Pular para o conteúdo

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.enabled ligada 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_URL e ASAAS_WEBHOOK_TOKEN no ambiente — e o webhook cadastrado lá apontando para https://<api>/webhooks/billing/asaas/asaas com 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 (valor chave|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.

  1. Autorização com o QR inicial. Sem autorização ativa, cobrar uma fatura com pix_automatico cria a autorização (POST /pix/automatic/authorizations) com frequency do ciclo do plano (MONTHLY ou ANNUALLY), paymentCreationMode: MANUAL (a régua é nossa e cria cada ciclo, como no cartão: nada de cobrança dupla), retryPolicy: ALLOW_THREE_IN_SEVEN_DAYS e immediateQrCode com o valor da fatura. A tentativa (pixauto:<id>) guarda o QR: pagar o QR quita esta fatura e autoriza as próximas.
  2. 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.
  3. 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_CONFIRMED paga a fatura.
  4. Recusado no banco (saldo, limite): PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED marca 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.
  5. 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.
  6. 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):

  1. 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.
  2. A loja paga. O provedor manda o webhook → fatura paid, BillingPayment matched, assinatura active se estava atrasada/suspensa.
  3. 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.
  4. 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.
  5. 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.