🚀 Quick Start — API Conta Azul

Este guia mostra como realizar sua primeira integração com a API da Conta Azul, utilizando o fluxo de autenticação OAuth 2.0 e fazendo uma chamada real à API de Serviços.

✅ Pré-requisitos

Antes de começar, você precisa:

Um app cadastrado no Portal de Desenvolvedores da Conta Azul
Um client_id, client_secret e redirect_uri válidos
O consentimento de um cliente Conta Azul para autorizar seu app

1. Obter o código de autorização

Direcione o cliente para a URL abaixo com os parâmetros preenchidos:

https://auth.contaazul.com/oauth2/authorize?
  response_type=code&
  client_id=SEU_CLIENT_ID&
  redirect_uri=SUA_REDIRECT_URI&
  state=ESTADO&
  scope=openid+profile+aws.cognito.signin.user.admin

➡️ Após o cliente autorizar, você receberá um redirecionamento para:

https://SUA_REDIRECT_URI/?code=AUTORIZATION_CODE&state=ESTADO

2. Trocar o código por um token de acesso

Envie um POST para:

https://auth.contaazul.com/oauth2/token

Headers:

Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

Body:

client_id=SEU_CLIENT_ID&
client_secret=SEU_CLIENT_SECRET&
grant_type=authorization_code
&code=AUTORIZATION_CODE
&redirect_uri=SUA_REDIRECT_URI

📌 Você pode gerar o header Authorization codificando em Base64:

Authorization: Basic base64(client_id:client_secret)

3. Fazer sua primeira chamada para a API

Utilize o access_token obtido para fazer uma requisição autenticada:

GET https://api-v2.contaazul.com/v1/servicos
Authorization: Bearer SEU_ACCESS_TOKEN

Exemplo de resposta:

[
  {
    "itens": [
      {
        "codigo": "string",
        "codigo_cnae": "string",
        "codigo_municipio_servico": "string",
        "custo": 0,
        "descricao": "string",
        "id": "string",
        "id_externo": "string",
        "id_servico": 0,
        "lei_116": "string",
        "lista_cenario_tributario": [
          {
            "id": "string",
            "inss_aliquota": 0,
            "iss_aliquota": 0,
            "iss_retido": true,
            "municipio": {
              "codigo": 0,
              "nome": "string",
              "uf": "string"
            },
            "nome_usuario": "string",
            "ultima_atualizacao": "string"
          }
        ],
        "natureza_operacional": {
          "id": "string"
        },
        "preco": 0,
        "status": "ATIVO",
        "tipo_servico": "PRESTADO"
      }
    ],
    "paginacao": {
      "pagina_atual": 0,
      "tamanho_pagina": 0,
      "total_itens": 0,
      "total_paginas": 0
    }
  }
]

✅ Parabéns! Sua aplicação está integrada com a API da Conta Azul.

🔄 Dica: renovar o token

Quando o access_token expirar, use o refresh_token com o mesmo endpoint /token, trocando grant_type para refresh_token.