Conta Azul

Native integration · Read-only (pull) · Syncs automatically every 60 min (configurable) + on demand · OAuth connection

Conta Azul is a financial management and ERP platform for small businesses. Connected to Dunning, it brings the receivables and customers from your Conta Azul into the collection operation — the open charges become charges and the customers become people in your portfolio.

Prerequisites

• A Conta Azul account with customers and receivables.
• An OAuth application registered in Conta Azul's developer portal, with Dunning's callback URL and the access scopes for customers and receivables (see the requirement below).

How to connect

:::note No dedicated panel screen (yet) Today only the Kobana Gateway has a ready connect screen in the panel. For this ERP, the connection is made through the API (/api/v1/integrations/... routes) — the steps below describe the authorization flow; the equivalent self-service screen in the panel is on the roadmap. :::

Conta Azul uses OAuth2: you authorize access in Conta Azul itself, without pasting tokens by hand.

1. In Dunning, open Settings → Integrations and click Connect on Conta Azul.
2. Dunning generates a secure link and redirects you to the Conta Azul login screen.
3. Log in and review the consent screen with the requested scopes.
4. Authorize Dunning's access.
5. Conta Azul sends you back to Dunning already connected — the tokens are stored encrypted and the integration is active, with the first sync afterward.

Once connected, the token is renewed automatically; you only redo the "Connect" if access is revoked.

Field mapping (source → Dunning)

Conta Azul field	Dunning field
Receivable	Charge
total	Original amount
nao_pago (outstanding balance)	Current amount
pago	Amount paid
data_vencimento	Due date
data_competencia / data_criacao	Issue date
descricao	Description
Status EM_ABERTO / RECEBIDO_PARCIAL	pending (or overdue if past due)
Status ATRASADO	overdue
Status RECEBIDO	paid (settlement + exit from the collection rule)
Status RENEGOCIADO / PERDIDO	cancelled (exit the collection rule)
Customer	Person in the portfolio
documento, nome, tipo_pessoa	Document, name, type (individual/company)

note

The Conta Azul receivable does not bring the customer's document or the payment date in this resource, and does not expose a digitable line/Pix. The charge is linked to the person by the customer identifier; when the status is "received", the payment date is assumed to be the moment of settlement.

Synchronization

Synchronization is idempotent and runs automatically (every 60 min by default) and manually (sync button). Customers and receivables are synced in the same cycle.

What it does not do / limitations

• Does not issue charges or write back to Conta Azul — it is pull-only.
• No webhooks. Changes appear at most on the next sync cycle.
• No digitable line/Pix coming from the source in this resource — payment is tracked via status.
• Renegotiated charges exit the collection rule (renegotiation generates a new charge at the source) and lost ones exit as an accounting write-off.

Requirement: OAuth application in Conta Azul

"Connect" depends on an OAuth application registered in Conta Azul's developer portal, with Dunning's callback URL and the access scopes for customers and receivables. That application's credentials (client ID and client secret) can be configured globally in the Dunning environment or per integration. Without that application registered, the connection flow does not open.

Disconnecting or reauthorizing

If access is revoked (or you want to switch accounts), redo the "Connect" to reauthorize. While the connection is active, the token is renewed automatically.

Troubleshooting

• The sync is out of date. Check the interval (default 60 min) and click Sync now.
• The connection dropped. Access may have been revoked in Conta Azul — redo the "Connect".
• A customer did not appear. The customer sync runs alongside the receivables sync; a customer with no charge is created when their first charge is synced.
• A charge appears duplicated. Dunning deduplicates by externalId (contaazul:receivable:{id}); a real duplicate only occurs with the same charge coming from another source.
• "Connect" does not open. The OAuth application registered in Conta Azul is missing (or its credentials) — see the requirement above.

Security

The authorization link carries a signed state (anti-CSRF) with single use, the tokens are encrypted at rest and the token calls go to the log with the body redacted — code and secrets are never recorded.