Assinaturas e faturas recorrentes

A recorrencia do Minstrel separa tres coisas que costumam vir misturadas:

• plano: o preco e o ritmo ("R$ 149,90 por mes, cobrado no inicio");
• assinatura: o contrato de um cliente com um plano;
• fatura: a intencao de cobrar um ciclo. E ela que e cobrada, retentada e avisada pela regua - nunca a assinatura direto.

Escolha o fluxo antes da primeira cobranca

Fatura avulsa paga nao vira assinatura. Para mensalidades de academia, SaaS ou outros servicos continuos, integre a assinatura desde a adesao. Gerar uma nova fatura avulsa todo mes e tentar cobrar o cartao do pagamento anterior nao estabelece um acordo de recorrencia.

No exemplo de uma academia, o aluno precisa aceitar a mensalidade e sua periodicidade antes das cobrancas automaticas. O aceite para salvar o cartao e o acordo para debitar mensalidades devem ser claros: guardar o cartao para compras futuras nao autoriza, por si so, uma assinatura.

Para simplificar a integracao, use Assinatura por link: o painel permite simular a adesão sem cartão. O fluxo real por link está indisponível até homologação de checkout integralmente hospedado pelo parceiro, com token reutilizável e os identificadores de recorrência necessários. Esse fluxo tem um recurso proprio (subscription_link); o link de uma fatura avulsa continua sendo pontual.

Escolher onde cobrar

No painel, Nova assinatura → Onde cobrar permite escolher a conta de adquirente, subadquirente ou gateway. O cartão exibido deve ser compatível com essa conta. Um cartão salvo na Cielo matriz não se torna válido em outra conta Cielo ou no Mercado Pago só porque o usuário escolheu outro parceiro.

A API aceita connectorAccountId ao criar ou alterar a assinatura. A escolha vale para o primeiro pagamento e os ciclos seguintes, inclusive quando o fluxo tem outras contas candidatas. O fluxo continua aplicando suas regras de risco, mas o nó de rota usa somente a conta escolhida, sem fallback para outra conta.

Cada pagamento congela essa escolha em requestedConnectorAccountId. Alterações posteriores na assinatura afetam novas cobranças; captura, estorno e pagamentos já iniciados mantêm a conta original. No detalhe da assinatura, Onde cobrar → Trocar permite escolher conta e cartão juntos.

Para integrações antigas que omitem a conta, o cartão de cofre vinculado fornece a conta de origem; registros legados sem escolha continuam com o roteamento configurado. Tokens de bandeira só podem mudar de adquirente quando o conector suporta essa portabilidade.

Cartao salvo, consentimento e identificadores

Para integrar a recorrencia:

1. Apresente o valor, a periodicidade, o inicio e as condicoes de cancelamento da assinatura; registre o aceite do cliente.
2. Cadastre o cartão em uma página hospedada pelo parceiro, com consentimento para armazenamento e cobrancas futuras. Use um token reutilizavel vinculado ao cliente; um token de uso unico nao serve para os proximos ciclos.
3. Crie a assinatura com customerId, planId, paymentMethodId e connectorAccountId. A primeira cobranca iniciada pelo portador deve acontecer durante uma acao real dele. Marcar uma chamada de servidor como CIT nao torna o cliente presente.
4. Acompanhe os eventos de assinatura e fatura pelos webhooks, inclusive recusas, cancelamentos e troca de cartao.

Os campos das adquirentes cumprem papeis diferentes:

A Rede explica os indicadores de recorrencia e credencial armazenada. Na Cielo, o TLID complementa o IssuerTransactionId: quando disponiveis, ambos devem ser preservados conforme sua finalidade. O TLID original deve continuar sendo referenciado, mesmo que cobrancas seguintes retornem novos valores. Consulte os identificadores de bandeira da Cielo.

