# Consulta de CNPJ

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

O `{cnpj}` pode vir com ou sem máscara. A API aceita **CNPJ alfanumérico** (IN RFB nº 2.229/2024), em que as 12 primeiras posições podem ter letras.

> **Atenção ao integrar:** não aplique `replace(/\D/g, '')` ou equivalente no CNPJ antes de enviar. Num CNPJ alfanumérico isso remove as letras em silêncio e produz outro número, sem erro nenhum. Remova só a pontuação (`.`, `/`, `-`).

## Exemplo

```bash
curl https://api.toreva.com.br/v1/cnpj/19729868000155 \
  -H "Authorization: Bearer $TOREVA_API_KEY"
```

Resposta `200`:

```json
{
  "cnpj": "19729868000155",
  "cnpjFormatado": "19.729.868/0001-55",
  "raiz": "19729868",
  "razaoSocial": "Empresa Exemplo Ltda",
  "nomeFantasia": "Exemplo",
  "matrizFilial": "matriz",
  "situacaoCadastral": {
    "codigo": "02",
    "descricao": "Ativa",
    "data": "2019-04-01",
    "motivo": null
  },
  "situacaoEspecial": null,
  "dataAbertura": "2005-11-03",
  "idadeAnos": 20,
  "naturezaJuridica": { "codigo": "2062", "descricao": "Sociedade Empresária Limitada" },
  "porte": { "codigo": "05", "descricao": "Demais" },
  "capitalSocial": 100000,
  "endereco": {
    "logradouro": "Rua Um",
    "numero": "100",
    "complemento": null,
    "bairro": "Centro",
    "municipio": "São Paulo",
    "codigoMunicipio": "7107",
    "uf": "SP",
    "cep": "01310100"
  },
  "contato": {
    "telefones": [{ "ddd": "11", "numero": "40028922", "formatado": "(11) 4002-8922" }],
    "email": "contato@exemplo.com.br"
  },
  "cnaePrincipal": { "codigo": "6201500", "descricao": "Desenvolvimento de programas de computador sob encomenda" },
  "cnaesSecundarios": [{ "codigo": "6202300", "descricao": "..." }],
  "socios": [
    {
      "nome": "Fulano de Tal",
      "tipo": "Pessoa física",
      "qualificacao": "Sócio-Administrador",
      "dataEntrada": "2010-04-15",
      "faixaEtaria": "41 a 50 anos"
    }
  ],
  "estabelecimentos": [
    {
      "cnpj": "19729868000236",
      "matrizFilial": "filial",
      "nomeFantasia": null,
      "situacaoCadastral": { "codigo": "02", "descricao": "Ativa" },
      "municipio": "Campinas",
      "uf": "SP"
    }
  ],
  "fonte": {
    "origem": "Receita Federal do Brasil",
    "referencia": "2026-07",
    "atualizadoEm": "2026-08-01",
    "possuiCorrecoes": false
  }
}
```

## Convenções do contrato

Valem para todos os campos, em todos os endpoints:

| Regra | O que significa |
|---|---|
| Datas em ISO-8601 | Sempre `AAAA-MM-DD`. Nunca `dd/mm/aaaa` |
| Dinheiro em número | `capitalSocial: 100000`, não `"R$ 100.000,00"` |
| Códigos em texto | `"02"`, `"6201500"`. O zero à esquerda conta |
| Ausência é `null` | Nunca string vazia |
| Sem máscara nos identificadores | `cnpj` e `cep` vêm só com os caracteres do valor |

## Campos que merecem atenção

**`situacaoCadastral.codigo`:** `01` Nula, `02` Ativa, `03` Suspensa, `04` Inapta, `08` Baixada. Compare o **código**, não a descrição. O texto pode mudar, o código não.

**`estabelecimentos`:** a matriz e as filiais com a mesma raiz de 8 posições, incluindo o próprio CNPJ consultado.

**`fonte.referencia`:** de qual carga mensal da Receita o dado veio. Use para saber a idade da informação.

**`fonte.possuiCorrecoes`:** `true` indica que algum campo foi corrigido sobre o que a Receita publica, em geral a pedido do próprio titular. O dado entregue já é o corrigido.

## Erros e cobrança

CNPJ inválido recebe `400 INVALID_CNPJ` e CNPJ fora da base recebe `404 NOT_FOUND`. Nenhum dos dois é cobrado. Os demais códigos estão em [Erros e limites](https://toreva.com.br/developers/erros-e-limites), e as regras de cobrança em [Preços e cobrança](https://toreva.com.br/developers/precos-e-cobranca).