Conta Azul de Bolso API integration (ERP & Open Finance Brasil)

Account login & OAuth refresh

Wraps the official Conta Azul OAuth 2.0 Authorization Code flow with PKCE, refresh-token rotation and idempotent token storage. Used to bind tenants in multi-account dashboards and to keep refresh windows alive within the documented 14-day refresh validity.

Statement & cash flow API

Exports contas a pagar, contas a receber, paid, scheduled and overdue rows by date range, account, status and supplier. The statement endpoint supports paging and JSON / Excel / PDF output, which is what accountants typically need for monthly closing.

Pix, boleto and card-via-link charges

Issues a single charge that customers can pay via Pix, boleto or card link. Receipts compensate in real time and the integration mirrors Conta Azul's automatic NFS-e emission on payment identification, so the downstream ERP receives both the receipt and the fiscal document.

NFe & NFS-e issuance

Covers product NFe and service NFS-e, including the 2024 export-only fields (Local de embarque, UF de embarque, Numero Drawback, Registro de exportacao, Chave da NFe recebida para exportacao) for clients that ship abroad.

DDA & supplier payments

Ingests boletos addressed to the company CNPJ via DDA, links them to contas a pagar, and lets your stack approve payment in batch (the 2024 batch-payments option in Conta PJ) or as a single scheduled transfer between own accounts or registered suppliers.

Open Finance Brasil consent

Manages the regulated Open Finance Brasil consent lifecycle: authorize, renew and revoke against Sicoob, Nubank, Banco do Brasil, Caixa and C6 Bank, and pulls D-1 transactions exposed by each bank, including weekend movements that PDF statements would push to Monday.

1. Accounting office multi-tenant sync

An accounting firm with hundreds of SMB clients on Conta Azul Pro needs nightly extractions of contas a pagar, contas a receber and NFe. We use the OAuth 2.0 Authorization Code flow per tenant, persist refresh tokens, and pull /v1/financeiro + /v1/nfe with date filters. Mapping aligns with the firm's chart of accounts and exports to Excel for the accountant's audit trail.

2. E-commerce reconciliation with Pix and NFS-e

A Shopify or VTEX store issues charges through Conta Azul de Bolso so a single link offers Pix, boleto or card. When payment compensates, the integration captures the webhook, calls the NFS-e endpoint, and posts both events back to the storefront's order so finance and operations stay aligned.

3. Treasury dashboard with Open Finance Brasil

A holding company with five CNPJs consolidates balances across Sicoob, Nubank, Banco do Brasil, Caixa and C6 Bank. We orchestrate the regulated Open Finance consent flow (including renewal before the 12-month expiry), normalize the D-1 movements from each ITP/AISP, and feed a Power BI dataset alongside the Conta Azul reconciled categories.

4. DDA-driven supplier payment batch

Finance teams that pay dozens of boletos per week consume the DDA inbox, match each bill to contas a pagar by CNPJ + due date, and submit a batch payment to Conta PJ — using the 2024 batch-finalization option — with cryptographically signed approval chains.

5. Compliance audit and consent log

A larger client must show ANPD evidence that every data pull has a legal basis. The integration produces an audit log of OAuth grants, Open Finance consents, and Pix limit changes (period, trusted contact, trusted company) so internal audit can answer LGPD information requests within the legal deadlines.

OAuth 2.0 Authorization Code (token refresh)

POST https://api.contaazul.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>

200 OK
{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "refresh_token": "v1.MUE5...",   // single-use, 14d validity
  "token_type": "bearer"
}

Statement query (financeiro)

GET /v1/financeiro/lancamentos
  ?status=PAGO,VENCIDO
  &data_inicio=2026-04-01
  &data_fim=2026-04-30
  &page=1&size=100
Authorization: Bearer <ACCESS_TOKEN>

200 OK
{
  "items": [
    {
      "id": "f3d8...",
      "tipo": "RECEITA",
      "valor": 1842.50,
      "data_pagamento": "2026-04-12",
      "categoria": "Vendas / Pix",
      "cliente_cnpj": "12.345.678/0001-90",
      "origem": "OPEN_FINANCE_BB"
    }
  ],
  "page": 1, "total": 412
}

Pix charge webhook

POST /webhook/contaazul-pix HTTP/1.1
X-CA-Signature: sha256=4f1c...

{
  "event": "cobranca.pago",
  "cobranca_id": "9f7a-4abc",
  "valor": 250.00,
  "metodo": "PIX",
  "txid": "E18236120202604121500u00",
  "pago_em": "2026-04-12T15:00:11-03:00",
  "nfse_emitida": true
}

Compliance & privacy

