# CNPJ

> API de consulta de dados cadastrais e geocodificados de pessoas jurídicas brasileiras (CNPJ). A fonte primária é a base pública da Receita Federal, enriquecida com dados de geocodificação e sumarizações prontas para análise.

**Base**: `https://api.prismadata.io/v1`

**Autenticação**: header `X-Apikey` (ou query `api_key`). Detalhes em [Autenticação](autenticacao.md).

**Formato de resposta**: JSON plano com campos `prismadata__<serviço>__<campo>`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md).

## Endpoints

### `GET /cnpj/raw/metadata`

Metadata cru com cobertura_geo aninhada.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/raw/metadata" \
  -H "X-Apikey: SEU_TOKEN"
```

**Response 200** (`application/json`):

> Metadados da versao atual dos dados (cobertura por classe de qualidade geografica como objeto aninhado).

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__versao_dados` | string \| null | não | Versao do dataset atual (`YYYYMMDD`). |
| `prismadata__pessoa_juridica__data_publicacao_rfb` | string \| null | não | Data da publicacao dos dados pela Receita Federal. |
| `prismadata__pessoa_juridica__data_processamento` | string \| null | não | Data e hora do enriquecimento dos dados. |
| `prismadata__pessoa_juridica__total_cnpjs_carregados` | integer | sim | Total de CNPJs disponiveis na versao atual. |
| `prismadata__pessoa_juridica__cobertura_geo` | object | sim | Objeto com a distribuicao dos CNPJs por classe de qualidade da geocodificacao. |
| `prismadata__pessoa_juridica__historico_competencia_min` | string \| null | não | Competencia mais antiga carregada na serie historica (`YYYY-MM-DD`). |
| `prismadata__pessoa_juridica__historico_competencia_max` | string \| null | não | Competencia mais recente carregada na serie historica (`YYYY-MM-DD`). |
| `prismadata__pessoa_juridica__historico_total_competencias` | integer \| null | não | Total de competencias mensais distintas presentes na serie. |
| `prismadata__pessoa_juridica__historico_competencias_ausentes` | array[string] | não | Competencias que faltam entre `competencia_min` e `competencia_max` (ex.: `["2025-01-01"]`). Ausencias declaradas — se lista vazia, cobertura completa. |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `POST /cnpj/raw/batch`

Lote raw. OUTPUT eh dict {cnpj: CnpjF1_completo ou null}.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/cnpj/raw/batch" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "cnpjs": [
           "11222333000144"
         ]
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `cnpjs` | array[string] | sim |  |

**Response 200** (`application/json`):

> Dicionario indexado pelo CNPJ com dados completos. Valor `null` para CNPJs invalidos ou nao encontrados. Limite: 256 CNPJs por chamada.

Dicionário `{string: object \| null}`.
Resultado da consulta detalhada em lote: dicionario indexado pelo CNPJ.

**Outros códigos**: 401, 403, 404, 422, 429

---

### `GET /cnpj/raw/{cnpj}`

Lookup raw — CnpjF1 completo com socios + cnaes_secundarios.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/raw/11222333000144" \
  -H "X-Apikey: SEU_TOKEN"
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `cnpj` | path | string | sim | CNPJ com ou sem mascara (alfanumerico aceito) |

**Response 200** (`application/json`):