No fluxo de cartao salvo, o Minstrel guarda os identificadores retornados e prepara as marcacoes conforme o conector. A integracao do cliente continua responsavel por iniciar o fluxo correto e obter o consentimento; enviar um identificador de uma compra avulsa nao transforma essa compra em uma adesao. Veja tambem as regras de recorrencia da Cielo.

Momento da cobranca

Cada plano define billingTiming:

curl https://api.minstrel.com.br/v1/plans \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_01HQ...",
    "name": "Mensal",
    "amount": 14990,
    "interval": "month",
    "billingTiming": "start",
    "trialDays": 7,
    "invoiceLeadDays": 3
  }'

invoiceLeadDays antecipa a geracao da fatura (nao a cobranca): a fatura nasce 3 dias antes do vencimento para a regua avisar o cliente antes de cobrar.

Ciclo de vida

No pre-pago, a assinatura so fica active quando a primeira fatura e paga. Ativar antes daria acesso a quem nao pagou - e a recusa no primeiro pagamento (cartao digitado errado, sem limite) e a mais comum de todas. O evento subscription.activated marca esse momento: use-o para liberar o acesso.

Criar uma assinatura

curl https://api.minstrel.com.br/v1/subscriptions \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: assinatura-cliente-1234" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "cus_01HQ...", "planId": "plan_01HQ..." }'

Num plano pre-pago sem teste, a resposta ja traz a primeira fatura e o resultado da cobranca:

{
  "id": "sub_01M4...",
  "status": "active",
  "latestInvoice": { "number": "2026-000123", "status": "paid", "total": 14990 },
  "firstCharge": { "outcome": "paid", "detail": "Fatura paga." }
}

A primeira cobranca vai como transacao com o cliente presente (CIT), que e o que o emissor espera no inicio de uma recorrencia; as seguintes vao como MIT recorrente. Com recusa, a assinatura fica incomplete e a fatura segue a politica de retentativa.

Geracao e virada de periodo

O worker de recorrencia faz duas coisas separadas, nessa ordem:

1. gera a proxima fatura quando chega a antecedencia do plano;
2. vira o periodo quando o atual termina - ou encerra a assinatura, se havia cancelamento agendado ou se o ultimo ciclo contratado acabou.

Separar os dois garante que "periodo atual" nunca aponte para o futuro e que um worker parado por dias recupere ciclo a ciclo, sem pular nenhuma fatura. Cada ciclo e faturado uma unica vez: o banco impede duas faturas para o mesmo ciclo, e uma fatura cancelada pelo operador conta como tratada.

GET /v1/subscriptions/:id devolve upcoming, o cronograma das proximas cobrancas com data de geracao, vencimento e valor. Para antecipar a proxima fatura manualmente, use POST /v1/subscriptions/:id/renew.

Valor proporcional

Com dia fixo de cobranca (billingDay), o primeiro periodo e mais curto que o intervalo - adesao em 25/03 num plano que cobra todo dia 10 gera um periodo de 16 dias. A fatura desse periodo e proporcional, arredondada a favor do cliente, e o item descreve a conta: Mensal - ciclo 1 (proporcional: 16 de 31 dias). O mesmo vale para a retomada de uma assinatura pausada.

Trocar o cartao

curl -X PATCH https://api.minstrel.com.br/v1/subscriptions/sub_01M4... \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -d '{ "paymentMethodId": "pm_01M4..." }'

As faturas vencidas e nao pagas voltam para a fila de cobranca na hora (rescheduledInvoices na resposta informa quantas) - a causa mais comum de atraso e justamente o cartao. O status da assinatura muda quando a fatura for paga, nao antes: trocar o cartao nao quita a divida.

Cancelar, pausar e retomar

• POST /v1/subscriptions/:id/cancel cancela ao fim do periodo por padrao: o cliente pagou pelo periodo inteiro, e cortar no meio gera contestacao. Envie { "atPeriodEnd": false } para encerrar na hora. Para desfazer um cancelamento agendado: PATCH com { "cancelAtPeriodEnd": false }.
• POST /v1/subscriptions/:id/pause suspende as cobrancas; faturas ja geradas para periodos que ainda nao comecaram sao canceladas.
• POST /v1/subscriptions/:id/resume abre um ciclo novo a partir de agora, em vez de cobrar o periodo em que o cliente ficou sem acesso.

