Em março de 2025, a Conta Azul lançou uma nova versão da API — mais completa, escalável e com mais endpoints disponíveis. A versão anterior da API foi descontinuada e está programada para ser desativada. Novas integrações devem ser criadas exclusivamente na versão atual.
Se você desenvolveu uma integração com a versão antiga e está recebendo erros como invalid_token ou 401 Unauthorized, ou se está procurando um endpoint que usava antes e não encontra mais, este artigo explica as principais diferenças e o que você precisa ajustar.
Qual é a diferença entre a API antiga e a API atual?
As duas versões são independentes: têm URLs de base diferentes, portais de acesso separados e fluxos de autenticação distintos.
Não é possível migrar uma conta da versão antiga para a nova: é necessário criar uma nova conta no Portal do Desenvolvedor atual e recriar a aplicação.
-
API antiga (v1 legada): URL base
https://api.contaazul.com/— descontinuada, sendo desativada em breve. Não aceita novas aplicações.
-
API atual (v2): URL base
https://api-v2.contaazul.com/— versão oficial e ativa. Toda integração nova deve usar esta base.
Alerta!
Chamadas feitas para a URL base da API antiga (https://api.contaazul.com/v1/) retornam invalid_token mesmo com token válido, porque a API legada foi descontinuada e não é compatível com as credenciais geradas no portal atual.
Se você está recebendo esse erro, verifique se está usando a URL correta da API v2.
Principais mudanças nos endpoints
Alguns recursos que existiam na API antiga foram renomeados ou reorganizados na versão atual.
Os mais citados nos atendimentos de suporte:
-
Clientes: na API antiga era
GET /v1/customers. Na API atual, clientes fazem parte do recurso de pessoas:GET https://api-v2.contaazul.com/v1/pessoas.
-
Escopo de autenticação: na API antiga, o scope variava (ex.:
sales,customers,financial.read). Na API atual, o scope é fixo:openid+profile+aws.cognito.signin.user.admin.
-
Endpoint de autorização OAuth: na API antiga era
http://api.contaazul.com/auth/authorize. Na API atual, siga o fluxo OAuth 2.0 (Authorization Code) conforme a documentação oficial.
-
Fluxo de caixa (
/cashflow): não existe endpoint equivalente na API atual. Para compor um fluxo de caixa, utilize os recursos financeiros disponíveis: contas a pagar, contas a receber, contas financeiras e parcelas.
-
Hierarquia de categorias: na API antiga retornava campos "Nível 1/2/3". Na API atual, use o campo
categoria_paino endpointGET https://api-v2.contaazul.com/v1/categoriaspara montar a hierarquia.
Importante!
Para paginação na API atual, os parâmetros são pagina e tamanho_pagina (não page como na versão antiga). Filtros devem ser enviados via query string, não no body da requisição.
A maioria dos endpoints de busca usa o método GET.
Como migrar para a API atual
- Acesse o Portal do Desenvolvedor atual e crie uma nova conta de desenvolvedor usando um e-mail válido.
- Crie uma nova aplicação no portal e gere as credenciais (Client ID e Client Secret).
- Implemente o fluxo de autenticação OAuth 2.0 (Authorization Code) conforme a documentação oficial.
- Atualize a URL base de todas as chamadas de API para
https://api-v2.contaazul.com/.
- Revise os endpoints utilizados na integração antiga e verifique os equivalentes na documentação da API atual.
- Para dúvidas técnicas específicas sobre equivalência de endpoints, acesse o Portal do Desenvolvedor e use o chat exclusivo com o time técnico.
Dica!
A documentação da API antiga ainda está acessível em devdocs.contaazul.com para consulta durante a migração.
Use-a como referência para identificar quais endpoints precisam ser atualizados.
Comentários
0 comentário