Conta Azul
Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Conexão via OAuth
A Conta Azul é uma plataforma de gestão financeira e ERP para pequenas empresas. Conectada ao Dunning, ela traz as contas a receber e os clientes da sua Conta Azul para a operação de cobrança — os títulos em aberto viram cobranças e os clientes viram pessoas na sua carteira.
Pré-requisitos
- Uma conta na Conta Azul com clientes e contas a receber.
- Um aplicativo OAuth cadastrado no portal de desenvolvedores da Conta Azul, com a URL de callback do Dunning e os escopos de acesso a clientes e contas a receber (veja a pendência abaixo).
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.
:::
A Conta Azul usa OAuth2: você autoriza o acesso na própria Conta Azul, sem colar tokens à mão.
- No Dunning, abra Configurações → Integrações e clique em Conectar na Conta Azul.
- O Dunning gera um link seguro e redireciona você para a tela de login da Conta Azul.
- Faça login e revise a tela de consentimento com os escopos solicitados.
- Autorize o acesso do Dunning.
- A Conta Azul devolve você ao Dunning já conectado — os tokens ficam gravados cifrados e a integração fica ativa, com a primeira sincronização em seguida.
Depois de conectada, o token é renovado automaticamente; você só refaz o "Conectar" se o acesso for revogado.
De → Para: como os campos são mapeados
| Campo na Conta Azul | Campo no Dunning |
|---|---|
| Conta a receber | Cobrança |
total | Valor original |
nao_pago (saldo devedor) | Valor atual |
pago | Valor pago |
data_vencimento | Vencimento |
data_competencia / data_criacao | Data de emissão |
descricao | Descrição |
Status EM_ABERTO / RECEBIDO_PARCIAL | pending (ou overdue se vencida) |
Status ATRASADO | overdue |
Status RECEBIDO | paid (baixa + saída da régua) |
Status RENEGOCIADO / PERDIDO | cancelled (saem da régua) |
| Cliente | Pessoa na carteira |
documento, nome, tipo_pessoa | Documento, nome, tipo (PF/PJ) |
A conta a receber da Conta Azul não traz o documento do cliente nem a data de pagamento nesse recurso, e não expõe linha digitável/Pix. O vínculo do título com a pessoa é feito pelo identificador do cliente; quando o status é "recebido", a data do pagamento é assumida como o momento da baixa.
Sincronização
A sincronização é idempotente e roda de forma automática (a cada 60 min por padrão) e manual (botão de sincronizar). Clientes e contas a receber são sincronizados no mesmo ciclo.
O que não faz / limitações
- Não emite títulos nem escreve de volta na Conta Azul — é pull-only.
- Sem webhooks. As mudanças aparecem no máximo no próximo ciclo de sincronização.
- Sem linha digitável/Pix vindos da origem nesse recurso — o pagamento é acompanhado pelo status.
- Títulos renegociados saem da régua (a renegociação gera um novo título na origem) e perdidos saem como baixa contábil.
Pendência: aplicativo OAuth na Conta Azul
O "Conectar" depende de um aplicativo OAuth cadastrado no portal de desenvolvedores da Conta Azul, com a URL de callback do Dunning e os escopos de acesso a clientes e contas a receber. As credenciais desse aplicativo (client ID e client secret) podem ser configuradas globalmente no ambiente do Dunning ou por integração. Sem esse aplicativo cadastrado, o fluxo de conexão não abre.
Como desconectar ou reautorizar
Se o acesso for revogado (ou você quiser trocar de conta), refaça o "Conectar" para reautorizar. Enquanto a conexão está ativa, o token é renovado automaticamente.
Solução de problemas
- A sincronização está desatualizada. Confira o intervalo (padrão 60 min) e clique em Sincronizar agora.
- A conexão caiu. O acesso pode ter sido revogado na Conta Azul — refaça o "Conectar".
- Um cliente não apareceu. O sync de clientes roda junto com o de contas a receber; um cliente sem título é criado quando o primeiro título dele é sincronizado.
- Uma cobrança aparece duplicada. O Dunning deduplica por
externalId(contaazul:receivable:{id}); duplicidade real só ocorre com a mesma cobrança vinda de outra origem. - O "Conectar" não abre. Falta o aplicativo OAuth cadastrado na Conta Azul (ou suas credenciais) — veja a pendência acima.
Segurança
O link de autorização carrega um state assinado (anti-CSRF) de uso único, os tokens são cifrados em repouso e as chamadas de token vão para o log com o corpo redigido — código e segredos nunca são registrados.