# 🚀 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](https://developers.contaazul.com/)
- 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:


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

### Body:


```text
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:


```text
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:


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

### Exemplo de resposta:


```json
[
  {
    "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`.