Dúvidas frequentes de desenvolvedores sobre Integração API

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:

1. Documentação da API Pública

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.

2. Como criar uma aplicação? 

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

3. Como criar uma conta no portal de desenvolvedores?

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.

4. Como gerar o cliente_id e o cliente_secret?
  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.
5. Como gerar o Acess_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.

6. Qual a validade do Access_token e Refresh_token?
  • 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.

7. 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.
8. A Conta Azul tem uma base de testes para os desenvolvedores?
Não temos uma base de testes, apenas o ambiente de produção.

Se você ainda não é nosso cliente, crie uma conta teste no site da Conta Azul, informe seu e-mail e clique em Experimente grátis:


Depois de feito este cadastro, já terá acesso a 3 dias de conta teste.

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.
9. Como conectar a conta do Conta Azul do cliente a aplicação desenvolvida?
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.

Importate!

Se for excluído ou editado o usuário que fez o aceite da autenticação, será invalidado a integração e precisará ser refeita.

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

11. Posso utilizar a API privada da Conta Azul?

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.

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

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.

 

Dica!

Saiba mais na próxima questão!

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

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:

14. Como faço para me tornar um parceiro e minha aplicação aparecer no menu de Integrações?
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!
15. O que fazer se ocorrer o erro ‘Error: Request failed with status code 500’?

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.

16. O que fazer se ocorrer o erro ‘400 Bad Request’?

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 essa: https://www.base64encode.org/.

 

Ao entrar na ferramenta, basta você copiar o seu clientId e clientSecret (obtidos no portal de desenvolvedores) 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.

17. O que fazer se ocorrer o erro ‘Request Header Or Cookie Too Large’?

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.

18. O que fazer se ocorrer o erro ‘message null’?
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.
19. O que fazer se ocorrer o erro ‘erro Invalid client authentication’?
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.
20. O que fazer se ocorrer o erro ‘A sale with status COMMITTED must have a customer id’?
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.
21. O que fazer se ocorrer o erro '500 Internal Server Error'?

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.

22. Quais os módulos que são disponibilizados para integração na API?

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

23. É possível integrar via API o módulo Fiscal e Financeiro?

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

24. É possível editar ou atualizar contratos via API?
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’.
25. É possível excluir produtos ou serviços via API?

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.

26. É 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 portaldevs.contaazul.com.

O nome que for definido no portal, é o que vai aparecer na coluna de origem.
27. É possível integrar orçamentos?
Atualmente não é possível integrar orçamentos, não possuíamos endpoint para essa funcionalidade no momento.
28. É possível informar uma categoria ao enviar a venda via API?
Atualmente não é possível informar uma categoria no campo category_id ao enviar a venda via API, esse campo é preenchido automaticamente no momento em que a venda é integrada.
29. É possível alterar a situação de uma venda via API?
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.
30. É possível enviar a venda com o financeiro recebido?

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

O que é possível:

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.
31. É possível pegar o número da venda via API?
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.
32. É possível cadastrar fornecedores via API?

É 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.
33. É possível preencher a conta bancária e forma de pagamento de uma venda via API?
Para enviar a venda com a conta e forma de pagamento preenchidas, os campos para preenchimento são method e financial_account_id.
34. É possível atualizar a conta bancária de uma venda via API?
Atualmente não é possível atualizar a conta bancária (financial_account_id) de uma venda via API.
35. É possível atualizar a forma de pagamento de uma venda via API?
É possível atualizar a forma de pagamento de uma venda avulsa via API pelo campo method.
36. É possível criar uma conta bancária via API?
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.
37. É possível buscar os produtos e serviços de uma venda pela listagem de vendas?
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.
38. É possível automatizar funções do contrato como envio de fatura, boletos, lembretes de vencimento e nota fiscal via API?
Atualmente não conseguimos via API automatizar essas funções no contrato.
39. É possível integrar a Conta Azul com o Power BI?
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.

Você pode criar um conector customizado no Power BI e tentar 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.
40. Com quais status consigo enviar a venda para a Conta Azul?

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

 

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.

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

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.

Esse artigo foi útil?
Usuários que acharam isso útil: 7 de 18

Comentários

0 comentário

Por favor, entre para comentar.