# cnpj.gratis — Documentação completa

Consulta gratuita de dados públicos de empresas brasileiras (CNPJ).
Dados da Receita Federal do Brasil, atualizados mensalmente.

## Endpoints da API

### Consulta por CNPJ (texto plano)

GET /{cnpj}.txt

Retorna dados da empresa em texto plano estruturado com Markdown.
Ideal para LLMs, agentes de IA e ferramentas de linha de comando.

Exemplo:
  curl https://cnpj.gratis/00000000000191.txt

### Consulta por CNPJ (JSON)

GET /{cnpj}.json

Retorna dados da empresa em formato JSON estruturado.
Ideal para desenvolvedores e integrações programáticas.

Exemplo:
  curl https://cnpj.gratis/00000000000191.json

### Parâmetros

- {cnpj}: 14 dígitos numéricos, sem pontuação (ex: 00000000000191)

### Rate Limit

10 requisições por minuto por IP.
Respostas com cache público de 24 horas (Cache-Control: public, max-age=86400).

## Campos retornados (JSON)

{
  "cnpj": "string — 14 dígitos",
  "cnpj_raiz": "string — 8 primeiros dígitos (raiz)",
  "filial_numero": "number — número da filial",
  "razao_social": "string — nome jurídico oficial",
  "nome_fantasia": "string | null — nome comercial",
  "situacao_cadastral": {
    "descricao": "string — ATIVA, BAIXADA, INAPTA, SUSPENSA, NULA",
    "motivo": "string | null",
    "data": "string — formato YYYY-MM-DD"
  },
  "data_abertura": "string — formato YYYY-MM-DD",
  "matriz_filial": "string — MATRIZ ou FILIAL",
  "porte_empresa": {
    "codigo": "string",
    "descricao": "string — ME, EPP, DEMAIS, NAO INFORMADO"
  },
  "descricao_natureza_juridica": "string",
  "capital_social": "number — em reais (R$)",
  "endereco": {
    "cep": "string — 8 dígitos",
    "tipo_logradouro": "string — RUA, AVENIDA, etc.",
    "logradouro": "string",
    "numero": "string",
    "complemento": "string | null",
    "bairro": "string",
    "uf": "string — sigla de 2 letras (SP, RJ, etc.)",
    "municipio": "string — nome da cidade",
    "municipio_codigo": "string — código IBGE"
  },
  "atividade_principal": {
    "codigo": "string — código CNAE (7 dígitos)",
    "descricao": "string — descrição da atividade"
  },
  "atividade_secundaria": [
    {
      "codigo": "string",
      "descricao": "string"
    }
  ],
  "quadro_societario": [
    {
      "nome": "string — nome do sócio",
      "qualificacao_socio": "string — ex: Sócio-Administrador",
      "identificador_socio": "string — tipo (PF ou PJ)",
      "data_entrada_sociedade": "string — formato YYYY-MM-DD",
      "faixa_etaria_descricao": "string | null"
    }
  ],
  "contato_telefonico": [
    {
      "completo": "string — DDD + número",
      "ddd": "string",
      "numero": "string",
      "tipo": "string — celular ou fixo"
    }
  ],
  "contato_email": [
    {
      "email": "string",
      "valido": "boolean",
      "dominio": "string"
    }
  ],
  "mei": {
    "optante": "boolean",
    "data_opcao_mei": "string | null",
    "data_exclusao_mei": "string | null"
  },
  "simples": {
    "optante": "boolean",
    "data_opcao_simples": "string | null",
    "data_exclusao_simples": "string | null"
  }
}

## Navegação do site

- Página da empresa: /{cnpj} (ex: /00000000000191)
- Empresas por estado: /{uf} (ex: /sp, /rj, /mg)
- Empresas por cidade: /{uf}/{cidade} (ex: /sp/sao-paulo)
- API texto: /{cnpj}.txt
- API JSON: /{cnpj}.json
- Documentação resumida: /llms.txt
- Documentação completa: /llms-full.txt

## Sobre os dados

- Fonte: Receita Federal do Brasil (dados públicos)
- Atualização: mensal
- Cobertura: todos os CNPJs ativos e inativos do Brasil
- Inclui: MEIs, empresas do Simples Nacional, e demais portes

## Códigos de erro HTTP

- 200: Sucesso
- 400: CNPJ inválido (não tem 14 dígitos numéricos)
- 404: CNPJ não encontrado na base de dados
- 429: Rate limit excedido (aguarde 60 segundos)

## Situações cadastrais possíveis

- ATIVA: empresa em operação regular
- BAIXADA: empresa encerrada/dissolvida
- INAPTA: declarada inapta pela Receita Federal
- SUSPENSA: com pendências fiscais
- NULA: inscrição cancelada/anulada

## Exemplos de uso

### Python
  import requests
  r = requests.get("https://cnpj.gratis/00000000000191.json")
  empresa = r.json()
  print(empresa["razao_social"])

### JavaScript
  const r = await fetch("https://cnpj.gratis/00000000000191.json");
  const empresa = await r.json();
  console.log(empresa.razao_social);

### cURL
  curl -s https://cnpj.gratis/00000000000191.txt
  curl -s https://cnpj.gratis/00000000000191.json | jq .razao_social

### Para LLMs / agentes
  Ao consultar um CNPJ, use o formato .txt para obter uma resposta
  em texto estruturado otimizada para processamento por linguagem natural.
  O formato .json é mais adequado para extrair campos específicos programaticamente.