Integrações

As integrações conectam o Dunning aos sistemas onde as suas cobranças já nascem — o Gateway da Kobana, os produtos irmãos de Faturamento e Financeiro, e ERPs de mercado como Bling, Conta Azul, Omie e Olist/Tiny. Em vez de recadastrar títulos à mão, você conecta a origem uma vez e o Dunning passa a puxar as cobranças e os clientes de lá para cobrar por eles com a régua, o portal e os acordos.

Como funciona

O modelo é pull idempotente: o Dunning lê a fonte externa e traz o que existe lá para dentro. Cada sincronização:

• Vincula o cliente da origem a uma pessoa da sua carteira — primeiro pelo identificador externo, depois pelo CPF/CNPJ normalizado. Quando não há correspondência, cria uma pessoa mínima para não perder o título.
• Cria ou atualiza a cobrança no Dunning a partir da conta a receber (ou boleto/fatura) da origem.
• Não duplica: cada título carrega um externalId prefixado pela origem (ex.: bling:receivable:123). Rodar o sync de novo atualiza o mesmo registro em vez de criar um novo.

Quando a origem informa que um título foi pago, o Dunning reaproveita o próprio fluxo de baixa — a cobrança é marcada como paga e sai da régua. Quando informa cancelamento, a cobrança sai definitivamente da régua. Cobranças que já estão em estado final localmente (pagas ou canceladas) não têm valor nem vencimento sobrescritos pela origem.

Sincronização automática e manual

Cada integração ativa é sincronizada automaticamente a cada 60 minutos por padrão. Esse intervalo é configurável por integração (ele vive no cadastro de cada conexão), e a sincronização automática pode ser desligada. Além do ciclo automático, você pode sincronizar sob demanda a qualquer momento, pelo botão de sincronizar.

Os produtos que suportam webhooks — o Gateway da Kobana e o Faturamento Automático — recebem os eventos em tempo real, sem esperar o próximo ciclo: um pagamento no boleto reflete no Dunning em segundos. Os ERPs (Bling, Conta Azul, Omie, Olist) não expõem webhooks e dependem do ciclo de sincronização — a mudança aparece no máximo no próximo sync.

Qual integração para quê

Integração	O que puxa	Autenticação	Tempo real
Gateway da Kobana	Clientes + boletos e Pix	Token de acesso	Webhook + pull
Faturamento Automático	Clientes + faturas	Token de API	Webhook + pull
Financeiro Inteligente	Pessoas + contas a receber	Token de acesso	Somente pull
Bling	Contatos + contas a receber	OAuth ("Conectar")	Somente pull
Conta Azul	Clientes + contas a receber	OAuth ("Conectar")	Somente pull
Omie	Clientes + contas a receber	Chave estática (app key/secret)	Somente pull
Olist (Tiny)	Contatos + contas a receber	OAuth ("Conectar")	Somente pull

:::note Conexão pelo painel: só o Gateway da Kobana (hoje) Das integrações acima, apenas o Gateway da Kobana tem uma tela de conexão pronta no painel. As demais (Faturamento, Financeiro, Bling, Conta Azul, Omie, Olist) são hoje configuradas pela API (/api/v1/integrations/...); a tela self-service equivalente no painel está no roadmap. A sincronização, os logs e a segurança descritos abaixo valem para todas. :::

Registro de tudo

Toda chamada a um sistema externo — e todo webhook recebido — é gravada em um log de integração: método, endpoint, status, duração e erro. É a trilha que responde "o título entrou?", "por que a última sincronização falhou?" ou "o webhook chegou?". Segredos nunca entram no log: corpos de autenticação são redigidos e tokens jamais são registrados.

Segurança das credenciais

As credenciais de cada integração (tokens de acesso, chaves de aplicativo, tokens OAuth) são cifradas em repouso. A gravação é fail-closed: se a cifra falhar, a operação é abortada em vez de gravar um segredo em texto puro. Nenhuma rota da API devolve as credenciais de uma integração.

O que as integrações não fazem

O Dunning cobra a partir do dado que recebe — ele não emite um boleto ou uma fatura em cima de um título de terceiro por conta própria. A emissão continua no sistema de origem; o Dunning entra depois, orquestrando a régua, o portal e os acordos sobre as cobranças sincronizadas. As integrações de ERP são pull-only (somente leitura da origem): o Dunning lê os títulos, mas não escreve de volta no ERP.