# Obter o cadastro de uma empresa

`GET /v1/empresas/{cnpj}` · requer o header `X-Api-Key`

Cadastro completo de um estabelecimento e o quadro de sócios da empresa (raiz do CNPJ), na competência RFB publicada. Inclui estabelecimentos em qualquer situação cadastral. Os campos preservam os códigos e formatos da Receita Federal: datas em AAAAMMDD e capital social com vírgula decimal.

## Requisição

```bash
curl https://api.fonteza.com.br/v1/empresas/12345678000190 \
  -H "X-Api-Key: $FONTEZA_KEY"
```

```python
import os
import requests

resposta = requests.get(
    "https://api.fonteza.com.br/v1/empresas/12345678000190",
    headers={"X-Api-Key": os.environ["FONTEZA_KEY"]},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()
```

## Parâmetros

| Parâmetro | Tipo | Onde | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `cnpj` | string | caminho | sim | CNPJ completo com 14 caracteres. Pontos e hífen são removidos e letras viram maiúsculas (CNPJ alfanumérico); a barra não é aceita no caminho e resulta em 404. Os dígitos verificadores não são conferidos. Ao menos 14 caracteres. |

## Resposta 200

Cadastro e sócios.

- `data` (objeto)
  - `cnpj` (string): CNPJ completo com 14 caracteres.
  - `cnpj_basico` (string): Raiz do CNPJ (8 primeiros caracteres), comum a matriz e filiais.
  - `razao_social` (string | null)
  - `nome_fantasia` (string | null)
  - `matriz_filial` (string | null): 1 matriz, 2 filial.
  - `situacao_cadastral` (string | null): Código RFB: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada.
  - `data_inicio_atividade` (string | null): Data no formato RFB AAAAMMDD.
  - `cnae_principal` (string | null): Código CNAE de sete dígitos.
  - `cnae_principal_desc` (string | null)
  - `municipio` (string | null)
  - `uf` (string | null)
  - `cep` (string | null): Oito dígitos, sem hífen.
  - `telefone` (string | null): DDD e número do primeiro telefone cadastral, sem formatação; vazio quando ausente.
  - `email` (string | null): E-mail cadastral declarado à RFB.
  - `natureza_juridica` (string | null): Descrição da natureza jurídica.
  - `porte` (string | null): 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais.
  - `capital_social` (string | null): Valor em reais no formato RFB, com vírgula decimal (ex. 150000,00).
  - `opcao_simples` (string | null): S ou N.
  - `opcao_mei` (string | null): S ou N.
  - `qtde_socios` (integer | null)
  - `socios` (array de objeto)
    - `nome` (string | null)
    - `cpf_mascarado` (string | null): Documento do sócio como publicado pela RFB: CPF mascarado para pessoa física, CNPJ para pessoa jurídica.
    - `qualificacao` (string | null): Código RFB da qualificação do sócio (ex. 49 sócio-administrador).
    - `desde` (string | null): Data de entrada na sociedade, formato AAAAMMDD.
- `meta` (objeto)
  - `fonte` (array de string)
  - `competencia` (string | null, opcional)
  - `snapshot_id` (string | null, opcional)

Exemplo (Cadastro com sócios):

```json
{
  "data": {
    "cnpj": "12345678000190",
    "cnpj_basico": "12345678",
    "razao_social": "TRANSPORTADORA EXEMPLO LTDA",
    "nome_fantasia": "EXEMPLO CARGAS",
    "matriz_filial": "1",
    "situacao_cadastral": "02",
    "data_inicio_atividade": "20150312",
    "cnae_principal": "4930202",
    "cnae_principal_desc": "Transporte rodoviário de carga, exceto produtos perigosos e mudanças, intermunicipal, interestadual e internacional",
    "municipio": "CAMPINAS",
    "uf": "SP",
    "cep": "13050000",
    "telefone": "1932345678",
    "email": "contato@transportadoraexemplo.com.br",
    "natureza_juridica": "Sociedade Empresária Limitada",
    "porte": "03",
    "capital_social": "150000,00",
    "opcao_simples": "S",
    "opcao_mei": "N",
    "qtde_socios": 1,
    "socios": [
      {
        "nome": "FULANA DE TAL",
        "cpf_mascarado": "***123456**",
        "qualificacao": "49",
        "desde": "20150312"
      }
    ]
  },
  "meta": {
    "fonte": [
      "RFB/DadosAbertos"
    ],
    "competencia": "2026-09",
    "snapshot_id": "rfb-2026-09-3f9c2a7d41b8e605"
  }
}
```

## Erros

| Status | Quando | Código |
| --- | --- | --- |
| 401 | Chave ausente, inválida ou revogada. |  |
| 404 | Registro não encontrado. |  |
| 422 | Parâmetro inválido. |  |
| 429 | Cota diária da chave atingida (1.000 chamadas por padrão). Toda requisição autenticada conta, inclusive as que terminam em erro e as recusadas por cota. A contagem renova na virada do dia da base. A resposta não traz Retry-After. |  |
| 503 | Autenticação indisponível, base indisponível, consulta interrompida pelo tempo limite (consulta_demorada) ou, nas buscas, consultas demais do mesmo tipo em andamento (api_sobrecarregada). | `base_indisponivel` `api_sobrecarregada` `consulta_demorada` |