Bling
Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Conexão via OAuth
O Bling é um ERP muito usado por pequenas e médias empresas no Brasil. Conectado ao Dunning, ele traz as contas a receber e os contatos do seu Bling para dentro da operação de cobrança — os títulos em aberto viram cobranças, e os contatos viram pessoas na sua carteira.
Pré-requisitos
- Uma conta Bling com contatos e contas a receber.
- Um aplicativo OAuth cadastrado no portal de desenvolvedores do Bling, apontando para a URL de callback do Dunning (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.
:::
O Bling usa OAuth2: você autoriza o acesso dentro da própria conta Bling, sem colar tokens à mão.
- No Dunning, abra Configurações → Integrações e clique em Conectar no Bling.
- O Dunning gera um link seguro e redireciona você para o Bling.
- No Bling, faça login e revise a tela de consentimento com os acessos solicitados.
- Autorize o acesso do Dunning.
- O Bling devolve você ao Dunning já conectado — os tokens são gravados cifrados e a integração fica ativa, com a primeira sincronização logo em seguida.
A partir daí, o token é renovado automaticamente nos bastidores; você não precisa reconectar a cada expiração.
De → Para: como os campos são mapeados
| Campo no Bling | Campo no Dunning |
|---|---|
Conta a receber (contas/receber) | Cobrança |
valor | Valor original |
vencimento | Vencimento |
dataEmissao | Data de emissão |
dataPagamento | Data do pagamento |
numeroDocumento | Número do documento |
historico | Descrição |
linkBoleto | Linha digitável / URL de pagamento |
linkQRCodePix | Copia-e-cola Pix |
situacao 1 (aberto) / 7 (confirmado) / 3 (parcial) | pending (ou overdue se vencida) |
situacao 2 (recebido) | paid (baixa + saída da régua) |
situacao 5 (cancelado) | cancelled |
situacao 4 / 6 (devolvido) | ignorada (não é alvo de régua) |
Contato (contatos) | Pessoa na carteira |
numeroDocumento do contato | Documento da pessoa |
nome | Nome da pessoa |
Sincronização
A sincronização é idempotente e roda de duas formas: automática (a cada 60 min por padrão) e manual (botão de sincronizar). Contatos 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 no Bling — é pull-only.
- Sem webhooks. A API do Bling não expõe webhooks de contas a receber para aplicativos, então pagamentos e cancelamentos aparecem no máximo no próximo ciclo de sincronização.
- Contas com situação devolvida/parcial-devolvida ficam de fora, por não serem alvo de cobrança.
Pendência: aplicativo OAuth no Bling
Para o "Conectar" funcionar, é preciso haver um aplicativo OAuth cadastrado no portal de desenvolvedores do Bling, apontando para a URL de callback do Dunning. As credenciais desse aplicativo (client ID e client secret) podem ser configuradas de forma global no ambiente do Dunning ou informadas por integração, no caso de cada organização usar o seu próprio aplicativo. Sem esse aplicativo cadastrado, o fluxo de conexão não abre — é o passo de habilitação que fica a cargo de quem administra o Bling.
Como desconectar ou reautorizar
Se o acesso for revogado no Bling (ou você quiser trocar de conta), basta refazer o "Conectar" — um novo consentimento gera tokens novos. Enquanto a conexão estiver ativa, a renovação do token é automática; você só reautoriza quando o refresh token deixa de valer.
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 no Bling ou o refresh token expirou — refaça o "Conectar" para reautorizar.
- Um contato não apareceu. O sync de contatos roda junto com o de contas a receber; um contato sem título é criado quando o primeiro título dele é sincronizado.
- Uma cobrança aparece duplicada. O Dunning deduplica por
externalId(bling: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 no Bling (ou as credenciais do app não estão configuradas) — veja a pendência acima.
Segurança
Todo o fluxo é protegido: o link de autorização carrega um state assinado (anti-CSRF) com uso único, os tokens são cifrados em repouso e as chamadas de token são registradas com o corpo redigido — código e segredos nunca aparecem no log.