# 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 | — |