Perguntas frequentes | Integração API para desenvolvedores

Nossa API está aberta e oferecemos um manual para orientar os desenvolvedores durante esse processo.

Você encontra a documentação em Documentação da API Conta Azul.

Siga os 5 passos seguintes:

1. Criação de Usuário e Aplicação no Portal Developers.
   
   Criação da conta no portal utilizando uma conta da plataforma Gmail.
   Criação da aplicação a ser utilizada no consumo de APIs.
   
   
   
2. Primeira etapa do Fluxo OAuth2 - Solicitação do Code.
   
   
   
3. Segunda etapa do Fluxo OAuth2 - Solicitação do Access Token.
   
   Esta informação deve ser gerenciada pela aplicação que a solicitou, ou seja, deve armazenar o access_token e refresh_token para uso posterior.
   
   
   
4. Utilização do Access Token.
   
   Para cada chamada de API o acess_token deve ser informado no Header da requisição como um Authorization Bearer.
   
   
   
5. Atualização do Access Token através do Refresh Token.
   
   O access_token tem validade de 1 hora e após esse período ele pode ser atualizado através do refresh_token (seguir o Step 5 da documentação)

Todos os passos citados acima estão descritos na documentação. 

Para criar uma conta no portal de desenvolvedores, é necessário acessar o link: https://portaldevs.contaazul.com/#/login/ e utilizar um e-mail em formato Gmail.

As contas na Conta Azul e no Portal do desenvolvedor são completamente independentes, ou seja, não há necessidade de utilizar o mesmo e-mail nas duas contas.

1. Acessar o Portal Developers
   
   Criar uma conta do Portal de desenvolvedores, utilizando uma conta de e-mail do Gmail.
   
   
   
2. Criar uma aplicação
   
   Nesse momento, é importante informar nome, descrição e URI de redirecionamento. 
   Caso a sua aplicação for gerar novas chaves de acesso, utilize um endereço onde sua aplicação possa pegar o code, caso contrário se for para utilizar uma única chave, pode se utilizar a URI a ser utilizada pode ser qualquer uma, como a https://www.google.com/.
   
   Na sequência, informe o propósito a ser utilizado nessa aplicação.
   
   
   
3. Conclusão
   
   Neste momento, você já tem acesso ao seu ClientID e Client_Secret, agora é seguir os passos para a geração das chaves a ser utilizada nas requisições, o Access e Refresh Token.

Para gerar o Access Token você precisa preencher o link com as informações na url padrão: https://api.contaazul.com/auth/authorize?redirect_uri={REDIRECT_URI}&client_id={CLIENT_ID}&scope=sales&state=DCEeFWf45A53sdfKef424:

• REDIRECT_URI: É apenas para conseguir pegar o CODE de autenticação, pode ser qualquer link, como https://www.google.com/.
• client_id: leia a resposta 4. Como gerar o client_id e o client_secret?

Esta etapa é para validar sua aplicação para permissão de acesso. A chamada etapa de consentimento, é onde o cliente da Conta Azul ao efetuar a inserção de login e senha, dá o aceite de que ele permite que a sua aplicação colete os seus dados.

Quando você enviar o link da sua aplicação, insira os dados de login e senha da Conta Azul aparecerá esta página para você autorizar a integração.

E assim você conseguirá pegar o CODE na URL do navegador para identificar o cliente que inseriu o login:

 

Agora sua aplicação está autorizada a criar o Access e Refresh Token. Para assim conseguir gerar o Access Token da integração.

• O Access_token tem validade de 1 hora.
• O Refresh_token tem validade de 2 semanas, mas o refresh_token só pode ser utilizado 1 única vez.

Atualmente não temos um access_token que não expire, e o refresh_token é uma chave usada para validar o access_token.

Uma vez que o access_token expira ,o refresh_token também expira e é necessário gerar um novo.

Atualmente nossa autenticação é apenas via OAuth2.

Não temos uma maneira de autenticação simplificada, todos os passos necessários para realizar o acesso estão disponíveis nessa documentação.

A autenticação precisa seguir esses passos por questões de segurança.

Não temos uma base de testes, apenas o ambiente de produção. Ao criar uma aplicação no Portal do desenvolvedor, automaticamente uma conta de teste é criada e você pode acessa-la por 3 (três) dias.