All data flows we deliver use the documented Conta Azul OAuth 2.0 API or the regulated Open Finance Brasil consent — no scraped session cookies, no shared credentials. We follow the Lei Geral de Protecao de Dados (Lei 13.709/2018) data-minimization rule, store consent records, log token refreshes, and produce ANPD-friendly audit trails. Penalties under LGPD reach 2% of revenue capped at R$50M per infraction, so a defensible legal basis is part of every delivery.

For Pix and DDA we align with current Banco Central rules, including the 2024-2025 Pix fraud verification step and the new Pix limit management (period, trusted contacts, trusted companies). Open Finance flows respect the 12-month consent renewal cycle and the per-bank scope catalog.

Modules we typically ship

• OAuth 2.0 client with PKCE and refresh-token rotation
• Pix / boleto / card-via-link charge service + webhook receiver
• NFe and NFS-e issuance with 2024 export fields
• DDA inbox processor matched to contas a pagar
• Open Finance Brasil consent, renewal and statement importer
• Conta PJ batch payment and scheduled transfer queue
• LGPD-ready audit log and consent registry

Bling

Cloud ERP popular with Brazilian e-commerce sellers. Holds orders, NFe, inventory and marketplace bridges; companies that bridge Bling and Conta Azul typically need a single SKU + CNPJ key to merge sales and accounting views.

Omie

Cloud ERP for SMBs with strong financial and accounting modules. Customers often consolidate Omie and Conta Azul cash-flow for a finance-team dashboard, mapping Omie boletos into Conta Azul contas a pagar.

Tiny ERP

E-commerce-focused ERP, recently part of the Olist group. Tiny exports of orders and NFe make it a common counterpart when migrating or running both systems during a transition window.

Eccosys

Higher-end ERP for larger e-commerce operations. Treasury teams crossing Eccosys and Conta Azul de Bolso usually need to align Pix and Open Finance receipts with multi-store sales feeds.

Nibo

Cloud platform aimed at accounting offices managing many SMB clients. Often paired with Conta Azul tenants when a firm wants a unified inbox of obligations across both providers.

ZeroPaper

Lightweight financial control tool for very small businesses. Migrators from ZeroPaper to Conta Azul Pro frequently ask for a one-shot importer that maps simple accounts into the Conta Azul chart of accounts.

QuickBooks Brasil

International accounting platform with a Brazilian footprint. International groups with subsidiaries on Conta Azul often want a consolidated trial balance that aligns Brazilian fiscal documents with QuickBooks.

Sage

Enterprise accounting suite used by some larger Brazilian operations. Pairs naturally with Conta Azul for audit trails when a holding company runs Sage at the top and Conta Azul Pro at the operating-company level.

FreshBooks

SaaS invoicing and time-tracking platform. International freelancers and agencies billing Brazilian clients often run FreshBooks for invoices and Conta Azul for fiscal documents and Pix receipts.

Dolibarr

Open-source ERP/CRM. Self-hosted Dolibarr deployments occasionally need an outbound adapter into Conta Azul de Bolso so accountants stay on a familiar interface even when operations live elsewhere.

Deliverables checklist

• API specification (OpenAPI / Swagger)
• Protocol and auth flow report (OAuth 2.0 + Open Finance Brasil consent)
• Runnable source for OAuth, financeiro, NFe and Pix endpoints (Python / Node.js)
• Webhook receiver and signature verification
• Reconciliation worker mapping bank movements to contas a pagar / receber
• Automated tests, sample payloads, and Postman collection
• LGPD compliance notes and consent log template

About us

We are an independent studio focused on fintech and OpenData/OpenBanking integrations. Our team includes engineers from Brazilian banks, payment institutions, ERP vendors and protocol-analysis backgrounds. We know LGPD, the BACEN Open Finance Brasil ruleset and the Conta Azul Pro plan structure, and we ship end-to-end APIs under those constraints.

• Brazilian SMB ERP and accounting integrations
• Pix, boleto, DDA and NFe pipelines
• Open Finance Brasil consent orchestration
• Source code delivery from $300 — runnable code and full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — access our hosted API and pay only per call, no upfront cost

Engagement workflow

1. Scope confirmation: which entities, plan tier, target banks for Open Finance.
2. OAuth 2.0 client registration and sandbox dry-run (1-2 business days).
3. Protocol analysis and API design (2-5 business days, depends on complexity).
4. Build and internal validation against a real Conta Azul Pro tenant (3-8 business days).
5. Docs, samples and reconciliation tests (1-2 business days).
6. Typical first delivery: 5-15 business days; multi-bank Open Finance flows may extend this.

FAQ

What do you need from me to start a Conta Azul de Bolso integration?

How long does delivery take?

How do you handle compliance with Brazilian rules?

Do you cover the new 2024-2025 features such as Pix limit management and batch payments?