# Documentação completa da NextAPI

> Guias e referência de todas as operações da API v1, gerados da documentação pública em https://www.nextapi.com.br/docs. Índice resumido: https://www.nextapi.com.br/llms.txt

---

## Documentação da API NextAPI

> Aprenda a integrar CNPJ, Simples Nacional e CEP. Guias de autenticação, créditos e referência pública da NextAPI.

Fonte: https://www.nextapi.com.br/docs

A NextAPI é uma API HTTP para consultar dados de empresas e endereços do Brasil. A documentação é pública; para executar consultas, crie uma conta no [painel](https://admin.nextapi.com.br/account/register) e obtenha seu token. A disponibilidade e o consumo dependem do endpoint e do plano.

- URL base: `https://api.nextapi.com.br` (prefixo `/v1`)
- Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`
- Contrato OpenAPI: https://www.nextapi.com.br/docs/openapi.json

### Guias

- [Primeiros passos](https://www.nextapi.com.br/docs/primeiros-passos.md): Crie seu token e faça a primeira consulta.
- [Autenticação](https://www.nextapi.com.br/docs/autenticacao.md): Envie seu token com segurança em cada requisição.
- [Créditos e limites](https://www.nextapi.com.br/docs/creditos-e-limites.md): Entenda o consumo, o saldo e as permissões do plano.
- [Atualização dos dados](https://www.nextapi.com.br/docs/atualizacao-dos-dados.md): Escolha entre cache e consulta com tolerância de atualização.
- [Tratamento de erros](https://www.nextapi.com.br/docs/erros.md): Identifique os códigos e saiba como reagir.
- [Usar com IA (MCP)](https://www.nextapi.com.br/docs/mcp.md): Conecte Claude, Cursor e VS Code à NextAPI pelo servidor MCP.
- [Referência da API](https://www.nextapi.com.br/docs/referencia.md): Consulte parâmetros, modelos, respostas e exemplos de todos os endpoints.

### O que você pode integrar

- CNPJ, Simples Nacional, MEI e Inscrições Estaduais.
- Consulta de CEP, busca de endereços e geolocalização.
- Pesquisa de empresas, CNAEs, estados e municípios.
- Consulta de saldo e limites do workspace.

A referência reúne 15 operações da API v1, com parâmetros, exemplos e modelos de resposta.

---

## Primeiros passos

> Crie seu token e faça a primeira consulta.

Fonte: https://www.nextapi.com.br/docs/primeiros-passos

Este guia usa a consulta de um CEP para validar a autenticação e o formato da resposta antes de conectar a API ao seu sistema.

### 1. Crie sua conta e obtenha um token

[Crie uma conta gratuita](https://admin.nextapi.com.br/account/register) e acesse a área de chaves de API no painel. Gere uma chave e guarde-a no servidor da sua aplicação.

### 2. Execute a primeira consulta

No terminal, substitua `SEU_TOKEN` pelo token obtido no painel e execute:

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps/01001000' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

Uma resposta HTTP `200` indica sucesso. O JSON contém os campos descritos na [referência de consulta de CEP](https://www.nextapi.com.br/docs/api/get-v1-ceps-cep), como `cep`, `logradouro`, `uf` e `codigoIbge`. Alguns campos podem ser nulos.

> A consulta de CEP por número consome 1 crédito no plano gratuito e é isenta nos planos pagos. Os limites por minuto continuam aplicáveis.

### 3. Integre no backend da sua aplicação

Exemplo para Node.js com o token em uma variável de ambiente do seu servidor:

```javascript
const token = process.env.NEXTAPI_TOKEN;
if (!token) throw new Error('Configure NEXTAPI_TOKEN no servidor');

const response = await fetch('https://api.nextapi.com.br/v1/ceps/01001000', {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  signal: AbortSignal.timeout(15000),
});

if (!response.ok) {
  const detail = await response.text();
  throw new Error(`NextAPI: HTTP ${response.status} - ${detail}`);
}
const address = await response.json();
console.log(address);
```

### 4. Escolha a próxima consulta

- [Consultar um CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj).
- [Consultar Simples Nacional e MEI](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-simples).
- [Verificar saldo e limites antes de ampliar o uso](https://www.nextapi.com.br/docs/creditos-e-limites).

Se a chamada falhar, veja o [guia de erros](https://www.nextapi.com.br/docs/erros). Os exemplos não executam consultas automaticamente nem solicitam seu token neste site.

---

## Autenticação

> Envie seu token com segurança em cada requisição.

Fonte: https://www.nextapi.com.br/docs/autenticacao

Envie o token no cabeçalho `Authorization` de cada requisição. Os exemplos desta documentação usam o formato Bearer:

```http
Authorization: Bearer SEU_TOKEN
Accept: application/json
```

A URL base da API é `https://api.nextapi.com.br`. Os endpoints documentados usam o prefixo `/v1`.

### Como obter e usar a chave

1. Entre no [painel da NextAPI](https://admin.nextapi.com.br/) e abra a área de chaves de API.
2. Gere uma chave para sua integração.
3. Configure o token no servidor e envie-o pelo cabeçalho nas chamadas à API.

### Onde guardar o token

Use variáveis de ambiente ou o gerenciador de segredos da sua infraestrutura. Não coloque o token em código do navegador, repositórios públicos ou URLs. Uma aplicação web deve chamar seu próprio backend, que faz a consulta autenticada à NextAPI.

### Falhas de autenticação

Nas consultas REST, a ausência do cabeçalho pode retornar HTTP `400` com código `1001`. Um token inválido retorna HTTP `401` com código `1002`. Verifique o status HTTP e, quando disponível, o campo `code` da resposta.

```json
{
  "status": "Erro",
  "code": 1002,
  "message": "Token de autenticação não informado ou inválido."
}
```

Não repita automaticamente uma chamada com a mesma credencial inválida. Corrija a configuração e tente novamente.

---

## Créditos e limites

> Entenda o consumo, o saldo e as permissões do plano.

Fonte: https://www.nextapi.com.br/docs/creditos-e-limites

Créditos medem o consumo de consultas; o limite de requisições por minuto controla a frequência de acesso. Ter saldo disponível não elimina o limite de frequência nem libera automaticamente todos os recursos.

### Consulte seu saldo

```bash
curl 'https://api.nextapi.com.br/v1/credits' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

Esse endpoint consome **0 créditos** e pode ser chamado com saldo zerado, mantendo a exigência de autenticação e o limite de requisições.

| Campo | Significado |
| --- | --- |
| `planCredits.remaining` | Créditos restantes da assinatura. |
| `extraCredits.remaining` | Créditos avulsos disponíveis. |
| `totalRemainingCredits` | Soma dos saldos disponíveis. |
| `limits.requestsPerMinute` | Limite de requisições por minuto. |
| `limits.canLiveSearch` | Indica se o workspace pode realizar consulta em tempo real. O saldo necessário também é validado ao consultar. |

### Custos por tipo de consulta

| Consulta | Consumo |
| --- | --- |
| CEP por número | 1 crédito no gratuito; isenta nos planos pagos. |
| CNPJ e Simples Nacional em cache | 1 crédito por consulta. |
| CNPJ e Simples Nacional com busca em tempo real | 15 créditos quando a busca externa é realizada. |
| Pesquisa avançada e geoespacial de CEPs | 2 créditos por consulta; planos pagos. |
| CNPJ e Simples em lote | 1 crédito por registro localizado; até 100 CNPJs por requisição; planos pagos. |
| Empresas, CNAEs, estados e municípios | 1 crédito por consulta; planos pagos. |
| Inscrições Estaduais | 1 crédito por consulta. |

Consulte também a descrição do endpoint na [referência](https://www.nextapi.com.br/docs/referencia). Não trate créditos como uma quantidade fixa de consultas: o custo depende da operação e da origem do dado.

### Quando o limite é atingido

HTTP `429` com código `1003` indica excesso de requisições. Distribua as chamadas ao longo do tempo e use retentativas com espera progressiva. Falta de saldo pode retornar HTTP `405` com código `1004`; para busca em tempo real, o código `1006` indica saldo insuficiente.

Os cabeçalhos `RemainingCredits`, `HasCredits` e `PaidPlan` ajudam a acompanhar o estado da assinatura. Para consultar também créditos avulsos, use `/v1/credits`.

[Compare os planos](https://www.nextapi.com.br/#pricing) considerando seus endpoints, volume mensal e picos por minuto.

---

## Atualização dos dados

> Escolha entre cache e consulta com tolerância de atualização.

Fonte: https://www.nextapi.com.br/docs/atualizacao-dos-dados

As consultas individuais de CNPJ e Simples Nacional permitem controlar a tolerância de atualização com `toleranceDays`. O parâmetro é opcional e aceita valores inteiros de **0 a 45**.

| Configuração | Comportamento |
| --- | --- |
| Sem `toleranceDays` | Consulta em cache, sem exigir uma atualização em tempo real. O serviço pode complementar ou atualizar sua base usando o cache do provedor. |
| `toleranceDays=30` | Usa o dado local se estiver dentro da tolerância. Se estiver mais antigo ou ausente, solicita uma busca externa. |
| `toleranceDays=0` | Solicita tolerância zero de atualização. Um dado local fora dessa tolerância exige busca externa. |

```bash
curl 'https://api.nextapi.com.br/v1/cnpj/SEU_CNPJ?toleranceDays=30' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

Para Simples Nacional, use o mesmo parâmetro em `/v1/cnpj/SEU_CNPJ/simples?toleranceDays=30`.

### Permissão e custo

Quando o resultado vem do cache, a consulta custa 1 crédito. Quando é necessária uma busca em tempo real, o custo é 15 créditos e a operação exige permissão e saldo suficiente. Planos pagos ou créditos avulsos podem habilitar essa modalidade; confira `limits.canLiveSearch` em `/v1/credits`.

> Informar uma tolerância não torna o custo fixo em 1 crédito. Dimensione sua integração considerando que uma consulta fora da tolerância pode consumir 15 créditos.

### Latência e indisponibilidade

Uma busca externa pode levar mais tempo que uma leitura em cache e depende da disponibilidade do provedor. Defina timeouts adequados e trate falhas sem apresentar dados antigos como se tivessem sido atualizados naquele momento.

Use o campo `dataAtualizacao`, quando disponível, para informar a data do dado. Campos nulos representam ausência de informação; não os converta automaticamente em respostas negativas.

---

## Tratamento de erros

> Identifique os códigos e saiba como reagir.

Fonte: https://www.nextapi.com.br/docs/erros

Use o status HTTP para identificar o resultado geral e o campo `code`, quando presente, para decidir como sua aplicação deve agir.

```json
{
  "status": "Erro",
  "code": 1003,
  "message": "O número de requisições por minuto excedeu o limite do plano."
}
```

| Código | Significado | O que fazer |
| --- | --- | --- |
| `1000` | Registro não encontrado | Confira o identificador e trate a ausência de dado. |
| `1001` | Token não informado | Envie Authorization no cabeçalho. |
| `1002` | Token inválido | Verifique a chave e a configuração da integração. |
| `1003` | Limite por minuto excedido | Diminua a frequência e aguarde antes de tentar novamente. |
| `1004` | Créditos esgotados | Consulte o saldo e ajuste o plano ou os créditos. |
| `1005` | Tempo real não permitido | Verifique as permissões do workspace. |
| `1006` | Saldo insuficiente para tempo real | Confira o saldo necessário para a busca externa. |
| `1007` | CEP inválido | Confira o formato e os dígitos do CEP. |
| `1008` | Parâmetros geoespaciais ausentes | Informe latitude, longitude e raioMetro. |
| `1009` | Latitude inválida | Use um valor entre -90 e 90. |
| `1010` | Longitude inválida | Use um valor entre -180 e 180. |
| `1011` | Raio inválido | Informe um raio maior que zero, na unidade exigida pelo endpoint. |
| `1012` | Recurso restrito a planos pagos | Confira o plano necessário para a operação. |
| `1013` | Filtros incompatíveis | Não combine q com logradouro. |
| `1014` | Falha do provedor externo | Tente novamente após uma espera, com limite de tentativas. |
| `9999` | Erro não mapeado | Leia a mensagem e registre o contexto sem incluir seu token. |

### Status HTTP

Os endpoints podem responder com estes status:

- `400`: parâmetros ou permissões inválidos.
- `401`: token inválido.
- `404`: registro ausente.
- `405`: falta de créditos.
- `429`: excesso de requisições.
- `500`: falha interna.
- `502`: falha de provedor externo.

As respostas documentadas por operação estão na referência. Falhas de autenticação e de limite podem ocorrer antes da execução do endpoint, mesmo quando não aparecem na lista de respostas do OpenAPI.

### Retentativas

- Não repita automaticamente erros de token, parâmetros ou falta de saldo.
- Para erros transitórios, use espera progressiva e limite de tentativas. Se houver `Retry-After`, respeite-o.
- Uma resposta de erro pode não ter corpo JSON. Verifique o tipo de conteúdo e trate respostas vazias.
- Após um timeout, o servidor pode já ter processado a consulta. Repetir a operação pode gerar novo consumo de créditos.

Se precisar de ajuda, envie à equipe o endpoint, o horário e o código do erro. Não envie seu token.

---

## Usar com IA (MCP)

> Conecte Claude, Cursor e VS Code à NextAPI pelo servidor MCP.

Fonte: https://www.nextapi.com.br/docs/mcp

O servidor MCP (Model Context Protocol) da NextAPI permite que assistentes de IA como Claude, Cursor e VS Code consultem CNPJ, Simples Nacional, CEP e os demais dados da API diretamente na conversa, sem que você escreva código de integração.

```
https://api.nextapi.com.br/mcp
```

O servidor usa o transporte Streamable HTTP. Cada ferramenta corresponde a um endpoint da API e consome créditos como a chamada REST equivalente, respeitando os mesmos limites do seu plano.

### Autenticação

Clientes compatíveis com OAuth, como Claude e Cursor, abrem o login da NextAPI na primeira conexão: entre com sua conta, autorize o acesso e o cliente passa a enviar o token sozinho. Para clientes sem OAuth, envie sua chave de API no cabeçalho `Authorization: Bearer SEU_TOKEN`, como nas chamadas REST. Veja [onde obter e guardar o token](https://www.nextapi.com.br/docs/autenticacao).

### Claude

No Claude (web ou desktop), abra **Configurações › Conectores**, escolha **Adicionar conector personalizado** e informe o nome NextAPI e a URL do servidor. Em seguida, clique em **Conectar** e faça login na NextAPI.

### Claude Code

No terminal, adicione o servidor e depois execute `/mcp` no Claude Code para fazer login:

```bash
claude mcp add --transport http nextapi https://api.nextapi.com.br/mcp
```

### Cursor

Adicione o servidor em `~/.cursor/mcp.json` (ou em `.cursor/mcp.json` no projeto). O Cursor pede o login na NextAPI ao conectar:

```json
{
  "mcpServers": {
    "nextapi": {
      "url": "https://api.nextapi.com.br/mcp"
    }
  }
}
```

### VS Code

Crie `.vscode/mcp.json` no projeto e inicie o servidor pela lista de servidores MCP do VS Code:

```json
{
  "servers": {
    "nextapi": {
      "type": "http",
      "url": "https://api.nextapi.com.br/mcp"
    }
  }
}
```

### Outros clientes, com token

Se o cliente não suportar OAuth, configure o cabeçalho com sua chave de API. Guarde o arquivo fora de repositórios públicos, porque ele passa a conter um segredo:

```json
{
  "mcpServers": {
    "nextapi": {
      "url": "https://api.nextapi.com.br/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    }
  }
}
```

### Ferramentas disponíveis

| Ferramenta | O que consulta |
| --- | --- |
| `Cnpj_Get` | [Dados cadastrais do CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj) |
| `Cnpj_GetSimples` | [Simples Nacional e MEI do CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-simples) |
| `Cnpj_GetInscricoesEstaduais` | [Inscrições Estaduais do CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-ie) |
| `Cnpj_PostBatch` | [CNPJs em lote](https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch) |
| `Cnpj_PostSimplesBatch` | [Simples Nacional em lote](https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch-simples) |
| `Empresas_Get` | [Busca de empresas por filtros](https://www.nextapi.com.br/docs/api/get-v1-empresas) |
| `Ceps_GetByCep` | [Consulta de CEP por número](https://www.nextapi.com.br/docs/api/get-v1-ceps-cep) |
| `Ceps_Search` | [Pesquisa avançada de CEPs](https://www.nextapi.com.br/docs/api/get-v1-ceps) |
| `Ceps_GeoSearch` | [CEPs próximos de uma latitude/longitude](https://www.nextapi.com.br/docs/api/get-v1-ceps-geo) |
| `Ceps_GeoSearchByCep` | [CEPs próximos de um CEP](https://www.nextapi.com.br/docs/api/get-v1-ceps-geo-cep) |
| `Cnaes_GetAll` | [Lista de CNAEs](https://www.nextapi.com.br/docs/api/get-v1-cnaes) |
| `Estados_GetAll` | [Lista de estados](https://www.nextapi.com.br/docs/api/get-v1-estados) |
| `Municipios_GetAll` | [Lista de municípios](https://www.nextapi.com.br/docs/api/get-v1-municipios) |
| `Municipios_GetById` | [Município por ID](https://www.nextapi.com.br/docs/api/get-v1-municipios-id) |
| `Credits_Get` | [Saldo de créditos e limites](https://www.nextapi.com.br/docs/api/get-v1-credits) |

Os parâmetros de cada ferramenta são os mesmos do endpoint na [referência da API](https://www.nextapi.com.br/docs/referencia), incluindo `toleranceDays` nas consultas de CNPJ e Simples Nacional (veja [atualização dos dados](https://www.nextapi.com.br/docs/atualizacao-dos-dados)).

### Exemplos de pedidos

- “Consulte o CNPJ 00.000.000/0001-91 e diga se a empresa está ativa.”
- “Este fornecedor é optante pelo Simples Nacional? CNPJ 00.000.000/0001-91.”
- “Qual é o endereço do CEP 01001-000?”
- “Quantos créditos ainda tenho na NextAPI?”

> O assistente decide quando chamar cada ferramenta, e cada chamada consome créditos. Em tarefas com muitos registros, peça consultas em lote e acompanhe o saldo com `Credits_Get`.

---

## Referência da API

> Consulte parâmetros, modelos, respostas e exemplos de todos os endpoints.

Fonte: https://www.nextapi.com.br/docs/referencia

Explore as 15 operações documentadas. Cada página apresenta parâmetros, corpo da requisição, respostas e modelos do contrato OpenAPI v1. O contrato completo está em https://www.nextapi.com.br/docs/openapi.json.

### CEPs

- [Consulta CEP por número](https://www.nextapi.com.br/docs/api/get-v1-ceps-cep.md): `GET /v1/ceps/{cep}`
- [Pesquisa avançada de CEPs](https://www.nextapi.com.br/docs/api/get-v1-ceps.md): `GET /v1/ceps`
- [Pesquisa geoespacial de CEPs por Latitude/Longitude](https://www.nextapi.com.br/docs/api/get-v1-ceps-geo.md): `GET /v1/ceps/geo`
- [Pesquisa geoespacial de CEPs](https://www.nextapi.com.br/docs/api/get-v1-ceps-geo-cep.md): `GET /v1/ceps/geo/{cep}`

### CNAEs

- [Lista CNAEs](https://www.nextapi.com.br/docs/api/get-v1-cnaes.md): `GET /v1/cnaes`

### CNPJ

- [Busca CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj.md): `GET /v1/cnpj/{cnpj}`
- [Busca dados do Simples Nacional do CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-simples.md): `GET /v1/cnpj/{cnpj}/simples`
- [Busca Inscrições Estaduais do CNPJ](https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-ie.md): `GET /v1/cnpj/{cnpj}/ie`
- [Busca CNPJs em lote](https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch.md): `POST /v1/cnpj/batch`
- [Busca dados do Simples Nacional em lote](https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch-simples.md): `POST /v1/cnpj/batch/simples`

### Créditos

- [Consulta Saldo de Créditos](https://www.nextapi.com.br/docs/api/get-v1-credits.md): `GET /v1/credits`

### Empresas

- [Busca Empresas](https://www.nextapi.com.br/docs/api/get-v1-empresas.md): `GET /v1/empresas`

### Estados

- [Lista Estados](https://www.nextapi.com.br/docs/api/get-v1-estados.md): `GET /v1/estados`

### Municípios

- [Lista Municípios](https://www.nextapi.com.br/docs/api/get-v1-municipios.md): `GET /v1/municipios`
- [Obtém Município por ID](https://www.nextapi.com.br/docs/api/get-v1-municipios-id.md): `GET /v1/municipios/{id}`

---

## Consulta CEP por número

> Parâmetros, exemplos e respostas de GET /v1/ceps/{cep} na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-ceps-cep

`GET /v1/ceps/{cep}`

Retorna as informações do CEP informado.

- Cada consulta no plano gratuito consome 1 crédito, nos planos pagos a consulta é isenta de custos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps/01001000' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `cep` | path | Sim | `string` | Número do CEP (somente dígitos, ex: 01310100) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CepItemResponse |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `404` | Registro não localizado | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "cep": "string",
  "logradouro": "string",
  "localidade": "string",
  "idMunicipio": 0,
  "nomeMunicipio": "string",
  "uf": "string",
  "latitude": 0,
  "longitude": 0,
  "dataAtualizacao": "2026-01-01T00:00:00",
  "codigoIbge": {
    "municipio": 0,
    "estado": 0,
    "pais": 0
  }
}
```

### Campos da resposta

Modelo: `CepItemResponse`

#### CepItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cep` | `string \| null` | Sim | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `localidade` | `string \| null` | Não marcado no contrato | — |
| `idMunicipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `nomeMunicipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `latitude` | `number (double) \| null` | Não marcado no contrato | — |
| `longitude` | `number (double) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string (date-time) \| null` | Não marcado no contrato | — |
| `codigoIbge` | `CepCodigoIbgeResponse` | Não marcado no contrato | — |

#### CepCodigoIbgeResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `municipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `estado` | `integer (int32) \| null` | Não marcado no contrato | — |
| `pais` | `integer (int32) \| null` | Não marcado no contrato | — |

---

## Pesquisa avançada de CEPs

> Parâmetros, exemplos e respostas de GET /v1/ceps na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-ceps

`GET /v1/ceps`

Retorna uma lista paginada de CEPs com base nos filtros fornecidos.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Limite global de 2.000 itens.
- Cada consulta consome 2 créditos.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `uf` | query | Não | `string` | Sigla do estado (ex: SP, RJ) |
| `idMunicipio` | query | Não | `integer (int32)` | Código do município |
| `nomeMunicipio` | query | Não | `string` | Nome do município para filtro (busca parcial) |
| `logradouro` | query | Não | `string` | Nome do logradouro para filtro (busca parcial) |
| `q` | query | Não | `string` | Busca global, realiza busca por palavra/texto nos campos cep, logradouro, localidade, nomeMunicipio e uf |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CepItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "cep": "string",
      "logradouro": "string",
      "localidade": "string",
      "idMunicipio": 0,
      "nomeMunicipio": "string",
      "uf": "string",
      "latitude": 0,
      "longitude": 0,
      "dataAtualizacao": "2026-01-01T00:00:00",
      "codigoIbge": {
        "municipio": 0,
        "estado": 0,
        "pais": 0
      }
    }
  ]
}
```

### Campos da resposta

Modelo: `CepItemResponsePagedResult`

#### CepItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CepItemResponse[]` | Não marcado no contrato | — |

#### CepItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cep` | `string \| null` | Sim | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `localidade` | `string \| null` | Não marcado no contrato | — |
| `idMunicipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `nomeMunicipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `latitude` | `number (double) \| null` | Não marcado no contrato | — |
| `longitude` | `number (double) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string (date-time) \| null` | Não marcado no contrato | — |
| `codigoIbge` | `CepCodigoIbgeResponse` | Não marcado no contrato | — |

#### CepCodigoIbgeResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `municipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `estado` | `integer (int32) \| null` | Não marcado no contrato | — |
| `pais` | `integer (int32) \| null` | Não marcado no contrato | — |

---

## Pesquisa geoespacial de CEPs por Latitude/Longitude

> Parâmetros, exemplos e respostas de GET /v1/ceps/geo na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-ceps-geo

`GET /v1/ceps/geo`

Retorna uma lista paginada de CEPs próximos a uma coordenada informada (latitude/longitude) dentro de um raio em metros.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Limite global de 2.000 itens.
- Cada consulta consome 2 créditos.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps/geo?latitude=VALOR_latitude&longitude=VALOR_longitude&raioMetro=VALOR_raioMetro' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `latitude` | query | Sim | `number (double)` | Latitude do ponto de referência (ex: -23.5489) |
| `longitude` | query | Sim | `number (double)` | Longitude do ponto de referência (ex: -46.6388) |
| `raioMetro` | query | Sim | `number (double)` | Raio em metros ao redor do ponto de referência |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CepItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "cep": "string",
      "logradouro": "string",
      "localidade": "string",
      "idMunicipio": 0,
      "nomeMunicipio": "string",
      "uf": "string",
      "latitude": 0,
      "longitude": 0,
      "dataAtualizacao": "2026-01-01T00:00:00",
      "codigoIbge": {
        "municipio": 0,
        "estado": 0,
        "pais": 0
      }
    }
  ]
}
```

### Campos da resposta

Modelo: `CepItemResponsePagedResult`

#### CepItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CepItemResponse[]` | Não marcado no contrato | — |

#### CepItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cep` | `string \| null` | Sim | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `localidade` | `string \| null` | Não marcado no contrato | — |
| `idMunicipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `nomeMunicipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `latitude` | `number (double) \| null` | Não marcado no contrato | — |
| `longitude` | `number (double) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string (date-time) \| null` | Não marcado no contrato | — |
| `codigoIbge` | `CepCodigoIbgeResponse` | Não marcado no contrato | — |

#### CepCodigoIbgeResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `municipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `estado` | `integer (int32) \| null` | Não marcado no contrato | — |
| `pais` | `integer (int32) \| null` | Não marcado no contrato | — |

---

## Pesquisa geoespacial de CEPs

> Parâmetros, exemplos e respostas de GET /v1/ceps/geo/{cep} na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-ceps-geo-cep

`GET /v1/ceps/geo/{cep}`

Retorna uma lista paginada de CEPs próximos a um CEP informado, dentro de um raio em metros.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Limite global de 2.000 itens.
- Cada consulta consome 2 créditos.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/ceps/geo/01001000?raioMetro=VALOR_raioMetro' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `cep` | path | Sim | `string` | Número do CEP (somente dígitos, ex: 01310100) |
| `raioMetro` | query | Sim | `number (double)` | Raio em metros ao redor do ponto de referência |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CepItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "cep": "string",
      "logradouro": "string",
      "localidade": "string",
      "idMunicipio": 0,
      "nomeMunicipio": "string",
      "uf": "string",
      "latitude": 0,
      "longitude": 0,
      "dataAtualizacao": "2026-01-01T00:00:00",
      "codigoIbge": {
        "municipio": 0,
        "estado": 0,
        "pais": 0
      }
    }
  ]
}
```

### Campos da resposta

Modelo: `CepItemResponsePagedResult`

#### CepItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CepItemResponse[]` | Não marcado no contrato | — |

#### CepItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cep` | `string \| null` | Sim | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `localidade` | `string \| null` | Não marcado no contrato | — |
| `idMunicipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `nomeMunicipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `latitude` | `number (double) \| null` | Não marcado no contrato | — |
| `longitude` | `number (double) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string (date-time) \| null` | Não marcado no contrato | — |
| `codigoIbge` | `CepCodigoIbgeResponse` | Não marcado no contrato | — |

#### CepCodigoIbgeResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `municipio` | `integer (int32) \| null` | Não marcado no contrato | — |
| `estado` | `integer (int32) \| null` | Não marcado no contrato | — |
| `pais` | `integer (int32) \| null` | Não marcado no contrato | — |

---

## Lista CNAEs

> Parâmetros, exemplos e respostas de GET /v1/cnaes na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-cnaes

`GET /v1/cnaes`

Retorna uma lista paginada com os CNAEs cadastrados na base

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Cada consulta consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/cnaes' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnaeItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "codigo": "string",
      "descricao": "string"
    }
  ]
}
```

### Campos da resposta

Modelo: `CnaeItemResponsePagedResult`

#### CnaeItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CnaeItemResponse[]` | Não marcado no contrato | — |

#### CnaeItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `codigo` | `string \| null` | Sim | — |
| `descricao` | `string \| null` | Não marcado no contrato | — |

---

## Busca CNPJ

> Parâmetros, exemplos e respostas de GET /v1/cnpj/{cnpj} na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj

`GET /v1/cnpj/{cnpj}`

Pesquisa pelo CNPJ informado na base da Receita Federal e retorna os dados do estabelecimento comercial

Cada consulta consome 1 crédito.

> O custo de 1 crédito se aplica ao cache. Uma busca em tempo real pode consumir 15 créditos e exige permissão e saldo. Veja [como funciona toleranceDays](https://www.nextapi.com.br/docs/atualizacao-dos-dados.md).

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/cnpj/SEU_CNPJ' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `cnpj` | path | Sim | `string` | Número do CNPJ (somente dígitos, ex: 00000000000191) |
| `toleranceDays` | query | Não | `integer (int32)` | Quantidade máxima de dias de tolerância do cache (0 a 45) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjItemResponse |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `404` | Registro não localizado | objeto |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "cnpj": "string",
  "razaoSocial": "string",
  "nomeFantasia": "string",
  "tipo": "string",
  "dataAbertura": "string",
  "situacaoCadastral": "string",
  "dataSituacaoCadastral": "string",
  "motivoSituacaoCadastral": "string",
  "porte": "string",
  "capitalSocial": 0,
  "naturezaJuridica": "string",
  "logradouro": "string",
  "numero": "string",
  "complemento": "string",
  "cep": "string",
  "bairro": "string",
  "municipio": "string",
  "uf": "string",
  "email": "string",
  "telefone": "string",
  "situacaoEspecial": "string",
  "dataSituacaoEspecial": "string",
  "atividadePrincipal": {
    "codigo": "string",
    "descricao": "string"
  },
  "atividadeSecundaria": [
    {
      "codigo": "string",
      "descricao": "string"
    }
  ],
  "quadroDeSocios": [
    {
      "nome": "string",
      "qualificacao": "string",
      "representanteLegal": "string",
      "qualificacaoRepresentanteLegal": "string",
      "paisOrigem": "string"
    }
  ],
  "dataAtualizacao": "string"
}
```

### Campos da resposta

Modelo: `CnpjItemResponse`

#### CnpjItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `razaoSocial` | `string \| null` | Não marcado no contrato | — |
| `nomeFantasia` | `string \| null` | Não marcado no contrato | — |
| `tipo` | `string \| null` | Não marcado no contrato | — |
| `dataAbertura` | `string \| null` | Não marcado no contrato | — |
| `situacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `dataSituacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `motivoSituacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `porte` | `string \| null` | Não marcado no contrato | — |
| `capitalSocial` | `number (double) \| null` | Não marcado no contrato | — |
| `naturezaJuridica` | `string \| null` | Não marcado no contrato | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `numero` | `string \| null` | Não marcado no contrato | — |
| `complemento` | `string \| null` | Não marcado no contrato | — |
| `cep` | `string \| null` | Não marcado no contrato | — |
| `bairro` | `string \| null` | Não marcado no contrato | — |
| `municipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `email` | `string \| null` | Não marcado no contrato | — |
| `telefone` | `string \| null` | Não marcado no contrato | — |
| `situacaoEspecial` | `string \| null` | Não marcado no contrato | — |
| `dataSituacaoEspecial` | `string \| null` | Não marcado no contrato | — |
| `atividadePrincipal` | `CnpjItemResponseCode` | Não marcado no contrato | — |
| `atividadeSecundaria` | `CnpjItemResponseCode[]` | Não marcado no contrato | — |
| `quadroDeSocios` | `CnpjItemResponsePartner[]` | Não marcado no contrato | — |
| `dataAtualizacao` | `string \| null` | Não marcado no contrato | — |

#### CnpjItemResponseCode

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `codigo` | `string \| null` | Não marcado no contrato | — |
| `descricao` | `string \| null` | Não marcado no contrato | — |

#### CnpjItemResponsePartner

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `nome` | `string \| null` | Não marcado no contrato | — |
| `qualificacao` | `string \| null` | Não marcado no contrato | — |
| `representanteLegal` | `string \| null` | Não marcado no contrato | — |
| `qualificacaoRepresentanteLegal` | `string \| null` | Não marcado no contrato | — |
| `paisOrigem` | `string \| null` | Não marcado no contrato | — |

---

## Busca dados do Simples Nacional do CNPJ

> Parâmetros, exemplos e respostas de GET /v1/cnpj/{cnpj}/simples na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-simples

`GET /v1/cnpj/{cnpj}/simples`

Retorna os dados do Simples Nacional para o CNPJ informado.

- Cada consulta consome 1 crédito.
- Disponível em todos os planos (no plano gratuito, restrito à base local/cache).

> O custo de 1 crédito se aplica ao cache. Uma busca em tempo real pode consumir 15 créditos e exige permissão e saldo. Veja [como funciona toleranceDays](https://www.nextapi.com.br/docs/atualizacao-dos-dados.md).

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/cnpj/SEU_CNPJ/simples' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `cnpj` | path | Sim | `string` | Número do CNPJ (somente dígitos, ex: 00000000000191) |
| `toleranceDays` | query | Não | `integer (int32)` | Quantidade máxima de dias de tolerância do cache (0 a 45) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjSimplesResponse |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `404` | Registro não localizado | objeto |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "cnpj": "string",
  "opcaoPeloSimples": false,
  "dataOpcaoPeloSimples": "2026-01-01T00:00:00",
  "dataExclusaoDoSimples": "2026-01-01T00:00:00",
  "opcaoPeloMEI": false,
  "dataOpcaoPeloMEI": "2026-01-01T00:00:00",
  "dataExclusaoDoMEI": "2026-01-01T00:00:00",
  "dataAtualizacao": "string"
}
```

### Campos da resposta

Modelo: `CnpjSimplesResponse`

#### CnpjSimplesResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `opcaoPeloSimples` | `boolean \| null` | Não marcado no contrato | — |
| `dataOpcaoPeloSimples` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataExclusaoDoSimples` | `string (date-time) \| null` | Não marcado no contrato | — |
| `opcaoPeloMEI` | `boolean \| null` | Não marcado no contrato | — |
| `dataOpcaoPeloMEI` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataExclusaoDoMEI` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string \| null` | Não marcado no contrato | — |

---

## Busca Inscrições Estaduais do CNPJ

> Parâmetros, exemplos e respostas de GET /v1/cnpj/{cnpj}/ie na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-cnpj-cnpj-ie

`GET /v1/cnpj/{cnpj}/ie`

Retorna as Inscrições Estaduais (IE) disponíveis para o CNPJ informado.

- Um CNPJ pode possuir mais de uma IE (uma por UF), por isso a resposta é uma lista.
- Dado essencial para emissão de Nota Fiscal.
- A cobertura é limitada aos estados que publicam a base pública de Inscrições Estaduais: atualmente SP, PR e MG. CNPJs de outras UFs, ou sem IE registrada, retornam lista vazia.
- Cada consulta consome 1 crédito. Disponível em todos os planos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/cnpj/SEU_CNPJ/ie' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `cnpj` | path | Sim | `string` | Número do CNPJ (somente dígitos, ex: 00000000000191) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjInscricaoEstadualResponse[] |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
[
  {
    "cnpj": "string",
    "inscricaoEstadual": "string",
    "uf": "string",
    "situacao": "string",
    "cnae": "string",
    "municipio": "string",
    "dataAtualizacao": "string"
  }
]
```

### Campos da resposta

Modelo: `CnpjInscricaoEstadualResponse[]`

#### CnpjInscricaoEstadualResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `inscricaoEstadual` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `situacao` | `string \| null` | Não marcado no contrato | — |
| `cnae` | `string \| null` | Não marcado no contrato | — |
| `municipio` | `string \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string \| null` | Não marcado no contrato | — |

---

## Busca CNPJs em lote

> Parâmetros, exemplos e respostas de POST /v1/cnpj/batch na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch

`POST /v1/cnpj/batch`

Pesquisa por uma lista de CNPJs informada no corpo da requisição e retorna os dados dos estabelecimentos localizados.

- Limite de 100 CNPJs por requisição.
- Cada registro localizado consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request POST 'https://api.nextapi.com.br/v1/cnpj/batch' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"cnpjs":["SEU_CNPJ"]}'
```

### Parâmetros

Esta operação não declara parâmetros de rota ou query no contrato.

### Corpo da requisição

Envie JSON com `Content-Type: application/json`. 

Modelo: `BatchCnpjRequest`

#### BatchCnpjRequest

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpjs` | `string[]` | Não marcado no contrato | — |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjItemResponse[] |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
[
  {
    "cnpj": "string",
    "razaoSocial": "string",
    "nomeFantasia": "string",
    "tipo": "string",
    "dataAbertura": "string",
    "situacaoCadastral": "string",
    "dataSituacaoCadastral": "string",
    "motivoSituacaoCadastral": "string",
    "porte": "string",
    "capitalSocial": 0,
    "naturezaJuridica": "string",
    "logradouro": "string",
    "numero": "string",
    "complemento": "string",
    "cep": "string",
    "bairro": "string",
    "municipio": "string",
    "uf": "string",
    "email": "string",
    "telefone": "string",
    "situacaoEspecial": "string",
    "dataSituacaoEspecial": "string",
    "atividadePrincipal": {
      "codigo": "string",
      "descricao": "string"
    },
    "atividadeSecundaria": [
      {
        "codigo": "string",
        "descricao": "string"
      }
    ],
    "quadroDeSocios": [
      {
        "nome": "string",
        "qualificacao": "string",
        "representanteLegal": "string",
        "qualificacaoRepresentanteLegal": "string",
        "paisOrigem": "string"
      }
    ],
    "dataAtualizacao": "string"
  }
]
```

### Campos da resposta

Modelo: `CnpjItemResponse[]`

#### CnpjItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `razaoSocial` | `string \| null` | Não marcado no contrato | — |
| `nomeFantasia` | `string \| null` | Não marcado no contrato | — |
| `tipo` | `string \| null` | Não marcado no contrato | — |
| `dataAbertura` | `string \| null` | Não marcado no contrato | — |
| `situacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `dataSituacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `motivoSituacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `porte` | `string \| null` | Não marcado no contrato | — |
| `capitalSocial` | `number (double) \| null` | Não marcado no contrato | — |
| `naturezaJuridica` | `string \| null` | Não marcado no contrato | — |
| `logradouro` | `string \| null` | Não marcado no contrato | — |
| `numero` | `string \| null` | Não marcado no contrato | — |
| `complemento` | `string \| null` | Não marcado no contrato | — |
| `cep` | `string \| null` | Não marcado no contrato | — |
| `bairro` | `string \| null` | Não marcado no contrato | — |
| `municipio` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |
| `email` | `string \| null` | Não marcado no contrato | — |
| `telefone` | `string \| null` | Não marcado no contrato | — |
| `situacaoEspecial` | `string \| null` | Não marcado no contrato | — |
| `dataSituacaoEspecial` | `string \| null` | Não marcado no contrato | — |
| `atividadePrincipal` | `CnpjItemResponseCode` | Não marcado no contrato | — |
| `atividadeSecundaria` | `CnpjItemResponseCode[]` | Não marcado no contrato | — |
| `quadroDeSocios` | `CnpjItemResponsePartner[]` | Não marcado no contrato | — |
| `dataAtualizacao` | `string \| null` | Não marcado no contrato | — |

#### CnpjItemResponseCode

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `codigo` | `string \| null` | Não marcado no contrato | — |
| `descricao` | `string \| null` | Não marcado no contrato | — |

#### CnpjItemResponsePartner

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `nome` | `string \| null` | Não marcado no contrato | — |
| `qualificacao` | `string \| null` | Não marcado no contrato | — |
| `representanteLegal` | `string \| null` | Não marcado no contrato | — |
| `qualificacaoRepresentanteLegal` | `string \| null` | Não marcado no contrato | — |
| `paisOrigem` | `string \| null` | Não marcado no contrato | — |

---

## Busca dados do Simples Nacional em lote

> Parâmetros, exemplos e respostas de POST /v1/cnpj/batch/simples na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/post-v1-cnpj-batch-simples

`POST /v1/cnpj/batch/simples`

Pesquisa por uma lista de CNPJs informada no corpo da requisição e retorna os dados do Simples Nacional dos estabelecimentos localizados.

- Limite de 100 CNPJs por requisição.
- Cada registro localizado consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request POST 'https://api.nextapi.com.br/v1/cnpj/batch/simples' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"cnpjs":["SEU_CNPJ"]}'
```

### Parâmetros

Esta operação não declara parâmetros de rota ou query no contrato.

### Corpo da requisição

Envie JSON com `Content-Type: application/json`. 

Modelo: `BatchCnpjRequest`

#### BatchCnpjRequest

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpjs` | `string[]` | Não marcado no contrato | — |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjSimplesResponse[] |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
[
  {
    "cnpj": "string",
    "opcaoPeloSimples": false,
    "dataOpcaoPeloSimples": "2026-01-01T00:00:00",
    "dataExclusaoDoSimples": "2026-01-01T00:00:00",
    "opcaoPeloMEI": false,
    "dataOpcaoPeloMEI": "2026-01-01T00:00:00",
    "dataExclusaoDoMEI": "2026-01-01T00:00:00",
    "dataAtualizacao": "string"
  }
]
```

### Campos da resposta

Modelo: `CnpjSimplesResponse[]`

#### CnpjSimplesResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `opcaoPeloSimples` | `boolean \| null` | Não marcado no contrato | — |
| `dataOpcaoPeloSimples` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataExclusaoDoSimples` | `string (date-time) \| null` | Não marcado no contrato | — |
| `opcaoPeloMEI` | `boolean \| null` | Não marcado no contrato | — |
| `dataOpcaoPeloMEI` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataExclusaoDoMEI` | `string (date-time) \| null` | Não marcado no contrato | — |
| `dataAtualizacao` | `string \| null` | Não marcado no contrato | — |

---

## Consulta Saldo de Créditos

> Parâmetros, exemplos e respostas de GET /v1/credits na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-credits

`GET /v1/credits`

Retorna o saldo detalhado de créditos da assinatura e créditos extras, além dos limites associados ao workspace atual.

- Esta operação é isenta (consome 0 créditos).
- A consulta pode ser executada mesmo se o saldo estiver zerado.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/credits' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

Esta operação não declara parâmetros de rota ou query no contrato.

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | WorkspaceCreditsResponse |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `401` | Token de autenticação inválido ou ausente | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "workspaceId": 0,
  "monthReference": "string",
  "planCredits": {
    "allocated": 0,
    "remaining": 0
  },
  "extraCredits": {
    "remaining": 0
  },
  "totalRemainingCredits": 0,
  "limits": {
    "requestsPerMinute": 0,
    "allowExternalSearch": false,
    "canLiveSearch": false
  }
}
```

### Campos da resposta

Modelo: `WorkspaceCreditsResponse`

#### WorkspaceCreditsResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `workspaceId` | `integer (int64)` | Não marcado no contrato | — |
| `monthReference` | `string \| null` | Não marcado no contrato | — |
| `planCredits` | `PlanCreditsInfo` | Não marcado no contrato | — |
| `extraCredits` | `ExtraCreditsInfo` | Não marcado no contrato | — |
| `totalRemainingCredits` | `integer (int32)` | Não marcado no contrato | — |
| `limits` | `LimitsInfo` | Não marcado no contrato | — |

#### PlanCreditsInfo

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `allocated` | `integer (int32)` | Não marcado no contrato | — |
| `remaining` | `integer (int32)` | Não marcado no contrato | — |

#### ExtraCreditsInfo

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `remaining` | `integer (int32)` | Não marcado no contrato | — |

#### LimitsInfo

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `requestsPerMinute` | `integer (int32)` | Não marcado no contrato | — |
| `allowExternalSearch` | `boolean` | Não marcado no contrato | — |
| `canLiveSearch` | `boolean` | Não marcado no contrato | — |

---

## Busca Empresas

> Parâmetros, exemplos e respostas de GET /v1/empresas na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-empresas

`GET /v1/empresas`

Busca Empresas e Estabelecimentos cadastrados na Receita Federal com filtros avançados.

- O resultado da consulta é paginado com limite de até 100 itens por página (padrão 20) e 5.000 itens totais.
- Cada consulta consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/empresas' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `uf` | query | Não | `string` | Sigla do estado para filtro (ex: SP, RJ) |
| `codigoMunicipio` | query | Não | `string` | Código(s) do município, separados por vírgula (ex: 3550308,3304557) |
| `cnpjRaiz` | query | Não | `string` | CNPJ raiz (8 primeiros dígitos) para filtro |
| `cnpj` | query | Não | `string` | Número completo do CNPJ para filtro (somente dígitos) |
| `q` | query | Não | `string` | Busca pelo início da Razão Social ou Nome Fantasia (mínimo 3 caracteres) |
| `dataAberturaInicio` | query | Não | `string (date-time)` | Data de abertura inicial do intervalo de filtro (formato: yyyy-MM-dd) |
| `dataAberturaFim` | query | Não | `string (date-time)` | Data de abertura final do intervalo de filtro (formato: yyyy-MM-dd) |
| `codigoSituacaoCadastral` | query | Não | `string` | Código(s) de situação cadastral separados por vírgula (01=Nula, 02=Ativa, 03=Suspensa, 04=Inapta, 08=Baixada) |
| `ceps` | query | Não | `string` | CEP(s) para filtro, separados por vírgula |
| `cnaes` | query | Não | `string` | Código(s) CNAE (somente números) para filtro, separados por vírgula |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | CnpjSimplifiedResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | IErrorCodeModel |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "cnpj": "string",
      "razaoSocial": "string",
      "situacaoCadastral": "string",
      "uf": "string"
    }
  ]
}
```

### Campos da resposta

Modelo: `CnpjSimplifiedResponsePagedResult`

#### CnpjSimplifiedResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `CnpjSimplifiedResponse[]` | Não marcado no contrato | — |

#### CnpjSimplifiedResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `cnpj` | `string \| null` | Não marcado no contrato | — |
| `razaoSocial` | `string \| null` | Não marcado no contrato | — |
| `situacaoCadastral` | `string \| null` | Não marcado no contrato | — |
| `uf` | `string \| null` | Não marcado no contrato | — |

---

## Lista Estados

> Parâmetros, exemplos e respostas de GET /v1/estados na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-estados

`GET /v1/estados`

Retorna uma lista paginada com os Estados da união.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Cada consulta consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/estados' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | EstadoItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | objeto |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "uf": "string",
      "nome": "string",
      "totalEstabelecimentos": 0
    }
  ]
}
```

### Campos da resposta

Modelo: `EstadoItemResponsePagedResult`

#### EstadoItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `EstadoItemResponse[]` | Não marcado no contrato | — |

#### EstadoItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `uf` | `string \| null` | Sim | — |
| `nome` | `string \| null` | Não marcado no contrato | — |
| `totalEstabelecimentos` | `integer (int64) \| null` | Não marcado no contrato | — |

---

## Lista Municípios

> Parâmetros, exemplos e respostas de GET /v1/municipios na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-municipios

`GET /v1/municipios`

Lista todos os municípios de forma paginada, com filtro opcional por UF.

- O resultado da consulta é paginado com limite de 200 itens por pagina.
- Cada consulta consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/municipios' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `uf` | query | Não | `string` | Sigla do estado para filtro (ex: SP, RJ) |
| `page` | query | Não | `integer (int32)` | Número da página (padrão: 1) |
| `pageSize` | query | Não | `integer (int32)` | Quantidade de itens por página (máx: 200) |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | MunicipioItemResponsePagedResult |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | IErrorCodeModel |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "items": [
    {
      "id": 0,
      "descricao": "string",
      "uf": "string"
    }
  ]
}
```

### Campos da resposta

Modelo: `MunicipioItemResponsePagedResult`

#### MunicipioItemResponsePagedResult

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `page` | `integer (int32)` | Não marcado no contrato | — |
| `pageSize` | `integer (int32)` | Não marcado no contrato | — |
| `total` | `integer (int64)` | Não marcado no contrato | — |
| `items` | `MunicipioItemResponse[]` | Não marcado no contrato | — |

#### MunicipioItemResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `id` | `integer (int32)` | Sim | — |
| `descricao` | `string \| null` | Sim | — |
| `uf` | `string \| null` | Sim | — |

---

## Obtém Município por ID

> Parâmetros, exemplos e respostas de GET /v1/municipios/{id} na NextAPI.

Fonte: https://www.nextapi.com.br/docs/api/get-v1-municipios-id

`GET /v1/municipios/{id}`

Obtém os dados completos de um município específico pelo seu ID.

- Retorna todos os dados do município incluindo população, empresas e divisões territoriais.
- Cada consulta consome 1 crédito.
- Disponível somente nos planos pagos.

URL base: `https://api.nextapi.com.br`. Autenticação: cabeçalho `Authorization: Bearer SEU_TOKEN`.

### Exemplo de requisição

```bash
curl --request GET 'https://api.nextapi.com.br/v1/municipios/ID_MUNICIPIO' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

### Parâmetros

| Nome | Local | Obrigatório | Tipo / regras | Descrição |
| --- | --- | --- | --- | --- |
| `id` | path | Sim | `integer (int32)` | ID do município |

### Respostas HTTP

| Status | Descrição | Formato JSON |
| --- | --- | --- |
| `200` | Operação realizada com sucesso | MunicipioDetalhadoResponse |
| `400` | Erro nos parametros informados na requisição | IErrorCodeModel |
| `404` | Registro não localizado | IErrorCodeModel |
| `405` | Falta de créditos para realizar a consulta | IErrorCodeModel |
| `500` | Erro ao processar a requisição | IErrorCodeModel |

Autenticação e limites também podem gerar erros antes da execução da operação. Veja o [guia de tratamento de erros](https://www.nextapi.com.br/docs/erros.md).

### Resposta de sucesso

Exemplo estrutural gerado do schema: os valores são ilustrativos. Campos anuláveis podem retornar `null`.

```json
{
  "id": 0,
  "descricao": "string",
  "uf": "string",
  "codigoIbge": "string",
  "populacaoEstimada": 0,
  "regiao": "string",
  "mesorregiao": {
    "codigo": "string",
    "nome": "string"
  },
  "microrregiao": {
    "codigo": "string",
    "nome": "string"
  },
  "regiaoImediata": {
    "codigo": "string",
    "nome": "string"
  },
  "regiaoIntermediaria": {
    "codigo": "string",
    "nome": "string"
  },
  "ibgeAtualizadoEm": "2026-01-01T00:00:00",
  "totalEmpresas": 0
}
```

### Campos da resposta

Modelo: `MunicipioDetalhadoResponse`

#### MunicipioDetalhadoResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `id` | `integer (int32)` | Sim | — |
| `descricao` | `string \| null` | Sim | — |
| `uf` | `string \| null` | Sim | — |
| `codigoIbge` | `string \| null` | Não marcado no contrato | — |
| `populacaoEstimada` | `integer (int64) \| null` | Não marcado no contrato | — |
| `regiao` | `string \| null` | Não marcado no contrato | — |
| `mesorregiao` | `MunicipioHierarquiaResponse` | Não marcado no contrato | — |
| `microrregiao` | `MunicipioHierarquiaResponse` | Não marcado no contrato | — |
| `regiaoImediata` | `MunicipioHierarquiaResponse` | Não marcado no contrato | — |
| `regiaoIntermediaria` | `MunicipioHierarquiaResponse` | Não marcado no contrato | — |
| `ibgeAtualizadoEm` | `string (date-time) \| null` | Não marcado no contrato | — |
| `totalEmpresas` | `integer (int64) \| null` | Não marcado no contrato | — |

#### MunicipioHierarquiaResponse

| Campo | Tipo | Obrigatório | Descrição / regras |
| --- | --- | --- | --- |
| `codigo` | `string \| null` | Sim | — |
| `nome` | `string \| null` | Sim | — |