Acesse Minhas aplicações, em Chaves de acesso você encontrará o usuário e senha para a conta de testes.

 

Caso não seja suficiente o período de degustação do nosso ERP, conseguimos disponibilizar uns dias extras para você realizar os testes necessários, é só enviar um e-mail para api@contaazul.com.

Nesse caso, deve ser possível que o cliente acesse a aplicação que você desenvolveu (seu site de direcionamento), para acionar o fluxo de autorização (digitar o login e senha da Conta Azul) que deve partir da sua integração, para que a integração desenvolvida.

Inicie o fluxo de Authenticating da documentação, a partir do step 2.

Dessa forma o cliente será direcionado para a Conta Azul para realizar a autenticação e autorização da sua integração com a conta dele. Seguindo a partir dai o fluxo do Auth2.

Sim. Nossa API utiliza o mesmo padrão de autenticação de empresas como a Google, Facebook e Amazon.

Além disso, todos os dados ficam salvos na Amazon, que está de acordo com diversas normas de segurança de dados.

A API que disponibilizamos é a pública, acessível a todos os usuários, enquanto nossa API privada pode sofrer atualizações periódicas devido às melhorias em curso.

Não podemos fornecer garantias em relação à API privada, pois ela está sujeita a mudanças e aprimoramentos contínuos.

Não desenvolvemos integrações adicionais com novas plataformas.

Mas temos parceiros especializados que oferecem serviços de integração entre outros sistemas e a Conta Azul.

 

Temos parceiros que desenvolvem integrações entre outras plataformas e a Conta Azul. Segue abaixo site das empresas para que possa entrar em contato e verificar a que melhor te atende:

• Pluga
• Informant
• Albato

Atualmente não estamos desenvolvendo parcerias de integrações com novas plataformas para que sejam apresentadas dentro de nosso ERP no menu de integrações, por estarmos concentrados em outras estratégias no momento.

Quando retornarmos com esse projeto, iremos comunicar os clientes!

O bloqueio pode ocorrer devido a uma suspeita de comprometimento da API pública ou em alguns lugares fora do Brasil possuem um bloqueio fixo a nossa API pública por questões de segurança.
Caso ocorra algum bloqueio em seu acesso, entre em contato com nossa equipe por api@contaazul.com e informe seu IP que avaliaremos a possibilidade de realizar uma liberação pontual do seu IP.

Nesse caso, tente realizar o acesso para criação da aplicação por uma janela anônima, na maioria das vezes resolve o problema.

Caso o erro persista, entre em contato pelo e-mail api@contaazul.com.

No cabeçalho da requisição, é necessário enviar a autenticação do tipo basic, que é composta pelo hash_64(clientId:clientSecret).

O parâmetro token basic é formado pelas informações do clientId + clientSecret em base64.

Para montá-lo, basta usar uma ferramenta que converta os dados em base64.$authToken -> $clientId:$clientSecret onde as variáveis $clientId e $clientSecret são as suas credenciais, respectivamente.

 

 

Ao entrar na ferramenta, basta você copiar o seu clientId e clientSecret (obtidos no Portal do desenvolvedor) nesse formato: 'clientId:clientSecret' e depois basta clicar em "encode" para gerar o código hash_64.

Caso o erro persista, entre em contato pelo e-mail api@contaazul.com.

Quando a plataforma está autenticada um cookie é gerado, e devido ao tamanho do cookie o micro serviço de autenticação não o suporta, o que acaba retornando o erro acima.

Como contorno, basta realizar logout da plataforma e iniciar o processo de autorização da aplicação para acesso à API.

Esse processo irá levá-lo para uma tela de autenticação do Heimdall e com isso será possível autenticar e realizar a autorização.

Normalmente esse erro ocorre quando o customer_id não está indo como um UUID válido, valide essa questão, pode ter acontecido erro na hora de copiar e colar.

Outra possibilidade é o payload informado não ter o atributos products ou services, o payload da requisição precisa ter ao menos um dos dois atributos.

Normalmente esse erro ocorre quando faltou incluir o Header de autenticação na requisição POST.

Na documentação, o passo 3 - Step 3 - Exchange Authorization Code for an Access Token - mostra que deve ser incluído o Header Authorization: Basic hash_base64 (client_id:client_secret), isso pode ser observado pela mensagem de retorno de erro que diz que é inválida a autenticação do cliente.

