Integração API: perguntas frequentes de desenvolvedores

O suporte técnico para integração com a API está disponível no Portal de Desenvolvedores da Conta Azul. No portal, o Bot Denver orienta sobre a documentação e, quando necessário, encaminha o atendimento para um especialista técnico, garantindo um suporte ágil e completo.

Dica!

Ao conectar a API, informe o código da autenticação de dois fatores, o mesmo usado no login da Conta Azul. Abra o aplicativo autenticador (Google Authenticator, Microsoft Authenticator ou Authy), copie o código atual e cole no campo solicitado.

 

API: perguntas frequentes

O que é a API de integração da Conta Azul?

A API da Conta Azul é um conjunto de recursos RESTful que permite integrar sistemas externos ao ERP.

Com a API da Conta Azul, desenvolvedores podem automatizar processos como cadastro de clientes, sincronização de vendas e orçamentos, cobranças e conciliação financeira, além de consultar notas fiscais emitidas: NF-e (Nota Fiscal eletrônica) e NFS-e (Nota Fiscal de Serviço eletrônica).

Preciso pagar para usar a API?

Não. O acesso à documentação é gratuito e qualquer desenvolvedor pode consultar os recursos disponíveis. Para colocar integrações em produção, mantenha um plano ativo na Conta Azul com suporte às funcionalidades desejadas.

Que tipos de dados posso integrar?

A API da Conta Azul permite integrar vendas, orçamentos e contratos, cadastros de clientes e fornecedores, produtos e serviços, além do financeiro: contas a pagar e a receber, categorias, contas financeiras e cobranças.

Pela API também é possível consultar notas fiscais emitidas (NF-e e NFS-e) e enviar documentos pela Captura.

Com isso, sistemas externos automatizam rotinas e mantêm as informações sincronizadas com o ERP. Veja a lista completa de módulos na documentação.

Quem pode usar a API da Conta Azul?

Qualquer desenvolvedor, parceiro de tecnologia ou empresa que precise integrar sistemas externos pode usar a API. O acesso à documentação é gratuito e, para produção, é necessário um plano compatível com as funcionalidades desejadas.

Quais os benefícios de integrar minha solução?

Ao integrar sua solução, você automatiza processos, reduz erros manuais, centraliza informações e entrega mais valor aos clientes. Isso aumenta a eficiência, amplia a escalabilidade do negócio e abre novas oportunidades com soluções conectadas.

Existe algum contato comercial para parcerias?

Sim. A entrada para parcerias é sempre pelo Conecta, o programa de parceria para integradores da Conta Azul, começando pelo Portal do Desenvolvedor.

Parceiros do Conecta a partir do nível Construtor contam com gestão de conta sob demanda. No nível Arquiteto, a gestão de conta e as revisões periódicas de performance (QBRs) são recorrentes.

Para falar sobre parcerias, use o e-mail integracoes@contaazul.com.

Como começo a me integrar com a Conta Azul?

Acesse a nossa documentação. Lá você encontra guias, exemplos e orientações para dar os primeiros passos rapidamente. Se ainda não tem acesso ao portal, entre pelo Portal do Desenvolvedor.

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

1. A Conta Azul desenvolve novas integrações com outros sistemas?

A Conta Azul não desenvolve integrações sob encomenda para um cliente específico. Antes de contratar um desenvolvimento, confira as integrações já disponíveis na Conta Azul.

Se você é desenvolvedor ou tem um software e quer integrá-lo à Conta Azul, conheça o Conecta, nosso programa de parceria para integradores.

2. A Conta Azul tem alguma indicação de desenvolvedor para criar uma integração?

Plataformas de automação como Pluga e Fin conectam a Conta Azul a outros sistemas sem que você precise programar.

3. Como faço para me tornar um parceiro e minha aplicação aparecer no menu de Integrações?

Para se tornar parceiro, entre no Conecta, o programa de parceria para integradores da Conta Azul:

1. Crie sua conta no Portal do Desenvolvedor.
2. Clique em Começar e aceite os Termos do Programa de Parceria Conecta.
3. Desenvolva a integração e passe pela homologação técnica. Com a homologação aprovada, você entra no nível Explorador.

A listagem da sua aplicação no menu de Integrações fica disponível a partir do nível Construtor (15 PMEs ativas conectadas por 30 dias consecutivos) e depende de aprovação da Conta Azul.

Veja os níveis e benefícios do programa em contaazul.com/conecta.

4. Qual canal de atendimento para dúvidas relacionadas ao desenvolvimento de novas APIs?

Para dúvidas sobre o desenvolvimento de integrações com a API, fale com nosso time pelo chat de suporte do Portal do Desenvolvedor (ícone no canto inferior direito) ou pelo e-mail api@contaazul.com.

Não oferecemos atendimento por telefone ou videochamada para dúvidas de integração com a API.

Para dúvidas gerais sobre o ERP, fale com nosso time de suporte.

Como acessar a documentação e criar uma nova integração via API na Conta Azul