> Dados do CNPJ na consulta detalhada (com lista completa de socios e CNAEs).

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__cnpj` | string | sim | CNPJ de 14 caracteres, sem mascara. |
| `prismadata__pessoa_juridica__cnpj_basico` | string | sim |  |
| `prismadata__pessoa_juridica__cnpj_ordem` | string | sim |  |
| `prismadata__pessoa_juridica__cnpj_dv` | string | sim |  |
| `prismadata__pessoa_juridica__cnpj_alfanumerico` | boolean | sim |  |
| `prismadata__pessoa_juridica__matriz_filial` | string | sim |  |
| `prismadata__pessoa_juridica__razao_social` | string | sim |  |
| `prismadata__pessoa_juridica__nome_fantasia` | string \| null | não |  |
| `prismadata__pessoa_juridica__situacao_cadastral` | string | sim |  |
| `prismadata__pessoa_juridica__data_situacao_cadastral` | string \| null | não |  |
| `prismadata__pessoa_juridica__motivo_situacao_cadastral` | string \| null | não |  |
| `prismadata__pessoa_juridica__data_abertura` | string \| null | não |  |
| `prismadata__pessoa_juridica__natureza_juridica_codigo` | string | sim |  |
| `prismadata__pessoa_juridica__natureza_juridica_descricao` | string | sim |  |
| `prismadata__pessoa_juridica__porte` | string | sim |  |
| `prismadata__pessoa_juridica__capital_social` | string \| null | não |  |
| `prismadata__pessoa_juridica__opcao_simples` | boolean \| null | não |  |
| `prismadata__pessoa_juridica__data_opcao_simples` | string \| null | não |  |
| `prismadata__pessoa_juridica__opcao_mei` | boolean \| null | não |  |
| `prismadata__pessoa_juridica__data_opcao_mei` | string \| null | não |  |
| `prismadata__pessoa_juridica__cnae_principal_codigo` | string | sim |  |
| `prismadata__pessoa_juridica__cnae_principal_descricao` | string \| null | não |  |
| `prismadata__pessoa_juridica__cnaes_secundarios` | array[string] | sim | Lista completa de codigos CNAE secundarios. |
| `prismadata__pessoa_juridica__logradouro` | string \| null | não |  |
| `prismadata__pessoa_juridica__numero` | string \| null | não |  |
| `prismadata__pessoa_juridica__complemento` | string \| null | não |  |
| `prismadata__pessoa_juridica__bairro` | string \| null | não |  |
| `prismadata__pessoa_juridica__municipio_codigo` | string \| null | não |  |
| `prismadata__pessoa_juridica__municipio_nome` | string \| null | não |  |
| `prismadata__pessoa_juridica__uf` | string \| null | não |  |
| `prismadata__pessoa_juridica__cep` | string \| null | não |  |
| `prismadata__pessoa_juridica__id_logradouro` | integer \| null | não |  |
| `prismadata__pessoa_juridica__id_loc` | integer \| null | não |  |
| `prismadata__pessoa_juridica__latitude` | string \| null | não |  |
| `prismadata__pessoa_juridica__longitude` | string \| null | não |  |
| `prismadata__pessoa_juridica__endereco_normalizado` | string \| null | não |  |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_score` | integer \| null | não |  |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao` | string \| null | não |  |
| `prismadata__pessoa_juridica__endereco_existe` | boolean \| null | não |  |
| `prismadata__pessoa_juridica__divergencia_endereco_rfb_geocoder` | boolean \| null | não |  |
| `prismadata__pessoa_juridica__socios` | array[object] | sim | Lista completa de socios com todos os campos originais. |
| `prismadata__pessoa_juridica__data_publicacao_rfb` | string \| null | não |  |
| `prismadata__pessoa_juridica__data_processamento` | string \| null | não |  |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `GET /cnpj/metadata`

Metadata flat (cobertura_geo achatada por classe).

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/metadata" \
  -H "X-Apikey: SEU_TOKEN"
```

**Response 200** (`application/json`):