Quando enviar uma venda como COMMITTED a mesma precisa ter um cliente vinculado, caso contrário não será criada na Conta Azul.
Para vendas com status PENDING, não é obrigatório o ID do cliente, mas para vendas com status COMMITTED, é obrigatório ser informado o cliente.

Quando enviar uma venda como COMMITTED a mesma precisa ter um produto ou serviço vinculado, caso contrário não será criada na Conta Azul e retornará com o erro ''A sale with status COMMITTED must have product_id for all items".

Para vendas com status PENDING, não é obrigatório o ID do produto ou serviço, mas para vendas com status COMMITTED, é obrigatório ser informado.

Este erro normalmente acontece na tentativa de baixar uma parcela sem uma conta financeira preenchida ou preenchida com a conta financeira do Receba Fácil ou Conta PJ da Conta Azul.

As contas financeiras Receba Fácil ou Conta PJ são nativas do ERP Conta Azul e geram cobranças baixadas automaticamente quando o cliente final realiza o pagamento. Não é possível via tela ou via API baixar as parcelas que tem uma dessas contas preenchidas, por isso o retorno do erro.

Para corrigir, acesse o lançamento via tela ou em uma consulta via API e valide se possui uma conta vinculada no registro da venda.

Se buscar via API, o campo que precisa ter uma conta preenchida é o financial_account_id.

Caso não tenha uma conta informada, atualize via tela, incluindo uma conta, assim o erro não ocorrerá mais.

Via API não é possível atualizar o campo financial_account_id.

Webhook é uma tecnologia utilizada para permitir a comunicação entre duas aplicações e enviar notificações quase em tempo real, mas hoje a Conta Azul não possui essa tecnologia, logo não tem como enviar os dados criados na Conta Azul para outras aplicações.

Através da API é possível integrar algumas partes do sistema, como produtos, serviços, clientes, fornecedores e vendas.

Os módulos Fiscal e Financeiro não estão disponíveis para integração.

Não é possível editar ou atualizar contratos via API, caso tente realizar essa ação ocorrerá o erro: ‘Contract can online be changed by web application’.

O endpoint de exclusão disponível na API pública faz a desativação do produto ou serviço, não é possível realizar a exclusão de um produto ou serviço via API.

Para excluir um produto ou serviço é necessário acessar o ERP e realizar o processo manualmente.

Atualmente esse campo já vem preenchido automaticamente, a própria Conta Azul atribui o valor nesse campo e ele vem com o nome da aplicação do portaldevs.contaazul.com.

O nome que for definido no portal, é o que vai aparecer na coluna de origem.

Atualmente não é possível integrar orçamentos, não possuíamos endpoint para essa funcionalidade no momento.

Atualmente não é possível informar uma categoria no campo category_id ao enviar a venda via API, esse campo é preenchido automaticamente com a primeira categoria cadastrada no plano de categorias do cliente no banco de dados, no momento em que a venda é integrada.

Não é possível realizar a edição desse campo via API nem via ERP manualmente, esse campo é bloqueado para edições.

Quando você fizer a consulta da venda via https://developers.contaazul.com/#!/Sale/findById haverá um elemento dentro do retorno chamado installments (é uma lista de elementos que podem contar várias parcelas).

Com o number desse elemento você consegue validar o status da installment, sendo ACQUITTED para baixada.

Dessa forma você saberá que a parcela foi baixada, mas lembrando que a parcela não vai retornar dados de vinculo com o boleto, caso tenha.

Atualmente não é possível alterar a situação da venda via API.

Para editar a situação de uma venda é necessário acessar o ERP e realizar o processo manualmente.

Atualmente não é possível enviar a venda com o financeiro marcado como recebido.

O que é possível:

• Quando você fizer a inclusão da venda via https://developers.contaazul.com/#!/Sale/create ou fizer a consulta da venda via https://developers.contaazul.com/#!/Sale/findById vai haver um elemento dentro do retorno chamado installments (é uma lista de elementos que podem contar varias parcelas).

Com o number desse elemento você faz o que está no passo a seguir:

• Por meio da api https://developers.contaazul.com/#!/Sale/update é possível atualizar o status o installment de uma venda. Utilizando as informações do passo anterior e enviando para o update citado aqui, a parcela pode ser marcada como ACQUITTED.

 

