# 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é 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](https://developers.contaazul.com/guide)
* **API Legada:** [https://devdocs.contaazul.com/](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/auth](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 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.

## Referência: De <> PARA

| 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.

### ⚠️ **Atenção: Migração da API -  alteração de ID's**

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.

#### **Por que isso é importante?**

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.

#### Exemplo contexto de Pessoas:

pessoasidlegado.png
#### Exemplo contexto de Produtos:

produtosidlegado.png
#### Exemplo contexto de Vendas:

vendas_idlegado.png