> Metadados da versao atual dos dados (cobertura por classe de qualidade geografica em campos escalares).

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__versao_dados` | string \| null | não | Versao do dataset atual (`YYYYMMDD`). |
| `prismadata__pessoa_juridica__data_publicacao_rfb` | string \| null | não | Data da publicacao dos dados pela Receita Federal. |
| `prismadata__pessoa_juridica__data_processamento` | string \| null | não | Data e hora do enriquecimento dos dados. |
| `prismadata__pessoa_juridica__total_cnpjs_carregados` | integer | sim | Total de CNPJs disponiveis na versao atual. |
| `prismadata__pessoa_juridica__cobertura_geo_muito_alta` | integer | sim | CNPJs com qualidade de geocodificacao muito alta. |
| `prismadata__pessoa_juridica__cobertura_geo_alta` | integer | sim | CNPJs com qualidade de geocodificacao alta. |
| `prismadata__pessoa_juridica__cobertura_geo_media` | integer | sim | CNPJs com qualidade de geocodificacao media. |
| `prismadata__pessoa_juridica__cobertura_geo_baixa` | integer | sim | CNPJs com qualidade de geocodificacao baixa. |
| `prismadata__pessoa_juridica__cobertura_geo_muito_baixa` | integer | sim | CNPJs com qualidade de geocodificacao muito baixa. |
| `prismadata__pessoa_juridica__cobertura_geo_centroide_municipio` | integer | sim | CNPJs projetados no centroide do municipio (endereco nao resolvido pra logradouro/numero — introduzido em v20260701). |
| `prismadata__pessoa_juridica__cobertura_geo_nao_geocodificado` | integer | sim | CNPJs sem geocodificacao (chave `(logradouro, numero, bairro, cep, municipio, uf)` nao presente no cache do geocoder externo — cache miss, nao erro semantico). |
| `prismadata__pessoa_juridica__cobertura_geo_sem_geo` | integer | sim | CNPJs sem classificacao de qualidade atribuida. |
| `prismadata__pessoa_juridica__historico_competencia_min` | string \| null | não | Competencia mais antiga carregada na serie historica (`YYYY-MM-DD`). |
| `prismadata__pessoa_juridica__historico_competencia_max` | string \| null | não | Competencia mais recente carregada na serie historica (`YYYY-MM-DD`). |
| `prismadata__pessoa_juridica__historico_total_competencias` | integer \| null | não | Total de competencias mensais distintas presentes na serie. |
| `prismadata__pessoa_juridica__historico_competencias_ausentes` | array[string] | não | Competencias faltantes entre min e max (ex.: `["2025-01-01"]`). |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `POST /cnpj/batch`

Lote flat. OUTPUT eh dict {cnpj: CnpjF1Flat ou null}.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/cnpj/batch" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "cnpjs": [
           "11222333000144"
         ]
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `cnpjs` | array[string] | sim |  |

**Response 200** (`application/json`):

> Dicionario indexado pelo CNPJ. Valor `null` para CNPJs invalidos ou nao encontrados. Limite: 1024 CNPJs por chamada.

Dicionário `{string: object \| null}`.
Resultado da consulta padrao em lote: dicionario indexado pelo CNPJ.

**Outros códigos**: 401, 403, 404, 422, 429

---

### `GET /cnpj/{cnpj}/historico/socios`

Trajetoria QSA: todas as versoes de cada socio do CNPJ. Cada linha = 1 socio em 1 janela `[valido_de, valido_ate)`. `valido_ate = 9999-12-31` indica versao vigente. Ordem: cronologica ASC, entao alfabetica por nome. `cnpj_cpf_socio` vem formatado (`***.XXX.XXX-**` para PF, `XX.XXX.XXX/XXXX-XX` para PJ, null para ESTRANGEIRO).

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/11222333000144/historico/socios" \
  -H "X-Apikey: SEU_TOKEN"
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `cnpj` | path | string | sim | CNPJ com ou sem mascara |

**Response 200** (`application/json`):

> Trajetoria do QSA (quadro societario). Uma linha por (socio, intervalo temporal). Socios PF vem com CPF mascarado.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__cnpj` | string | sim |  |
| `prismadata__pessoa_juridica__cnpj_basico` | string | sim |  |
| `prismadata__pessoa_juridica__versoes` | array[object] | sim | Uma linha por (socio, intervalo temporal). Ordenacao ASC por `valido_de`. |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `GET /cnpj/{cnpj}/historico`

Trajetoria cadastral: todas as versoes escalares do CNPJ. Cada linha = 1 versao com `[valido_de, valido_ate)`. `valido_ate = 9999-12-31` indica versao vigente. Ordem cronologica ASC. QSA (socios) NAO vem nesta resposta — consulte `/cnpj/{cnpj}/historico/socios`.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/11222333000144/historico" \
  -H "X-Apikey: SEU_TOKEN"
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `cnpj` | path | string | sim | CNPJ com ou sem mascara |

**Response 200** (`application/json`):

