A Conta Azul lançou uma nova versão de suas APIs, e a recomendação é que todas as migrações de aplicações existentes na API legada sejam realizadas utilizando a nova documentação e seus recursos até 5 de novembro de 2025.
A API legada foi descontinuada e não será mais possível utilizá-la.
Esta nova versão visa proporcionar maior segurança, eficiência e flexibilidade para os desenvolvedores.
Referências das versões:
- Nova API: https://developers.contaazul.com/guide
- API Legada: https://devdocs.contaazul.com/
Para interagir com a nova API da Conta Azul, você precisará obter as credenciais necessárias. É crucial entender que as credenciais utilizadas na API legada não são compatíveis e não devem ser utilizadas com a nova API. Você precisará gerar um novo conjunto de credenciais seguindo os passos abaixo:
Criação de Conta de Desenvolvedor: Crie uma conta no Portal do Desenvolvedor, que permite gerenciar todas as suas aplicações integradas.
Criação de Nova Aplicação: Faça login no Portal, clique em "Nova Aplicação" e siga o passo a passo.
Obtenção de Credenciais: Ao criar a aplicação, você receberá o
client_ide oclient_secret. Estas credenciais são cruciais para o fluxo de autenticação OAuth2 e para gerar seuaccess_token. Elas podem ser consultadas a qualquer momento na seção "Minhas Aplicações". Um usuário e senha de teste para o Conta Azul Pro (ERP) também são fornecidos para validação da integração.
Para mais detalhes, siga este guia: https://developers.contaazul.com/auth
A nova API da Conta Azul utiliza o padrão de autenticação OAuth2, um protocolo seguro para autorização.
Fluxo OAuth2: O processo de autenticação envolve a utilização do
client_ideclient_secret(obtidos na etapa de credenciais) para iniciar o fluxo OAuth2.Geração de Tokens: Através deste fluxo, você obterá dois tokens essenciais:
access_token: Utilizado para realizar requisições à API. Este token tem um tempo de vida limitado.refresh_token: Utilizado para renovar oaccess_tokenquando ele expirar, sem a necessidade de o usuário passar pelo processo de autenticação novamente.
Escopos (Diferença para a Nova API): Na nova API, o escopo a ser utilizado é um parâmetro fixo:
openid profile aws.cognito.signin.user.admin. Ao utilizar este escopo, você não precisará definir outros escopos adicionais, e o desenvolvedor terá acesso a todos os contextos da API. Essa abordagem simplifica a gestão de permissões para a maioria dos casos de uso.
Para um entendimento completo do fluxo OAuth2 e detalhes de como gerar e gerenciar seus tokens, consulte a seção "Autenticação" na documentação da nova API.
Para qualquer dúvida, problema ou necessidade de assistência durante a migração ou o desenvolvimento com a nova API, encaminhe um e-mail para api@contaazul.com . Nosso time entrará em contato para oferecer suporte e garantir que você tenha todo o apoio necessário durante o processo. Além disso, você também pode acessar o nosso Chat pelo Portal do Desenvolvedor para tirar dúvidas e obter orientações sobre o uso das APIs.
| API Legada | Nova API |
|---|---|
| Product | Produtos |
| Service | Serviços |
| Contract-beta | Contratos |
| Sale | Vendas |
| Customer | Pessoas |
| Suplier-beta | Pessoas |
Obs.: O endpoint do contexto Plans foi descontinuado na nova API.
Se sua equipe está migrando da API antiga da Conta Azul, é fundamental ter atenção redobrada com os IDs de Produtos, Vendas e Pessoas.
Na nova versão da API, os IDs desses recursos foram alterados. Para garantir uma transição suave e evitar inconsistências, você deve realizar o de-para utilizando o campo id_legado, que está presente nos objetos de retorno.
O id_legado funciona como uma ponte entre a versão antiga e a nova, permitindo que você continue referenciando os recursos corretos em suas aplicações. Ignorar essa etapa pode levar a erros de sincronização e perda de dados, comprometendo a integridade da sua integração.
Portanto, certifique-se de atualizar sua lógica para mapear os IDs antigos para os novos, utilizando o id_legado como referência.
