Você encontrará respostas para as principais dúvidas sobre integração com a API da Conta Azul Pro.
Este conteúdo é voltado para desenvolvedores que desejam conectar sistemas externos ao ERP.
Consulte tópicos sobre autenticação, limites de requisição, formatos de retorno, permissões e estrutura dos endpoints disponíveis.
Além da possibilidade de integrar com outros aplicativos através das integrações diretas, indiretas e da Pluga, a Conta Azul possui API aberta, para que caso deseje, junto à um desenvolvedor, você possa criar a integração com o seu sistema ou aplicativo.
Explicamos para os desenvolvedores as dúvidas mais comuns:
- Como funciona a Integração API aberta da Conta Azul
- Como acessar a documentação e criar uma nova integração via API na Conta Azul
- Como é a segurança da integração via API da Conta Azul
- Funcionalidades disponíveis para integração via API da Conta Azul
- Como funciona a integração do módulo de orçamentos, vendas e contratos na Conta Azul
- Como funciona a integração do módulo financeiro na Conta Azul
- Como corrigir os erros apresentados na integração via API da Conta Azul
Como funciona a Integração API aberta da Conta Azul
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.
Por estarmos concentrados em outras estratégias no momento, 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.
Quando retornarmos com esse projeto, comunicaremos nossos clientes!
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.
O e-mail é um canal de atendimento exclusivo para desenvolvedores que estão com dúvidas no desenvolvimento de novas integrações com a Conta Azul.
Fale com nosso time de suporte para dúvidas gerais.
Como acessar a documentação e criar uma nova integração via API na Conta Azul
Para desenvolver a sua integração, acesse o nosso Portal do Desenvolvedor.
Acessando o Portal do Desenvolvedor, você terá acesso a um painel de aplicações e a documentação com todos os nossos passos de autenticação para o desenvolvimento da integração.
Importante!
Em março de 2025 a Conta Azul lançou uma nova versão das suas APIs, com mais endpoints (lugar exato onde um programa encontra outro para conversar e trocar informações), mais escalável e mais completa para facilitar a integração de parceiros.
Nossa API está aberta e oferecemos um manual para orientar os desenvolvedores durante esse processo.
Importante!
Em março de 2025 a Conta Azul lançou uma nova versão das suas APIs, com mais endpoints (lugar exato onde um programa encontra outro para conversar e trocar informações), mais escalável e mais completa para facilitar a integração de parceiros.
Acesse a documentação da nova versão API: https://developers.contaazul.com/guide.
Se você criou a integração antes de março de 2025, acesse a documentação antiga.
Para criar uma conta no portal de desenvolvedores, é necessário acessar o link https://developers-portal.contaazul.com/#/login e utilizar um e-mail em formato Gmail.
Os dados de acesso ao ERP Conta Azul Pro e do Portal do desenvolvedor são completamente independentes, ou seja, não há necessidade de utilizar o mesmo e-mail nas duas contas.
Confira na documentação no Novo Portal do Desenvolvedor.
Confira na documentação no Novo Portal do Desenvolvedor.
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.
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.
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.
Confira na documentação no Novo Portal do Desenvolvedor.
Sim, é possível.
Você pode conectar todas as contas à aplicação desenvolvida em nosso portal, basta fazer o fluxo de autorização para cada cliente.
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.
Como é a segurança da integração via API da Conta Azul
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.
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 pelo e-mail api@contaazul.com e informe seu IP que avaliaremos a possibilidade de realizar uma liberação pontual do seu IP.
Funcionalidades disponíveis para integração via API da Conta Azul
Confira na documentação no Novo Portal do Desenvolvedor.
Webhook é uma tecnologia utilizada para permitir a comunicação entre duas aplicações e enviar notificações quase em tempo real.
Atualmente a Conta Azul não possui essa tecnologia, logo não tem como enviar os dados criados na Conta Azul para outras aplicações.
Porém nossa API tem endpoints GET (recolher ou consultar dados do servidor) de informações que podem ser consultados e seu resultado levado para outras aplicações.
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 Portal do desenvolvedor.
O nome que for definido no portal, é o que vai aparecer na coluna de origem.
Sobre a limitação de requisições (rate limit), no momento não temos uma política definida.
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.
Não é possível integrar a Conta Azul Mais com outros sistemas.
Através de nossa API é possível somente integrar a Conta Azul Pro com outros sistemas.
Como funciona a integração do módulo de orçamentos, vendas e contratos na Conta Azul
Se a sua integração API foi criada depois de março de 2025:
Os status atuais são EM_ANDAMENTO, APROVADO e FATURADO.
Se a sua integração API foi criada antes de março de 2025:
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.
Importante!
Para vendas com status PENDING, não é obrigatório o ID do cliente, para vendas com status COMMITTED, é obrigatório ser informado o cliente.
Não é possível integrar orçamentos, pois não possuíamos endpoint para essa funcionalidade no momento.
Se a sua integração API foi criada depois de março de 2025:
É possível criar recorrências mensais e anuais conforme os parâmetros do endpoints de Contratos.
Se a sua integração API foi criada antes de março de 2025:
É possível criar contratos somente a recorrência mensal e deve ser no mínimo 2 (duas) recorrências (2 meses).
No endpoint Contract, o campo duration é a quantidade de vendas.
Não é possível automatizar essas funções no contrato via API.
Se a sua integração API foi criada depois de março de 2025:
Sim você pode consultar o número da venda nos endpoints de busca de Vendas.
Se a sua integração API foi criada antes de março de 2025:
Para consultar o número da venda que aparece no menu Vendas, da Conta Azul Pro, o atributo que contém o sequência das vendas do cliente é o number.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível utilizando os filtros de busca do endpoint de Vendas.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível utilizando os filtros de busca do endpoint de Vendas.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Não, ainda não disponibilizamos os endpoints para edição de contratos.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, no método de edição da venda é possível alterar a conta financeira vinculada a venda.
Se a sua integração API foi criada antes de março de 2025:
Não é possível atualizar a conta bancária (financial_account_id) de uma venda via API.
Se a sua integração API foi criada depois de março de 2025:
Sim, no método de edição da venda é possível editar a forma de pagamento da venda.
Se a sua integração API foi criada antes de março de 2025:
É possível atualizar a forma de pagamento de uma venda avulsa via API pelo campo method.
Se a sua integração API foi criada depois de março de 2025:
Sim, no método de edição da venda é possível editar a situação de uma venda.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, pelos endpoints de produtos disponíveis.
Se a sua integração API foi criada antes de março de 2025:
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 cadastrados via API.
Para excluir um produto ou serviço é necessário acessar o ERP e realizar o processo manualmente.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível enviar uma venda com o status Faturado.
Se a sua integração API foi criada antes de março de 2025:
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, a parcela pode ser marcada como ACQUITTED.
Atenção!
Para marcar uma installment como ACQUITTED é necessário que a mesma possua uma conta financeira preenchida, logo, o campo financial_account_id não pode estar null.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível enviar uma venda passando os parâmetros de cobrança.
Se a sua integração API foi criada antes de março de 2025:
Os métodos de pagamento das Cobranças da 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:
- BANKING_BILLET: is equivalent to 'Boleto Bancário'
- CREDIT_CARD: is equivalent to 'Cartão de Crédito'
- DEBIT_CARD: is equivalent to 'Cartão de Débito'
- DIGITAL_WALLET: is equivalent to 'Carteira Digital'
- CASHBACK: is equivalent to 'Cashback'
- CHECK: is equivalent to 'Cheque'
- STORE_CREDIT: is equivalent to 'Credito da Loja'
- VIRTUAL_CREDIT: is equivalent to 'Crédito Virtual'
- BANKING_DEPOSIT: is equivalent to 'Depósito Bancário'
- CASH: is equivalent to 'Dinheiro'
- OTHER: is equivalent to 'Outros'
- AUTOMATIC_DEBIT: is equivalent to 'Débito Automático'
- INSTANT_PAYMENT: is equivalent to 'PIX - Pagamento Instantâneo'
- FIDELITY_PROGRAM: is equivalent to 'Programa de Fidelidade'
- WITHOUT_PAYMENT: is equivalent to 'Sem Pagamento'
- BANKING_TRANSFER: is equivalent to 'Transferência Bancária'
- FOOD_VOUCHER: is equivalent to 'Vale Alimentação'
- FUEL_VOUCHER: is equivalent to 'Vale Combustível'
- GIFT_VOUCHER: is equivalent to 'Vale Presente'
- MEAL_VOUCHER: is equivalent to 'Vale Refeição'
Se a sua integração API foi criada depois de março de 2025:
Não, a API segue as mesmas regras de negócio da aplicação. Então o valor da soma das parcelas deve ser igual ao valor total da venda.
Se a sua integração API foi criada antes de março de 2025:
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:
{"code": "INTEGRATION_ERROR", "message":"O valor total das parcelas R$__ difere do valor total R$__."}
Se a sua integração API foi criada depois de março de 2025:
Sim, pela API é possível cadastrar um cliente estrangeiro.
Se a sua integração API foi criada antes de março de 2025:
Não é possível cadastrar um cliente estrangeiro via API.
É possível cadastrar um cliente estrangeiro manualmente via ERP, se necessário, edite o cadastro do seu cliente.
Como funciona a integração do módulo financeiro na Conta Azul
Se a sua integração API foi criada depois de março de 2025:
Sim, seguindo os passos para autenticação e autorização corretamente é possível integrar o Conta Azul Pro com o Power BI.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Os métodos de pagamento estão listados na documentação em Vendas > Criar uma nova venda > condicao_pagamento. tipo_pagamento.
Se a sua integração API foi criada antes de março de 2025:
Os métodos de pagamento disponíveis são:
- BANKING_BILLET: is equivalent to 'Boleto Bancário'
- CREDIT_CARD: is equivalent to 'Cartão de Crédito'
- DEBIT_CARD: is equivalent to 'Cartão de Débito'
- DIGITAL_WALLET: is equivalent to 'Carteira Digital'
- CASHBACK: is equivalent to 'Cashback'
- CHECK: is equivalent to 'Cheque'
- STORE_CREDIT: is equivalent to 'Credito da Loja'
- VIRTUAL_CREDIT: is equivalent to 'Crédito Virtual'
- BANKING_DEPOSIT: is equivalent to 'Depósito Bancário'
- CASH: is equivalent to 'Dinheiro'
- OTHER: is equivalent to 'Outros'
- AUTOMATIC_DEBIT: is equivalent to 'Débito Automático'
- INSTANT_PAYMENT: is equivalent to 'PIX - Pagamento Instantâneo'
- FIDELITY_PROGRAM: is equivalent to 'Programa de Fidelidade'
- WITHOUT_PAYMENT: is equivalent to 'Sem Pagamento'
- BANKING_TRANSFER: is equivalent to 'Transferência Bancária'
- FOOD_VOUCHER: is equivalent to 'Vale Alimentação'
- FUEL_VOUCHER: is equivalent to 'Vale Combustível'
- GIFT_VOUCHER: is equivalent to 'Vale Presente'
- MEAL_VOUCHER: is equivalent to 'Vale Refeição'
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível informar a categoria financeira.
Se a sua integração API foi criada antes de março de 2025:
Não é possível informar uma categoria financeira 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.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível informar utilizando os métodos de criação de vendas disponíveis.
Se a sua integração API foi criada antes de março de 2025:
Para enviar a venda com a conta bancária e forma de pagamento preenchidas, os campos para preenchimento são respectivamente financial_account_id e method.
Se a sua integração API foi criada depois de março de 2025:
Ainda não é possível cadastrar uma conta bancária via API.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, consultado o método de busca do endpoint de Contas Financeiras.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível verificar pelo métodos de busca e listagem disponíveis.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Sim, é possível gerar cobranças pelo método de Geração de cobranças.
Se a sua integração API foi criada antes de março de 2025:
Não é possível gerar cobranças via API, inclusive não integramos dados das Cobranças da Conta Azul, temos somente os métodos de pagamentos mencionados na questão 40.
Como corrigir os erros apresentados na integração via API da Conta Azul
Se a sua integração API foi criada depois de março de 2025:
Siga os passos de autenticação e autorização corretamente (https://developers.contaazul.com/auth).
Caso o erro persista, entre em contato pelo e-mail api@contaazul.com.
Se a sua integração API foi criada antes de março de 2025:
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.
Dica!
Para converter em base_64, você pode usar uma ferramenta online como a https://www.base64encode.org/.
Ao entrar na ferramenta, copie o seu clientId e clientSecret (obtidos no Portal do desenvolvedor) no formato: clientId:clientSecret e depois clique em encode para gerar o código hash_64.
Caso o erro persista, entre em contato pelo e-mail api@contaazul.com.
Se a sua integração API foi criada depois de março de 2025:
Consulte a documentação do endpoint sendo executado e confira todos os parâmetros e campos obrigatórios, incluindo os tipos de cada campo.
Caso o erro persista, entre em contato pelo e-mail api@contaazul.com.
Se a sua integração API foi criada antes de março de 2025:
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.
Importante!
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.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada antes de março de 2025:
Quando enviar uma venda como COMMITTED a mesma precisa ter ao menos um produto ou serviço vinculado, caso contrário não será criada na Conta Azul.
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.
Se a sua integração API foi criada antes de março de 2025:
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.
Se a sua integração API foi criada depois de março de 2025:
Confirma as informações dos parâmetros utilizados e siga os passos de autenticação apresentados na documentação.
Se a sua integração API foi criada antes de março de 2025:
Normalmente esse erro ocorre quando faltou incluir o Header de autenticação na requisição POST.
Na documentação, em Exchange Authorization Code for an Access Token, mostramos 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.
Se a sua integração API foi criada antes de março de 2025:
Normalmente esse erro ocorre quando o customer_id não está indo como um UUID válido, este erro pode ter sido gerado no momento 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.
Se a sua integração API foi criada antes de março de 2025:
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:
Verificar estoque ao criar uma venda
☐ Ao ativar esta opção, só será possível vender produtos em quantidade suficiente disponível no estoque. Esse parâmetro não será considerado no frente de caixa.
Para concluir, clique em Salvar.
Feito isso, não será mais validado o estoque ao ser gerado uma venda.
Se a sua integração API foi criada antes de março de 2025:
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.
Comentários
0 comentário