> Trajetoria cadastral do CNPJ (versoes ao longo do tempo). Ordem cronologica ASC. `valido_ate = 9999-12-31` marca a versao vigente.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__cnpj` | string | sim |  |
| `prismadata__pessoa_juridica__cnpj_basico` | string | sim |  |
| `prismadata__pessoa_juridica__versoes` | array[object] | sim | Versoes em ordem cronologica ASC. `valido_ate = 9999-12-31` marca a versao vigente. |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `GET /cnpj/{cnpj}`

Lookup flat — sem socios nem cnaes_secundarios; agregacoes no lugar. Com `?data=YYYY-MM-DD`: point-in-time — retorna a versao do CNPJ vigente nessa data (periodo `[valido_de, valido_ate)`). Se `data` esta fora da janela historica disponivel, retorna 404 com detail especifico (nao confunde com "CNPJ nao encontrado").

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/11222333000144" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: data=string
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `cnpj` | path | string | sim | CNPJ com ou sem mascara (alfanumerico aceito) |
| `data` | query | string(date) \| null | não | Se informado, retorna o estado do CNPJ nessa data (YYYY-MM-DD). Sem ele, retorna o estado atual. |

**Response 200** (`application/json`):

> Dados do CNPJ na consulta padrao (com resumo de socios e CNAEs).

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__cnpj` | string | sim | CNPJ de 14 caracteres, sem mascara. |
| `prismadata__pessoa_juridica__cnpj_basico` | string | sim | Primeiros 8 caracteres do CNPJ (identifica a matriz e todas as filiais). |
| `prismadata__pessoa_juridica__cnpj_ordem` | string | sim | 4 caracteres que identificam a filial (0001 e a matriz). |
| `prismadata__pessoa_juridica__cnpj_dv` | string | sim | 2 digitos verificadores. |
| `prismadata__pessoa_juridica__cnpj_alfanumerico` | boolean | sim | `true` quando o CNPJ contem letras (formato novo da Receita Federal). |
| `prismadata__pessoa_juridica__matriz_filial` | string | sim | `MATRIZ` ou `FILIAL`. |
| `prismadata__pessoa_juridica__razao_social` | string | sim | Razao social registrada na Receita Federal. |
| `prismadata__pessoa_juridica__nome_fantasia` | string \| null | não | Nome fantasia declarado, se houver. |
| `prismadata__pessoa_juridica__situacao_cadastral` | string | sim | Situacao atual: `NULA`, `ATIVA`, `SUSPENSA`, `INAPTA` ou `BAIXADA`. |
| `prismadata__pessoa_juridica__data_situacao_cadastral` | string \| null | não | Data (`YYYY-MM-DD`) da ultima mudanca de situacao. |
| `prismadata__pessoa_juridica__motivo_situacao_cadastral` | string \| null | não | Motivo textual da situacao atual. |
| `prismadata__pessoa_juridica__data_abertura` | string \| null | não | Data (`YYYY-MM-DD`) de constituicao da empresa. |
| `prismadata__pessoa_juridica__natureza_juridica_codigo` | string | sim | Codigo IBGE da natureza juridica. |
| `prismadata__pessoa_juridica__natureza_juridica_descricao` | string | sim | Descricao textual da natureza juridica. |
| `prismadata__pessoa_juridica__porte` | string | sim | Porte: `NAO_INFORMADO`, `MICRO`, `PEQUENA` ou `DEMAIS`. |
| `prismadata__pessoa_juridica__capital_social` | string \| null | não | Capital social declarado (valor decimal em texto). |
| `prismadata__pessoa_juridica__opcao_simples` | boolean \| null | não | Se e optante do Simples Nacional. |
| `prismadata__pessoa_juridica__data_opcao_simples` | string \| null | não | Data de adesao ao Simples. |
| `prismadata__pessoa_juridica__opcao_mei` | boolean \| null | não | Se e optante do MEI. |
| `prismadata__pessoa_juridica__data_opcao_mei` | string \| null | não | Data de adesao ao MEI. |
| `prismadata__pessoa_juridica__cnae_principal_codigo` | string | sim | Codigo CNAE da atividade principal (7 digitos). |
| `prismadata__pessoa_juridica__cnae_principal_descricao` | string \| null | não | Descricao da atividade principal. |
| `prismadata__pessoa_juridica__cnae_secundario_1` | string \| null | não | Primeiro CNAE secundario (na ordem em que aparece no cadastro). |
| `prismadata__pessoa_juridica__cnae_secundario_2` | string \| null | não | Segundo CNAE secundario. |
| `prismadata__pessoa_juridica__cnae_secundario_3` | string \| null | não | Terceiro CNAE secundario. |
| `prismadata__pessoa_juridica__total_cnaes_secundarios` | integer | sim | Numero total de CNAEs secundarios registrados. Para ver a lista completa use a consulta detalhada. |
| `prismadata__pessoa_juridica__logradouro` | string \| null | não | Nome do logradouro. |
| `prismadata__pessoa_juridica__numero` | string \| null | não | Numero do endereco. |
| `prismadata__pessoa_juridica__complemento` | string \| null | não | Complemento do endereco. |
| `prismadata__pessoa_juridica__bairro` | string \| null | não | Bairro. |
| `prismadata__pessoa_juridica__municipio_codigo` | string \| null | não | Codigo IBGE do municipio. |
| `prismadata__pessoa_juridica__municipio_nome` | string \| null | não | Nome do municipio. |
| `prismadata__pessoa_juridica__uf` | string \| null | não | UF (2 caracteres). |
| `prismadata__pessoa_juridica__cep` | string \| null | não | CEP sem mascara. |
| `prismadata__pessoa_juridica__id_logradouro` | integer \| null | não | Identificador estavel do logradouro, util para correlacionar com outros produtos de geolocalizacao da PrismaData. |
| `prismadata__pessoa_juridica__id_loc` | integer \| null | não | Identificador estavel da localizacao, util para correlacionar com outros produtos de geolocalizacao da PrismaData. |
| `prismadata__pessoa_juridica__latitude` | string \| null | não | Latitude do endereco. `null` quando nao foi possivel geocodificar. |
| `prismadata__pessoa_juridica__longitude` | string \| null | não | Longitude do endereco. `null` quando nao foi possivel geocodificar. |
| `prismadata__pessoa_juridica__endereco_normalizado` | string \| null | não | Endereco reescrito no padrao usado pela geocodificacao. |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_score` | integer \| null | não | Score de qualidade da geocodificacao (0-100). |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao` | string \| null | não | Classificacao da qualidade da geocodificacao: `MUITO_ALTA`, `ALTA`, `MEDIA`, `BAIXA`, `MUITO_BAIXA`, `CENTROIDE_MUNICIPIO` ou `NAO_GEOCODIFICADO`. |
| `prismadata__pessoa_juridica__endereco_existe` | boolean \| null | não | Se o endereco foi encontrado na base de referencia da geocodificacao. |
| `prismadata__pessoa_juridica__divergencia_endereco_rfb_geocoder` | boolean \| null | não | Sinaliza divergencia entre o endereco cadastrado na Receita Federal e o endereco geocodificado. |
| `prismadata__pessoa_juridica__total_socios` | integer | sim | Numero total de socios cadastrados. |
| `prismadata__pessoa_juridica__total_socios_pf` | integer | sim | Numero de socios pessoa fisica. |
| `prismadata__pessoa_juridica__total_socios_pj` | integer | sim | Numero de socios pessoa juridica. |
| `prismadata__pessoa_juridica__total_socios_estrangeiro` | integer | sim | Numero de socios estrangeiros. |
| `prismadata__pessoa_juridica__data_publicacao_rfb` | string \| null | não | Data da publicacao dos dados pela Receita Federal. |
| `prismadata__pessoa_juridica__data_processamento` | string \| null | não | Data e hora em que os dados foram enriquecidos. |