Os métodos de pagamento das Cobranças Conta Azul não estão disponíveis via API pública, os métodos que temos disponíveis via API atualmente são os que estão na documentação de criação de vendas.

 

Para pegar o número da venda que aparece na tela de vendas, o atributo é o number, esse atributo contém o sequência das vendas do cliente.

É possível cadastrar fornecedores via API, esse endpoint fica na parte 7 da documentação de developers.

 

Nestes endpoints poderá:

• Excluir os fornecedores,
• Trazer os clientes da aplicação,
• Atualizar os fornecedores,
• Listar os fornecedores por filtros,
• Permitir o cadastro de fornecedores,
• Trazer a listagem dos fornecedores dentro do cadastro ou edição do produto.

Para enviar a venda com a conta e forma de pagamento preenchidas, os campos para preenchimento são method e financial_account_id.

Atualmente não é possível atualizar a conta bancária (financial_account_id) de uma venda via API.

É possível atualizar a forma de pagamento de uma venda avulsa via API pelo campo method.

Atualmente não é possível criar a conta bancária via API, conseguimos apenas listar as contas bancárias já existentes no endpoint GET/v1/sales/banks.

Conseguimos listar as contas bancárias já existentes no endpoint GET/v1/sales/banks.

Via tela não é possível visualizar o UUID da conta, você precisaria ter conhecimento técnico para coletar o UUID utilizando o comando F12 + aba rede.

Atualmente não é possível buscar os produtos E serviços pela listagem das vendas.

Para buscar os produtos E serviços de uma venda é necessário utilizar o endpoint GET/v1/sales/{id}/items.

Não é possível integrar vendas com o valor da soma das parcelas diferente do valor total da venda.

Caso sejam enviadas vendas nesse formato retornará o erro:

Atualmente não conseguimos via API automatizar essas funções no contrato.

A API pública considera vendas que não estão excluídas e a busca por status, atualmente, aceita os status PENDING e COMMITTED apenas.

O situação de venda cancelada não é considerado na consulta atual, com isso, ela é listada.

Pelas nossas validações, o Power BI não funciona bem com o fluxo de autenticação da nossa API, então ainda não é possível acessar esses dados diretamente.

Converse com um desenvolvedor para criar um conector customizado no Power BI e realizar o fluxo de autenticação. Esse processo de autenticação é descrito na nossa documentação, contudo não testamos este fluxo para auxiliar neste processo.

Atualmente existem dois status para enviar a venda para a Conta Azul, sendo elas PENDING e COMMITTED.

O status PENDING a venda é criada na Conta Azul com um alerta de revisão pendente e o cliente precisa confirmar para que a venda seja aprovada.

 

E o lançamento financeiro criado, já o status COMMITTED a venda já entra direto como aprovada e não necessita de nenhuma ação do cliente:

 

Atualmente não é possível cadastrar um cliente estrangeiro via API, essa ação só é possível manualmente via ERP, se necessário, edite o cadastro do seu cliente.

É possível sim, você vai conectar todas as contas à aplicação que você desenvolveu em nosso portal, basta fazer o fluxo de autorização para cada cliente.

O erro Não foi possível efetuar a integração: A quantidade de MEUPRODUTO. solicitada é superior a disponível no estoque não tem relação com estoque mínimo ou máximo, mas sim com uma configuração feita dentro do ERP.

A correção não pode ser feita via API, precisa ser feita manualmente pelo usuário administrador da conta dentro do ERP Conta Azul.

Para corrigir essa falha, acesse Configurações e plano > Mais configurações... > Configurações do estoque > Permissões do estoque, e clique em:

 

 

Para concluir, clique em Salvar.

 

Feito isso, não será mais validado o estoque ao ser gerado uma venda.

Sobre Rate Limit, no momento não temos uma política definida, mas para garantia da performance é importante que as consultas sejam feitas utilizando os recursos de paginação para reduzir o tempo de espera das consultas e assim não gerar timeout.

Para questões relacionadas ao desenvolvimento de novas APIs, nosso canal de suporte é exclusivamente através do e-mail api@contaazul.com.

Não oferecemos assistência por telefone ou vídeo chamadas.

Este canal de atendimento é exclusivo para desenvolvedores que estão com dúvidas no desenvolvimento de novas integrações com a Conta Azul.

Faça contato com nossos atendentes para suporte em dúvidas gerais.