Conta

Financeiro da plataforma

Plano, transações processadas, benefícios, faturas e pagamentos da sua organização ao Minstrel.

Guia de integração · 6 min de leitura

Nesta página

O Financeiro reúne o que sua empresa paga ao Minstrel. As cobranças que você faz aos seus clientes ficam em Transações e Assinaturas.

A conta pertence à organização. Trocar sandbox por produção no painel não altera as faturas: somente o uso de produção é faturado. As consultas da API exigem billing:read.

Matriz e franquias

A matriz pode centralizar a cobrança de várias unidades. Nesse modelo, plano, franquia e faturas pertencem à matriz, e o uso das unidades é somado ao dela. Criar outra marca ou franquia não reinicia os 30 dias nem as 50 cobranças gratuitas. O saldo compartilhado aparece no topo das unidades vinculadas.

A equipe Minstrel pode definir quem recebe a cobrança de cada unidade:

Matriz: o uso novo entra na fatura da matriz.
Franquia: a unidade contrata condições próprias e recebe sua cobrança. A produção exige um contrato ativo ou benefício concedido pelo Minstrel.

A alteração vale a partir de sua vigência. O uso anterior continua com o responsável daquele momento; faturas fechadas não são transferidas nem recalculadas. Ao voltar à cobrança centralizada, o contrato próprio da unidade é encerrado nessa data. Anuidades já pagas e eventuais créditos são analisados separadamente pela equipe Minstrel.

O financeiro consolidado exige também acesso à matriz com billing:read. Um acesso apenas à franquia não dá acesso às faturas de outras unidades. Uma chave de API da unidade também não acessa o financeiro da matriz.

Teste gratuito

O cadastro concede 30 dias ou 50 novas cobranças de produção, o primeiro limite atingido. O prazo começa na criação da conta. Cada nova cobrança ou link consome uma unidade gratuita, inclusive se for recusada. Fallback e repetição idempotente do mesmo pagamento não gastam outro crédito do teste.

O menu superior mostra o prazo e o saldo. GET /v1/platform-billing/access permite consultar esses dados com payments:read. O sandbox continua gratuito. Ao terminar o teste, consultas, cancelamentos e estornos continuam disponíveis; novas cobranças em produção exigem um plano. Não há contratação automática.

Planos e contratação

Os preços atuais estão em Preços e em Financeiro → Plano da plataforma. Ambos usam GET /v1/platform-billing/catalog.

O proprietário pode aceitar um plano disponível para contratação online:

json

{
  "planCode": "start",
  "billingInterval": "monthly",
  "planVersion": 1,
  "acceptedTerms": true
}

Envie para POST /v1/platform-billing/subscribe com a sessão do proprietário. Use a versão retornada pelo catálogo para impedir aceite de preços que foram alterados enquanto a tela estava aberta. Chave de API não contrata planos.

Mensal: pós-pago, com fechamento no fim do mês e vencimento no dia do contrato, normalmente dia 10 do mês seguinte. Contratar encerra a gratuidade e inicia o plano pago. Mensalidade e franquia do primeiro mês são proporcionais.
Anual: dez mensalidades antecipadas cobrem doze meses. A anuidade aparece no Financeiro; a produção paga depende da quitação. Um teste ainda válido mantém seus próprios limites enquanto a anuidade estiver aberta. Uso variável é faturado mensalmente. O worker prepara a renovação nos 14 dias finais.

Contratar não debita um cartão. A fatura informa como pagar após a configuração dos dados reais de recebimento do Minstrel.

O que conta na fatura

Nos planos públicos, a unidade é a resposta de negócio processada:

Autorização aprovada ou recusada conta uma vez.
Cada fallback ou retentativa com resposta do parceiro conta outra unidade.
Pix e boleto contam na emissão. Confirmar o pagamento não cobra outra unidade, mesmo quando a confirmação ocorrer em outro mês.
Falha técnica sem resposta, bloqueio antes do parceiro, captura, cancelamento, estorno, repetição idempotente e sandbox não entram na contagem.
Pagamentos criados na gratuidade não entram na fatura posterior.