**Outros códigos**: 401, 403, 404, 422, 429

---

### `POST /cnpj/endereco/cnpjs`

**Reverse lookup por endereco.** Dado um endereco (logradouro + numero + municipio + UF, opcionalmente bairro, CEP e complemento), devolve a lista de CNPJs localizados no mesmo endereco. A granularidade e autodescoberta pelo campo `complemento`: - Com `complemento` informado: filtra pela mesma sala/andar (`granularidade=sala_andar`). - Sem `complemento`: devolve o predio inteiro (`granularidade=predio`). **Historico retrospectivo:** o campo `data_ref` permite consultar o estado do endereco em qualquer data desde maio/2023 (`"2023-06-01"`). Sem `data_ref`, devolve apenas quem esta no endereco atualmente. **Uso ideal:** due diligence de ponto comercial, enriquecimento de leads por endereco, analise de densidade de empresas, compliance KYC/KYB. **Enderecos com numero nao identificado** (`S/N`, `1000-A`) sao filtrados por default para evitar devolver centenas de CNPJs de uma rua inteira (`super_id_loc` interno). **Enderecos no exterior** (`uf="EX"`) sao filtrados por construcao. **Cota:** uma consulta por chamada, independente do numero de CNPJs retornados.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/cnpj/endereco/cnpjs" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "logradouro": "RUA ALAGOAS",
         "numero": "601",
         "bairro": "SAVASSI",
         "municipio": "BELO HORIZONTE",
         "uf": "MG",
         "cep": "30130165",
         "complemento": "LOJA 26"
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `logradouro` | string | sim | Nome do logradouro, idealmente **com prefixo tipo** (`"RUA ALAGOAS"`, `"AVENIDA PAULISTA"`). A consulta tenta as duas variantes (com e sem split do tipo) e une os resultados. |
| `numero` | string | não | Numero do imovel. Valores inconversiveis a inteiro (`S/N`, `1000-A`) sao tratados como numero ausente — a consulta devolve `cnpjs=[]` por filtro de endereco patologico. |
| `bairro` | string | não |  |
| `municipio` | string | sim | Nome do municipio (acentos sao normalizados internamente). |
| `uf` | string | sim | Sigla da UF. `uf="EX"` (exterior) devolve vazio. |
| `cep` | string | não |  |
| `complemento` | string | não | Quando informado, filtra pela mesma sala/andar via hash normalizado do complemento. |
| `data_ref` | string(date) | não | Opcional. `YYYY-MM-DD`. Default: vigente (`9999-12-31`). Quando informado, retrocede ao estado do endereco naquela data. |
| `limit` | integer | não |  |
| `offset` | integer | não |  |

