Financeiro Inteligente

Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda

O Financeiro Inteligente é o produto de gestão financeira da Kobana, com contas a receber e cadastro de pessoas. Conectado ao Dunning, ele alimenta a régua com os recebíveis em aberto — os clientes e os títulos entram automaticamente na sua operação de cobrança.

Pré-requisitos

• Uma conta no Financeiro Inteligente com pessoas e contas a receber.
• Um token de acesso (access token) da API do Financeiro Inteligente.

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 Financeiro Inteligente usa chave estática — você cola um token, sem redirecionamento.

1. No painel do Financeiro Inteligente, copie o token de acesso.
2. No Dunning, abra Configurações → Integrações e escolha o Financeiro Inteligente.
3. Cole o token de acesso 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. A primeira sincronização roda logo após conectar; as seguintes acontecem automaticamente.

De → Para: como os campos são mapeados

Campo no Financeiro Inteligente	Campo no Dunning
Conta a receber (receivable)	Cobrança
amount	Valor original
nominal_amount	Valor atual
ticket_amount (liquidado no banco)	Valor pago
due_date	Vencimento
document_date / created_at	Data de emissão
payment_date	Data do pagamento
document_number / document	Número do documento
description (+ nº da parcela)	Descrição
payment_method_kind (bank_billet→boleto, pix→pix, credit_card, ted→transfer…)	Meio de pagamento
Status pending	pending (ou overdue se vencida)
Status received	paid (baixa + saída da régua)
Status cancelled	cancelled
Pessoa (cliente)	Pessoa na carteira
document_number, name, legal_name	Documento, nome, razão social
emails, phones	E-mails e telefones da pessoa

Pull-only

A API do Financeiro Inteligente não expõe webhooks, então a integração é somente leitura por pull: o Dunning busca os recebíveis na sincronização automática (a cada 60 min por padrão) e na sincronização manual, pelo botão de sincronizar. Cada execução é idempotente — reprocessar não duplica títulos. Um recebível pago dá baixa na cobrança e a retira da régua; um cancelado sai definitivamente. Cobranças já finais localmente (pagas ou canceladas) não têm seus valores sobrescritos pela origem.

O que não faz / limitações

• Não emite recebíveis. A criação continua no Financeiro Inteligente.
• Não escreve de volta. É pull-only: baixar ou cancelar no Dunning não altera o recebível de origem.
• Sem tempo real. Sem webhooks, pagamentos e cancelamentos aparecem no máximo no próximo ciclo de sincronização.

Como desconectar ou reconfigurar

Refaça o setup para trocar o token. Para rotacionar credenciais, gere um novo token no painel de origem e cole-o no Dunning; o antigo deixa de ser usado.

Solução de problemas

• A sincronização está desatualizada. Confira o intervalo (padrão 60 min) e clique em Sincronizar agora.
• Um recebível pago não deu baixa. Como não há webhook, a baixa depende do próximo pull — force com Sincronizar agora ou aguarde o ciclo.
• Um cliente não apareceu. O sync de pessoas roda junto com o de recebíveis; uma pessoa sem título é criada quando o primeiro recebível dela é sincronizado.
• Uma cobrança aparece duplicada. O Dunning deduplica por externalId (finance:receivable:{id}); duplicidade real só ocorre se o mesmo título vier de outra origem.
• A conexão caiu / token inválido. Gere um novo token no painel e reconecte.

Segurança

O token de acesso é cifrado em repouso e nunca é devolvido pela API. Toda chamada à API do Financeiro Inteligente é registrada no log de integração, para você auditar o que entrou e diagnosticar falhas de sincronização.