Guia de Migração: API Legada para Nova API Conta Azul

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é 20 de Outubro de 2025.

Após 20 de Outubro de 2025, a API legada será 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/

Sobre Credenciais

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:

1. Criação de Conta de Desenvolvedor: Crie uma conta no Portal do Desenvolvedor, que permite gerenciar todas as suas aplicações integradas.

2. Criação de Nova Aplicação: Faça login no Portal, clique em "Nova Aplicação" e siga o passo a passo.

3. Obtenção de Credenciais: Ao criar a aplicação, você receberá o client_id e o client_secret. Estas credenciais são cruciais para o fluxo de autenticação OAuth2 e para gerar seu access_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/guide

Autenticação

Nova API

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_id e client_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 o access_token quando 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.

Suporte

Para qualquer dúvida, problema ou necessidade de assistência durante a migração ou desenvolvimento com a nova API, encaminhe um e-mail para api@contaazul.com. Nosso time entrará em contato para solucionar e dar suporte na migração, garantindo que você tenha o apoio necessário durante todo o processo.

Referência: De <> PARA

Obs.: O endpoint do contexto Plans foi descontinuado na nova API.