**Response 200** (`application/json`):

> Lista de CNPJs encontrados no endereco. Vazia quando o endereco nao e localizado ou quando todos os CNPJs foram filtrados.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__id_loc` | integer | sim | Hash estavel do endereco (dialeto cadastral da RFB). CNPJs no mesmo `id_loc` estao fisicamente no mesmo ponto (predio). |
| `prismadata__pessoa_juridica__id_logradouro` | integer | sim | Hash estavel do logradouro (rua inteira). |
| `prismadata__pessoa_juridica__id_locs_tentados` | array[integer] | não | Lista de `id_loc` candidatos consultados pela API. A RFB grava o mesmo endereco em formatos variados (`'RUA ALAGOAS'` vs `'ALAGOAS'` com `tipo='RUA'` separado); a consulta tenta as duas variantes e une os resultados. |
| `prismadata__pessoa_juridica__id_complemento` | integer \| null | não | Hash do complemento normalizado (sala/andar) quando o cliente informou o campo `complemento`. `null` quando a consulta foi so por predio. |
| `prismadata__pessoa_juridica__granularidade` | string | sim | `predio` (sem filtro por complemento) ou `sala_andar` (com complemento informado). |
| `prismadata__pessoa_juridica__total` | string | sim | Total exato de CNPJs encontrados ate 1000 (`"3"`, `"47"`, `"999"`). Acima disso retorna `"1000+"` como string. Pequena faixa `null` tambem possivel quando a consulta nao encontra nada. |
| `prismadata__pessoa_juridica__latitude` | string \| null | não | Latitude do endereco consultado. Todos os CNPJs retornados compartilham a mesma coordenada por construcao do `id_loc`. `null` quando a consulta nao encontra CNPJs no endereco. |
| `prismadata__pessoa_juridica__longitude` | string \| null | não | Longitude do endereco consultado. |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao` | string \| null | não | Qualidade da geocodificacao: `MUITO_ALTA`, `ALTA`, `MEDIA`, `BAIXA`, `MUITO_BAIXA`, `CENTROIDE_MUNICIPIO` ou `NAO_GEOCODIFICADO`. Util pra decidir se a coordenada e confiavel. |
| `prismadata__pessoa_juridica__endereco_normalizado` | string \| null | não | Endereco reescrito no padrao da base de referencia geocodificada (feedback 'foi isso que achamos'). Util pra validar se o endereco passado foi interpretado corretamente. |
| `prismadata__pessoa_juridica__motivo_vazio` | string \| null | não | Preenchido somente quando `cnpjs` esta vazia. Explica por que a consulta nao devolveu nenhum CNPJ: - `super_id_loc`: o numero do endereco nao foi identificado (`S/N`, `1000-A`); a consulta refletiria a rua inteira e por isso e omitida. - `data_ref_sem_versao`: a `data_ref` consultada e anterior a maio/2023 (fora da janela historica disponivel). - `sem_cnpjs_cadastrados`: endereco e periodo validos; simplesmente nenhum CNPJ esta registrado nesse endereco. |
| `prismadata__pessoa_juridica__cnpjs` | array[object] | não | CNPJs encontrados no endereco (ordenados por `valido_de` DESC, depois `cnpj` ASC). Limite por `limit` da request. Vazio quando o endereco nao e encontrado na base. |

**Outros códigos**: 400, 401, 403, 429, 502

---

### `GET /cnpj/{cnpj}/enriched`

Consulta um CNPJ e, na mesma chamada, agrega dados de servicos de localizacao da PrismaData (favelas, presidios, renda, etc.). Habilite os enriquecimentos desejados por parametro de query. Se o CNPJ nao tem coordenadas geocodificadas (por exemplo, quando o endereco cadastrado na Receita Federal nao pode ser geocodificado), os enriquecimentos solicitados nao sao executados — o resultado contem apenas os campos de `pessoa_juridica`. **Cota:** cada enriquecimento habilitado conta como uma consulta adicional. Enriquecimentos pulados por falta de coordenadas nao contam.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/cnpj/11222333000144/enriched" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: slum=False, prison=False, border=False, personal_income_static=False, personal_income_pdf=False, commercial_cluster=False, infosc=False, tipologia=False, sandbox=False
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `cnpj` | path | string | sim | CNPJ de 14 caracteres, com ou sem mascara. Aceita CNPJ alfanumerico. |
| `slum` | query | boolean | não | Proximidade e classificacao de favelas. |
| `prison` | query | boolean | não | Proximidade e detalhes do presidio mais proximo. |
| `border` | query | boolean | não | Situacao em relacao a fronteiras internacionais. |
| `personal_income_static` | query | boolean | não | Renda media no ponto. |
| `personal_income_pdf` | query | boolean | não | Distribuicao de renda no ponto. |
| `commercial_cluster` | query | boolean | não | Aglomeracoes comerciais proximas. |
| `infosc` | query | boolean | não | Informacoes do setor censitario. |
| `tipologia` | query | boolean | não | Tipologia CNEFE. |
| `sandbox` | query | boolean | não | Se `true`, retorna dados sinteticos para testes. Consultas em modo sandbox nao contam para efeito de cota. |