Assinatura cancelada pelo emissor (Visa R0/R1/R3, Mastercard MAC 21) nao pode ser reativada com o mesmo cartao: crie uma nova com outro meio de pagamento.

Baixa manual

Dinheiro que entrou por fora (Pix direto na conta, deposito, acordo) e registrado na fatura sem criar transacao:

curl https://api.minstrel.com.br/v1/invoices/inv_01M4.../mark-paid \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: baixa-2026-000123" \
  -d '{ "note": "Pix recebido direto na conta em 14/10" }'

A fatura fica paid com paidOutOfBand: true e a nota informada, e a assinatura e reativada como numa cobranca aprovada. Faturas em processamento recusam a baixa: uma cobranca em voo pode ser aprovada a qualquer momento. Se havia um link de pagamento ativo, ele e cancelado na mesma hora (cancelReason: "invoice_paid"): o cliente nao paga duas vezes.

Fatura avulsa

POST /v1/invoices cria uma fatura sem assinatura - implantacao, servico extra, acordo de divida. Ela nao e cobrada sozinha: sem acordo de recorrencia, cobrar o cartao salvo do cliente por iniciativa da loja (MIT) e o tipo de cobranca que o emissor recusa ou que vira contestacao. A fatura nasce com nextAttemptAt: null e fica fora da fila do cobrador; o vencimento serve para a regua e para marcar atraso.

Para receber:

• envie um link de pagamento: o cliente paga na pagina do parceiro, com cartao, Pix ou boleto, numa transacao iniciada por ele (CIT);
• ou, com o cliente no seu checkout agora, cobre o cartao salvo dele marcando a presenca:

curl https://api.minstrel.com.br/v1/invoices/inv_01M4.../charge \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: cobranca-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{ "customerPresent": true }'

Sem customerPresent: true, a fatura avulsa responde 409 (invoice_not_payable), com o caminho do link em meta.paymentLinks. A recusa de uma cobranca avulsa nao agenda retentativa (noRetryReason: "standalone_invoice"): quem tenta de novo e o cliente, e a fatura segue em aberto.

Na fatura de assinatura, POST /v1/invoices/:id/charge continua igual: cobra o cartao salvo como MIT recorrente, e a recusa segue a politica de retentativa.

Regua de cobranca e seus modelos, por ambiente

A regua (/v1/dunning/rules) e os modelos de mensagem que ela envia (/v1/dunning/templates) sao independentes em cada ambiente. Com a chave de sandbox, voce lista, cria e edita so os modelos do sandbox; editar um texto de teste nunca muda o e-mail que o cliente final recebe em producao, e o contrario tambem vale.

• uma regra so aceita modelo do proprio ambiente: apontar para o de outro ambiente responde 404, igual a um id que nao existe;
• o mesmo nome de modelo pode existir nos dois ambientes (a unicidade e por organizacao, ambiente, nome e idioma);
• nada e copiado sozinho. Para ter o texto em producao, crie o modelo com a chave de producao.

Gere um cartao de teste com resultado fixo e assine um plano com ele:

curl https://api.minstrel.com.br/v1/customers/cus_01HQ.../payment-methods/test-card \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -d '{ "scenario": "51", "brand": "visa" }'

O cartao de teste so existe no sandbox e, como todo cartao no Minstrel, e um token: numero e CVV nunca trafegam pela API.

Indicadores

GET /v1/billing/summary devolve MRR, ARR, ticket medio, churn de 30 dias, assinaturas por status e faturas em aberto, vencidas, a vencer em 7 dias e pagas no mes. O MRR conta assinaturas active e past_due pelo valor negociado de cada uma, convertido para mes.