5. Como criar uma API com a 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.

6. Como acessar a documentação da API pública da Conta Azul?

A API da Conta Azul é aberta e a documentação completa está em developers.contaazul.com.

Para acompanhar novos endpoints e mudanças na API, consulte o Changelog, que também pode ser recebido por e-mail.

7. Como criar uma conta no portal de desenvolvedores da Conta Azul?

Para criar uma conta, acesse o Portal do Desenvolvedor e clique em Cadastre sua conta.

Informe e-mail, nome, celular e senha, e confirme o código enviado por e-mail.

Se você já é cliente Conta Azul Pro, pode entrar no Portal do Desenvolvedor com o mesmo usuário e senha do ERP.

8. Como gerar o client_id e o client_secret?

Ao criar uma aplicação no Portal do Desenvolvedor, o client_id e o client_secret são exibidos na tela e ficam disponíveis a qualquer momento em Minhas Aplicações.

Confira o passo a passo no guia de credenciais da API.

9. Como gerar o access_token?

O access_token é gerado pelo fluxo OAuth 2.0 (Authorization Code), usando o client_id e o client_secret da sua aplicação.

Confira o passo a passo no guia de autenticação da API.

10. Qual a validade do access_token e do refresh_token?

O access_token tem validade de 1 hora.

O refresh_token tem validade de 2 anos e só pode ser usado uma vez. A cada renovação, você recebe um novo access_token e um novo refresh_token, que deve ser guardado para a próxima renovação.

O código de autorização, obtido no início do fluxo OAuth 2.0, vale 3 minutos.

Saiba mais em como renovar o access_token.

11. A Conta Azul tem uma base de testes para os desenvolvedores?

Não temos um ambiente de sandbox dedicado para testes da API.

Ao criar um App de Desenvolvimento no Portal do Desenvolvedor, você recebe automaticamente um usuário e senha de uma Conta de Desenvolvimento do Conta Azul Pro, com dados fictícios.

A Conta de Desenvolvimento vale por 30 dias e pode ser renovada até 5 vezes pelo botão Renovar conta, dentro do App de Desenvolvimento.

12. Como conectar a conta do Conta Azul do cliente a uma aplicação desenvolvida?

Confira na documentação no Novo Portal do Desenvolvedor.

13. É possível integrar mais de uma conta da Conta Azul com a integração desenvolvida no 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.

14. Existe alguma maneira de autenticação simplificada na API?

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

15. A API da Conta Azul é segura?

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.

16. Posso utilizar a API privada da Conta Azul?

Não. A Conta Azul disponibiliza apenas APIs públicas, documentadas em developers.contaazul.com.

17. O que fazer se meu acesso à API pública for bloqueado?

O bloqueio de acesso à API pública pode ocorrer por diversos fatores de segurança, como suspeita de comprometimento do acesso ou acessos feitos a partir de alguns locais fora do Brasil.

Se o seu acesso à API for bloqueado, fale com nosso time pelo chat do Portal do Desenvolvedor ou pelo e-mail api@contaazul.com e informe o seu IP para avaliarmos uma liberação pontual.

Funcionalidades disponíveis para integração via API da Conta Azul

18. Quais os módulos disponíveis para integração na API?

Confira na documentação no Novo Portal do Desenvolvedor.

19. É possível enviar os dados da Conta Azul para outras aplicações (Webhook)?

Não. No momento, a API da Conta Azul não oferece webhooks.

Para manter os dados atualizados em outras aplicações, faça consultas periódicas (polling) aos endpoints da API, usando os filtros por data de alteração para trazer apenas o que mudou desde a última consulta.

20. É possível alterar o campo origem via API?

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.

21. Existe limitação de requisições ao realizar consultas utilizando a API da Conta Azul?

Sim. O limite de requisições (rate limit) da API da Conta Azul é de 600 requisições por minuto e 10 por segundo, por conta conectada do ERP.

Ao ultrapassar o limite de requisições, a API retorna o erro 429 Too Many Requests.

Para evitar o bloqueio por excesso de requisições, use paginação, consulte só dados alterados e aplique novas tentativas com intervalo crescente. Saiba mais em requisitos mínimos da API.

22. É possível integrar a Conta Azul Mais com outros sistemas?

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

23. Quais status da venda podem ser enviados para a Conta Azul via API?

Os status da venda aceitos pela API são EM_ANDAMENTO, APROVADO e FATURADO.

24. É possível integrar orçamentos via API?

Sim. A API permite criar orçamentos, consultar um orçamento pelo id, listar orçamentos com filtros (datas, clientes, vendedores, produtos, categorias e situação) e excluir orçamentos em lote.

Confira os endpoints de Orçamentos na documentação.

25. É possível cadastrar contratos com quais recorrências via API?

É possível criar recorrências mensais e anuais conforme os parâmetros do endpoints de Contratos.

26. É possível automatizar funções do contrato como envio de fatura, boletos, lembretes de vencimento e nota fiscal via API?