**Response 200** (`application/json`):

> Objeto JSON com os campos de `pessoa_juridica` (sempre presentes) e os campos de cada enriquecimento habilitado (quando o CNPJ tem coordenadas).

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__pessoa_juridica__cnpj` | string | sim | CNPJ de 14 caracteres, sem mascara. |
| `prismadata__pessoa_juridica__cnpj_basico` | string | sim | Primeiros 8 caracteres do CNPJ (identifica a matriz e todas as filiais). |
| `prismadata__pessoa_juridica__cnpj_ordem` | string | sim | 4 caracteres que identificam a filial (0001 e a matriz). |
| `prismadata__pessoa_juridica__cnpj_dv` | string | sim | 2 digitos verificadores. |
| `prismadata__pessoa_juridica__cnpj_alfanumerico` | boolean | sim | `true` quando o CNPJ contem letras (formato novo da Receita Federal). |
| `prismadata__pessoa_juridica__matriz_filial` | string | sim | `MATRIZ` ou `FILIAL`. |
| `prismadata__pessoa_juridica__razao_social` | string | sim | Razao social registrada na Receita Federal. |
| `prismadata__pessoa_juridica__nome_fantasia` | string \| null | não | Nome fantasia declarado, se houver. |
| `prismadata__pessoa_juridica__situacao_cadastral` | string | sim | Situacao atual: `NULA`, `ATIVA`, `SUSPENSA`, `INAPTA` ou `BAIXADA`. |
| `prismadata__pessoa_juridica__data_situacao_cadastral` | string \| null | não | Data (`YYYY-MM-DD`) da ultima mudanca de situacao. |
| `prismadata__pessoa_juridica__motivo_situacao_cadastral` | string \| null | não | Motivo textual da situacao atual. |
| `prismadata__pessoa_juridica__data_abertura` | string \| null | não | Data (`YYYY-MM-DD`) de constituicao da empresa. |
| `prismadata__pessoa_juridica__natureza_juridica_codigo` | string | sim | Codigo IBGE da natureza juridica. |
| `prismadata__pessoa_juridica__natureza_juridica_descricao` | string | sim | Descricao textual da natureza juridica. |
| `prismadata__pessoa_juridica__porte` | string | sim | Porte: `NAO_INFORMADO`, `MICRO`, `PEQUENA` ou `DEMAIS`. |
| `prismadata__pessoa_juridica__capital_social` | string \| null | não | Capital social declarado (valor decimal em texto). |
| `prismadata__pessoa_juridica__opcao_simples` | boolean \| null | não | Se e optante do Simples Nacional. |
| `prismadata__pessoa_juridica__data_opcao_simples` | string \| null | não | Data de adesao ao Simples. |
| `prismadata__pessoa_juridica__opcao_mei` | boolean \| null | não | Se e optante do MEI. |
| `prismadata__pessoa_juridica__data_opcao_mei` | string \| null | não | Data de adesao ao MEI. |
| `prismadata__pessoa_juridica__cnae_principal_codigo` | string | sim | Codigo CNAE da atividade principal (7 digitos). |
| `prismadata__pessoa_juridica__cnae_principal_descricao` | string \| null | não | Descricao da atividade principal. |
| `prismadata__pessoa_juridica__cnae_secundario_1` | string \| null | não | Primeiro CNAE secundario (na ordem em que aparece no cadastro). |
| `prismadata__pessoa_juridica__cnae_secundario_2` | string \| null | não | Segundo CNAE secundario. |
| `prismadata__pessoa_juridica__cnae_secundario_3` | string \| null | não | Terceiro CNAE secundario. |
| `prismadata__pessoa_juridica__total_cnaes_secundarios` | integer | sim | Numero total de CNAEs secundarios registrados. Para ver a lista completa use a consulta detalhada. |
| `prismadata__pessoa_juridica__logradouro` | string \| null | não | Nome do logradouro. |
| `prismadata__pessoa_juridica__numero` | string \| null | não | Numero do endereco. |
| `prismadata__pessoa_juridica__complemento` | string \| null | não | Complemento do endereco. |
| `prismadata__pessoa_juridica__bairro` | string \| null | não | Bairro. |
| `prismadata__pessoa_juridica__municipio_codigo` | string \| null | não | Codigo IBGE do municipio. |
| `prismadata__pessoa_juridica__municipio_nome` | string \| null | não | Nome do municipio. |
| `prismadata__pessoa_juridica__uf` | string \| null | não | UF (2 caracteres). |
| `prismadata__pessoa_juridica__cep` | string \| null | não | CEP sem mascara. |
| `prismadata__pessoa_juridica__id_logradouro` | integer \| null | não | Identificador estavel do logradouro, util para correlacionar com outros produtos de geolocalizacao da PrismaData. |
| `prismadata__pessoa_juridica__id_loc` | integer \| null | não | Identificador estavel da localizacao, util para correlacionar com outros produtos de geolocalizacao da PrismaData. |
| `prismadata__pessoa_juridica__latitude` | string \| null | não | Latitude do endereco. `null` quando nao foi possivel geocodificar. |
| `prismadata__pessoa_juridica__longitude` | string \| null | não | Longitude do endereco. `null` quando nao foi possivel geocodificar. |
| `prismadata__pessoa_juridica__endereco_normalizado` | string \| null | não | Endereco reescrito no padrao usado pela geocodificacao. |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_score` | integer \| null | não | Score de qualidade da geocodificacao (0-100). |
| `prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao` | string \| null | não | Classificacao da qualidade da geocodificacao: `MUITO_ALTA`, `ALTA`, `MEDIA`, `BAIXA`, `MUITO_BAIXA`, `CENTROIDE_MUNICIPIO` ou `NAO_GEOCODIFICADO`. |
| `prismadata__pessoa_juridica__endereco_existe` | boolean \| null | não | Se o endereco foi encontrado na base de referencia da geocodificacao. |
| `prismadata__pessoa_juridica__divergencia_endereco_rfb_geocoder` | boolean \| null | não | Sinaliza divergencia entre o endereco cadastrado na Receita Federal e o endereco geocodificado. |
| `prismadata__pessoa_juridica__total_socios` | integer | sim | Numero total de socios cadastrados. |
| `prismadata__pessoa_juridica__total_socios_pf` | integer | sim | Numero de socios pessoa fisica. |
| `prismadata__pessoa_juridica__total_socios_pj` | integer | sim | Numero de socios pessoa juridica. |
| `prismadata__pessoa_juridica__total_socios_estrangeiro` | integer | sim | Numero de socios estrangeiros. |
| `prismadata__pessoa_juridica__data_publicacao_rfb` | string \| null | não | Data da publicacao dos dados pela Receita Federal. |
| `prismadata__pessoa_juridica__data_processamento` | string \| null | não | Data e hora em que os dados foram enriquecidos. |

