Faturamento Automático

Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Baixa em tempo real por webhook

O Faturamento Automático é o produto de assinaturas e faturamento recorrente da Kobana. Quando a sua operação fatura por lá, o Dunning conecta-se a ele para cobrar as faturas em aberto — trazendo os clientes e as faturas geradas para dentro da régua, do portal e dos acordos.

Pré-requisitos

• Uma conta no Faturamento Automático com clientes e faturas.
• Um token de API (API token) do Faturamento Automático.
• Acesso ao painel do Faturamento Automático para cadastrar o webhook entrante (opcional, mas recomendado para baixa em tempo real).

Como conectar

:::note Sem tela dedicada no painel (ainda) Hoje só o Gateway da Kobana tem tela de conexão pronta no painel. Para este ERP, a conexão é feita pela API (rotas /api/v1/integrations/...) — o passo a passo abaixo descreve o fluxo de autorização; a tela self-service equivalente no painel está no roadmap. :::

O Faturamento Automático usa chave estática — você cola um token, sem redirecionamento.

1. No painel do Faturamento Automático, copie o token de API.
2. No Dunning, abra Configurações → Integrações e escolha o Faturamento Automático.
3. Cole o token de API e selecione o ambiente (produção ou sandbox).
4. Clique em Conectar. O Dunning valida o token com uma chamada de teste; um token inválido é recusado antes de salvar.
5. Para a baixa em tempo real: o setup devolve a URL de webhook do Dunning. Cadastre um webhook no painel do Faturamento Automático apontando para essa URL e cole o signing secret do endpoint no campo indicado — é ele que valida a assinatura de cada entrega.

De → Para: como os campos são mapeados

Campo no Faturamento Automático	Campo no Dunning
Fatura (invoice)	Cobrança
total	Valor original
amount_remaining (saldo em aberto)	Valor atual
amount_paid / paid_at	Valor pago / data do pagamento
due_date	Vencimento
finalized_at / created_at	Data de emissão
number	Número do documento
hosted_invoice_url / invoice_pdf_url	URL de pagamento
Status open	pending (ou overdue se vencida)
Status paid	paid (baixa + saída da régua)
Status void / uncollectible	cancelled (write-off sai da régua)
Status draft	ignorada (ainda não é cobrável)
Cliente da conta de cobrança	Pessoa na carteira
document_number, name, legal_name	Documento, nome, razão social
emails, phones	E-mails e telefones da pessoa
custom_metadata (campos personalizados)	customData.kobanaBilling.custom_metadata

Os campos personalizados (custom_metadata) que você define no Faturamento Automático, tanto no cliente quanto na fatura, viajam para o Dunning sob a chave customData.kobanaBilling. A sincronização mescla esse bloco e preserva o restante do customData da pessoa/cobrança — ou seja, campos que você tenha definido pela API do Dunning não são sobrescritos a cada rodada de sync.

Tempo real e pull

Quando uma fatura é paga, o Dunning dá baixa na cobrança e a retira da régua; faturas canceladas (void/uncollectible) saem definitivamente. Com o webhook cadastrado, essas mudanças chegam em tempo real (invoice.paid, invoice.voided, entre outros); sem ele, a sincronização a cada 60 min (ou o botão de sincronizar) mantém tudo consistente.

O que não faz / limitações

• Não emite faturas. A emissão e a régua de faturamento continuam no Faturamento Automático.
• Não escreve de volta. É pull-only: baixar ou cancelar no Dunning não altera a fatura de origem.
• Faturas em rascunho não entram enquanto não forem finalizadas.
• Sem webhook, há atraso de até um ciclo de sincronização.

Como desconectar ou reconfigurar

Refaça o setup para trocar o token. Uma reconfiguração sem informar o signing secret não apaga o segredo já cadastrado — evita derrubar em silêncio a validação de assinatura dos webhooks. Para rotacionar credenciais, gere um novo token/endpoint no painel de origem e atualize no Dunning.

Solução de problemas

• A sincronização está desatualizada. Confira o intervalo (padrão 60 min) e use Sincronizar agora.
• Uma fatura paga não deu baixa. Verifique no log de integração se o webhook invoice.paid chegou e se o signing secret está correto; sem webhook, o próximo pull regulariza.
• Um cliente não apareceu. O sync de clientes roda junto; contas de cobrança sem cliente associado são puladas.
• Uma cobrança aparece duplicada. O Dunning deduplica por externalId (billing:invoice:{id}); duplicidade real só ocorre se o mesmo título vier de outra origem.
• Webhooks retornam erro de assinatura. O signing secret cadastrado no Dunning não bate com o do endpoint — recadastre o secret no setup/reconfiguração.

Segurança

O token de API é cifrado em repouso e nunca é devolvido pela API. O signing secret dos webhooks é preservado entre reconfigurações para não interromper a validação de assinatura.