Não é possível automatizar essas funções no contrato via API.

27. É possível consultar o número da venda via API?

Sim você pode consultar o número da venda nos endpoints de busca de Vendas.

28. É possível consultar vendas aprovadas e faturadas na API da Conta Azul, sem listar as vendas canceladas junto?

Sim, é possível utilizando os filtros de busca do endpoint de Vendas.

29. É possível consultar os produtos e serviços de uma venda via API?

Sim. Para consultar os produtos e serviços de uma venda, use o endpoint que retorna os itens da venda pelo id da venda, disponível nos endpoints de Vendas.

30. É possível editar contratos via API?

Ainda não disponibilizamos a edição de contratos via API.

Pela API, é possível criar, consultar por id, listar com filtros, encerrar e remover contratos. Confira os endpoints de Contratos.

31. É possível editar a conta bancária de uma venda via API?

Sim, no método de edição da venda é possível alterar a conta financeira vinculada a venda.

32. É possível editar a forma de pagamento da venda via API?

Sim, no método de edição da venda é possível editar a forma de pagamento da venda.

33. É possível editar a situação de uma venda via API?

Sim, no método de edição da venda é possível editar a situação de uma venda.

34. É possível excluir produtos ou serviços via API?

Sim, pelos endpoints de produtos disponíveis.

35. É possível enviar a venda via API com o financeiro recebido?

Sim, é possível enviar uma venda com o status Faturado.

36. É possível enviar uma venda via API com a forma e pagamento preenchida com as Cobranças da Conta Azul?

Sim, é possível enviar uma venda passando os parâmetros de cobrança.

37. É possível integrar vendas via API com o valor da soma das parcelas diferente do valor total da venda?

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.

38. É possível cadastrar um cliente estrangeiro via API?

Sim, pela API é possível cadastrar um cliente estrangeiro.

Como funciona a integração do módulo financeiro na Conta Azul

39. É possível integrar a Conta Azul Pro com o Power BI?

Sim, seguindo os passos para autenticação e autorização corretamente é possível integrar o Conta Azul Pro com o Power BI.

40. Quais são os métodos de pagamento disponíveis via API?

Os métodos de pagamento disponíveis via API estão listados no campo condicao_pagamento.tipo_pagamento dos endpoints de Vendas.

Para pagamentos via Pix, use o valor PIX_PAGAMENTO_INSTANTANEO.

41. É possível informar uma categoria financeira ao enviar a venda via API?

Sim, é possível informar a categoria financeira.

42. É possível informar a conta bancária e forma de pagamento de uma venda via API?

Sim, é possível informar utilizando os métodos de criação de vendas disponíveis.

43. É possível cadastrar uma conta bancária via API?

Ainda não é possível cadastrar uma conta bancária via API.

44. É possível consultar o UUID das contas bancárias (financial_account_id) via API?

Sim, consultado o método de busca do endpoint de Contas Financeiras.

45. É possível consultar se uma venda está baixada via API?

Sim, é possível verificar pelo métodos de busca e listagem disponíveis.

46. É possível gerar cobranças via API (pix, boleto, link de pagamento)?

Sim, é possível gerar cobranças pelo método de Geração de cobranças.

Como corrigir os erros apresentados na integração via API da Conta Azul

47. Como corrigir o erro 400 Bad Request?

Na geração ou renovação do token, o erro 400 Bad Request vem com invalid_grant, e o campo error_subtype indica a causa:

• access_revoked: o acesso da empresa foi revogado. Inicie um novo fluxo de autorização.
• invalid_refresh_token: o refresh_token não existe ou já foi usado. Envie o último refresh_token recebido.
• invalid_client: o cabeçalho Authorization: Basic está malformado. Confira o Base64 de client_id:client_secret.

Se o erro 400 Bad Request persistir, fale pelo chat do Portal do Desenvolvedor ou pelo e-mail api@contaazul.com.

48. Como corrigir o erro 500 Internal Server Error?

Para corrigir o erro 500 Internal Server Error, consulte a documentação do endpoint e confira os campos obrigatórios, os tipos de cada campo e se o JSON está bem formado.

Depois, tente novamente após alguns segundos. Se o erro persistir, fale pelo chat do Portal do Desenvolvedor ou pelo e-mail api@contaazul.com.

49. Como corrigir o erro Invalid client authentication?

O erro Invalid client authentication acontece quando o cabeçalho Authorization: Basic está ausente ou malformado na requisição de token.

O cabeçalho Authorization: Basic deve conter o client_id e o client_secret no formato client_id:client_secret, codificados em Base64. Veja como gerar esse valor no FAQ da documentação da API.

50. Como corrigir o erro Não foi possível efetuar a integração: A quantidade de [nome do produto] solicitada é superior a disponível no estoque?

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.

Artigos relacionados

• Veja como usar a autenticação de dois fatores na Conta Azul
• Saiba mais sobre a Conta Azul Pro
• Veja como falar com o time de suporte da Conta Azul