**Outros códigos**: 400, 401, 403, 404, 429, 502

---

### `POST /cnpj/batch/enriched`

Consulta enriquecida em lote. Envie a lista de CNPJs e as flags de enriquecimento no body; receba um dicionario indexado pelo CNPJ. Limite: 256 CNPJs por chamada. CNPJs invalidos ou nao encontrados vem como `null` no dicionario. **Cota:** cada CNPJ conta como uma consulta base, mais uma consulta adicional por enriquecimento habilitado. Enriquecimentos pulados por falta de coordenadas nao contam.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/cnpj/batch/enriched" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "cnpjs": [
           "11222333000144"
         ],
         "flags": {
           "slum": false,
           "prison": false,
           "border": false,
           "personal_income_static": false,
           "personal_income_pdf": false,
           "commercial_cluster": false,
           "infosc": false,
           "tipologia": false
         }
       }'
```

**Request body** (`application/json`):

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `cnpjs` | array[string] | sim | Lista de CNPJs a consultar. |
| `flags` | object | não | Enriquecimentos a habilitar para todos os CNPJs do lote. |

**Response 200** (`application/json`):

> Dicionario indexado pelo CNPJ. Valor `null` para CNPJs invalidos ou nao encontrados.

Dicionário `{string: object \| null}`.
Resultado da consulta enriquecida em lote: dicionario indexado pelo CNPJ.

**Outros códigos**: 400, 401, 403, 429, 502

---

## Recursos relacionados

- Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/CNPJ
- OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/cnpj.json
- OpenAPI completo: https://prismadata.io/openapi.yaml
- Índice geral: https://prismadata.io/llms.txt