Para equipe ilarika
Fatura e pagamento: como a loja paga e como o sistema fica sabendo
- Super AdminAssinaturasdetalheFaturas (ações e coluna "Nota fiscal")
- Super AdminAssinaturasNota fiscal de serviço (ligar, fila)
- Super AdminAssinaturasdetalheEditar titular
- conta.<domínio>/minha-assinaturaFaturas (links da nota)
Uma fatura aberta vira uma cobrança num provedor (Asaas ou manual). O provedor devolve o jeito de pagar (QR Pix copia e cola, boleto, link do cartão). Quando o dinheiro entra, o provedor avisa por webhook; se o aviso se perder, a reconciliação pergunta de hora em hora e o botão “já paguei” pergunta na hora. Pagou → fatura paga, pagamento casado e a assinatura volta a ativa.
Antes de começar
billing.enabledligada só muda quem emite fatura automaticamente (a régua, atraso-e-bloqueio.md). Cobrar uma fatura à mão pelo Super Admin funciona com ela desligada.- Asaas: chave de API, ambiente (sandbox ou produção) e token do webhook
em Super Admin › Configurações › Asaas (cobrança) (super-admin/asaas.md)
— ou, sem nada lá,
ASAAS_API_KEY,ASAAS_BASE_URLeASAAS_WEBHOOK_TOKENno ambiente — e o webhook cadastrado lá apontando parahttps://<api>/webhooks/billing/asaas/asaascom o mesmo token (docs/runbooks/cobranca.md). Sem isso, o provedor padrão é o manual. - Manual: chave Pix da plataforma em
PlatformSetting billing.manual.pix(valorchave|Nome do favorecido). O QR gerado leva o número da fatura.
Meios por provedor
| Provedor | Pix | Boleto | Cartão (token) | Pix Automático |
|---|---|---|---|---|
| Asaas | sim | sim (só pelo Super Admin) | sim | sim (autorização com QR inicial + cobrança no mandato) |
| Manual | QR estático da plataforma | não | não | não |
O que a loja vê. Na página da fatura (conta.<domínio>/pagar/:token) e em
“Minha assinatura”, a loja paga uma fatura em aberto por Pix ou cartão.
Boleto não é oferecido à loja (POST /public/faturas/:token/cobrar e
POST /t/me/assinatura/faturas/:id/cobrar recusam); o Super Admin ainda
pode emitir boleto por cobrar/reemitir, e esse boleto aparece na página
da fatura como cobrança pendente.
O servidor nunca guarda número de cartão: o checkout e “Minha assinatura”
mandam o cartão uma vez para virar token no Asaas (POST /creditCard/tokenize);
fica só o token, o final e a bandeira.
Pix Automático (Asaas, Jornada 3)
Liberado por Super Admin › Assinaturas › Pix Automático
(billing.pixAutomatico.enabled, nasce desligado; PUT /platform/billing/pix-automatico). O Asaas só aceita Pix Automático em conta
PJ com CNPJ ativo há 6 meses ou mais.
- Autorização com o QR inicial. Sem autorização ativa, cobrar uma fatura
com
pix_automaticocria a autorização (POST /pix/automatic/authorizations) comfrequencydo ciclo do plano (MONTHLYouANNUALLY),paymentCreationMode: MANUAL(a régua é nossa e cria cada ciclo, como no cartão: nada de cobrança dupla),retryPolicy: ALLOW_THREE_IN_SEVEN_DAYSeimmediateQrCodecom o valor da fatura. A tentativa (pixauto:<id>) guarda o QR: pagar o QR quita esta fatura e autoriza as próximas. - Ativa. Depois do pagamento, o banco do pagador confirma e chega
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED: a autorização vira a forma de pagamento da assinatura (substitui o cartão, se havia). O pagamento do QR (cobrança criada pelo próprio Asaas) casa com a fatura pelo cliente e pelo valor; se a ativação chegar antes, a fatura já fica paga por ela. - Ciclos seguintes. A régua emite a fatura em D-5 e cria a cobrança com
pixAutomaticAuthorizationId(precisa nascer de 2 a 10 dias úteis antes do vencimento). O banco debita no vencimento;PAYMENT_CONFIRMEDpaga a fatura. - Recusado no banco (saldo, limite):
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSEDmarca a tentativa como recusada; nas retentativas da régua (D+3, D+5) o sistema pede nova tentativa para o dia seguinte (POST /pix/automatic/paymentInstructions/{id}/retries, até 3 em 7 dias). Esgotou, a fatura segue a régua de atraso normal. - Pago por outro caminho (Pix ou cartão pela página da fatura): o débito agendado é cancelado no Asaas, para não cobrar duas vezes.
- Cancelado pelo pagador no banco, expirado ou recusado. A forma fica “cancelada” e a loja recebe WhatsApp e e-mail pedindo para escolher outra forma antes do próximo vencimento. Sem escolher, a fatura chega para pagar e a régua segue normal.
Passo a passo (Super Admin)
Em Super Admin › Assinaturas, abra a assinatura. Na tabela Faturas, cada fatura aberta tem as ações (só superadmin):
- Reemitir cobrança: escolha o meio (Pix (QR), Boleto, Cartão ou Pix automático) e confirme. As tentativas pendentes são canceladas e sai uma cobrança nova. “Pix automático” sem autorização ativa gera o QR que paga a fatura e autoriza as próximas.
- A loja paga. O provedor manda o webhook → fatura
paid,BillingPaymentmatched, assinaturaactivese estava atrasada/suspensa. - Não chegou? Consultar provedor pergunta ao gateway e aplica. A reconciliação faz o mesmo de hora em hora para toda tentativa pendente há mais de 1 h.
- Pagou por fora (Pix direto na conta, transferência)? Marcar paga, com a Referência do comprovante (id do Pix, número da transferência) e o motivo. Fica auditado com quem marcou.
- Fatura errada: Anular, com motivo. Fatura aberta não se edita; emite outra.
Por trás, POST /platform/billing/invoices/:id/cobrar (com meio e
provider opcional) reaproveita a tentativa pendente do mesmo meio, sem criar
QR em cima de QR.
O que acontece com cada evento do provedor
| Evento | Efeito |
|---|---|
| pagamento confirmado com tentativa casada | fatura paga, pagamento matched, assinatura reativada |
| pagamento confirmado sem tentativa casada | BillingPayment unmatched em “a reconciliar” (nada se perde) |
| recusado / vencido | tentativa failed / expired; a fatura continua aberta |
| instrução do Pix Automático recusada | tentativa failed com o motivo; a régua pede nova tentativa |
| estornado / chargeback | pagamento refunded / chargeback; nota na linha do tempo da assinatura; a régua decide |
| autorização de Pix Automático ativa | vira a forma de pagamento; a fatura do QR inicial fica paga |
| autorização cancelada / expirada / recusada | forma cancelada (ou o Pix Automático a caminho sai); loja avisada se ficou sem forma |
Todo webhook entra primeiro na caixa de entrada (billing_webhook_inbox),
com chave única por provedor e id do evento: repetição do gateway não gera
trabalho. Falhou ao aplicar, a linha fica com error;
POST /platform/billing/webhooks/:inboxId/reprocessar tenta de novo.
Nota fiscal de serviço (NFS-e)
Fatura paga gera uma nota fiscal de serviço da plataforma para a loja, emitida pelo Focus NFe (prefeitura do município da iLarika). Nada muda no pagamento: a nota é consequência, nunca condição.
Quando sai. Ao marcar a fatura paga (webhook, “já paguei” ou à mão), a
nota entra na fila billing-nfse. Só sai se Super Admin › Assinaturas ›
Nota fiscal de serviço estiver ligada e o emissor configurado no
ambiente da API (FOCUS_NFE_TOKEN, NFSE_*; docs/runbooks/cobranca.md,
seção 7). Nasce desligada.
O que não gera nota. Fatura sem valor (cortesia), loja de teste e fatura cujo titular não tem CPF/CNPJ válido. Esses casos ficam marcados na fatura (“Sem nota” com o motivo, ou “Erro: titular incompleto”) em vez de sumirem.
Tomador. É o titular da cobrança da assinatura (nome, CPF/CNPJ, e-mail e endereço). O checkout só pede cidade e UF; se a prefeitura exigir endereço completo e código IBGE, complete em detalhe da assinatura › Editar titular e clique em Reemitir nota.
Depois de autorizada. O número, o PDF e o XML aparecem na coluna “Nota
fiscal” do detalhe, em conta.<domínio>/minha-assinatura (lista de faturas) e
no link público da fatura paga; o dono e o e-mail de cobrança recebem um
e-mail com os links. A linha do tempo da assinatura ganha “Nota fiscal nº X
emitida”.
Ações do superadmin, por fatura paga.
| Ação | Quando aparece | O que faz |
|---|---|---|
| Emitir nota / Reemitir nota | sem nota, com erro, sem nota (pulada) ou cancelada | Nova tentativa com referência nova no emissor. |
| Consultar nota | processando | Pergunta ao emissor agora (a fila já faz isso sozinha: 1, 2, 4… min, até 1 h). |
| Reenviar nota por e-mail | autorizada | Manda de novo o e-mail com PDF e XML. |
| Cancelar nota | autorizada | Cancela na prefeitura com justificativa (alguns municípios só aceitam dentro de um prazo). |
Pagamento estornado ou chargeback tenta cancelar a nota sozinho; se a prefeitura recusar, o motivo fica no erro da nota para alguém decidir.
Painel “Nota fiscal de serviço” (em Super Admin › Assinaturas): quem emite, se é homologação (nota sem valor fiscal) ou produção, ligada ou não (interruptor Emitir nota fiscal ao pagar, que só liga com o emissor configurado), quantas autorizadas, na fila e com erro. Sincronizar agora roda a varredura que o servidor já faz de hora em hora (nota parada há mais de 10 min).
Perguntas comuns
A nota saiu com erro “titular incompleto”. E agora? Abra a assinatura, Editar titular, preencha CPF/CNPJ, nome e endereço (com código IBGE), e clique em Reemitir nota na fatura.
Dá para desligar sem perder nada? Sim: desligada, nenhuma fatura entra na fila. Ao religar, só as faturas pagas dali em diante geram nota; as antigas saem pelo botão Emitir nota em cada uma.
O Asaas manda e-mail de cobrança para a loja? Não: o cliente é criado com as notificações desligadas. A régua é nossa (atraso-e-bloqueio.md).
Posso trocar de gateway depois? Sim. Só apps/api/src/billing/provedores/
conhece o Asaas; outro adaptador que passe na suíte de contrato entra no
registro e vira padrão por PlatformSetting billing.provider.