A franquia e o excedente usam essa mesma unidade. Não há uma segunda taxa de retentativa nos planos por processadas. Condições negociadas podem usar apenas aprovações (pricing.billingMetric = "approved"); confira o seu contrato. Os contratos anteriores mantêm suas condições até uma alteração explícita.

Serviços adicionais

Antifraude é contado por análise realizada, sem erros do provedor. Zero Auth conta verificações válidas ou inválidas com resposta, excluindo indisponibilidade e erro. Os preços unitários aparecem nas condições do plano.

Mensageria é opcional. A cobrança exige ativação e confirmação dos preços contratados. Só contam envios com identificação do provedor e envio realizado em produção; agendamento e falha não são faturados como mensagem enviada.

`kind`	Item
`monthly_fee`	Mensalidade, proporcional no primeiro mês e em revisões
`transactions`	Unidades acima da franquia contratada
`annual_fee`	Cobertura antecipada de doze meses
`antifraud` / `verification`	Análises antifraude / Zero Auth
`email_module`	Módulo mensal de e-mail contratado
`email` / `sms` / `whatsapp`	Envios realizados dos canais contratados
`volume` / `extra_attempts`	Condições específicas de contratos negociados
`manual`	Cobrança avulsa com descrição

Resumo e previsão

GET /v1/platform-billing/overview apresenta:

Campo	Conteúdo
`pricing`	Condições vigentes, unidade cobrada, periodicidade e cobertura anual
`current`	Uso de produção, franquia, linhas, subtotal, desconto e total parcial
`current.projection`	Estimativa até o fim do mês pelo ritmo observado
`previous` / `history`	Fatura anterior e histórico
`benefits`	Benefícios concedidos e suas vigências
`scheduledChanges`	Novas condições com início futuro
`sandbox`	Uso informativo, sem cobrança
`nextInvoice` / `outstanding`	Próxima fatura e saldo em aberto, descontados os recebimentos

A projeção usa os mesmos preços e benefícios do fechamento, respeitando as revisões do contrato. Uma projeção não é uma fatura emitida.

O mês segue Brasília (UTC−3), virando às 00h do dia 1. O fechamento ocorre após uma folga de duas horas e é idempotente: uma segunda execução devolve a mesma fatura. Faturas fechadas preservam as condições e os benefícios usados no cálculo. Alterar o catálogo de planos não altera contratos existentes.

Benefícios e alterações comerciais

Descontos percentuais, valores fixos e isenções podem valer para mensalidade, uso ou total, com prazo. A vigência dos benefícios é mensal. O Financeiro mostra o benefício pelo nome; faturas já emitidas mantêm seu histórico.

Mudanças de contrato podem entrar agora ou no próximo mês. Uma revisão imediata divide mensalidade e franquia entre os períodos de vigência. Solicite mudanças, isenções, ampliação de teste e cancelamento a contato@minstrel.com.br.

Faturas e pagamentos

GET /v1/platform-billing/invoices lista faturas com limit, startingAfter e filtro status. Anuidades, uso mensal e cobranças avulsas aparecem na lista.

`status`	Significado
`open`	Em aberto
`overdue`	Vencimento encerrado, com saldo
`paid`	Quitada por recebimentos confirmados
`waived`	Saldo dispensado por benefício ou ajuste
`void`	Cancelada

GET /v1/platform-billing/invoices/:id traz lines, subtotal, discount, total, amountPaid, balance, recebimentos e ajustes. O valor restante a pagar é balance, não o total original. Um pagamento parcial mantém a fatura aberta; isenção não é registrada como dinheiro recebido.

Enquanto houver saldo, paymentInstructions pode conter beneficiário, chave Pix, Pix copia e cola, boleto e instruções bancárias. Sem configuração, o campo é null. Confira o beneficiário antes de pagar. Apenas dados de demonstração antigos podem exibir sample: true; não pague instruções de exemplo.

A administração registra recebimentos após conferência e pode lançar descontos, isenções, acréscimos e cancelamentos com motivo. As baixas e os ajustes são idempotentes, preservam a trilha de auditoria e não podem exceder o saldo. A conciliação bancária automática depende de uma integração com o provedor cobrador.