# cnpj.chat — Documentação Completa

> Consulte dados de 60 milhões de empresas brasileiras da Receita Federal. CNPJ exato, busca por razão social, atividade (CNAE) e localização. Atualizado mensalmente. Open source.

## Visão geral

cnpj.chat é uma ferramenta gratuita e open source que permite consultar dados públicos de empresas brasileiras em linguagem natural. Os dados vêm diretamente da Receita Federal do Brasil e são processados mensalmente por um pipeline automatizado.

O projeto existe porque os dados cadastrais de empresas brasileiras são públicos por lei, mas na prática estão distribuídos em 85GB de arquivos compactados que mudam de formato sem aviso. cnpj.chat resolve esse problema processando os dados uma vez e disponibilizando para consulta gratuita.

## Como funciona

1. O usuário faz uma pergunta em português (ex: "Quem é o CNPJ 00.000.000/0001-91?").
2. O servidor pede a um modelo de linguagem para classificar a pergunta em um intent tipado (lookup de CNPJ, busca de empresas, contagem por estado etc.). O modelo **não escreve SQL**, não escolhe tabelas e não inventa códigos CNAE.
3. O servidor resolve referências em linguagem natural — `cnae_query` (ex: "padarias") vira um código CNAE de 7 dígitos, `municipio_query` ("Campinas") vira a forma canônica do município — usando os índices semânticos já bundlados.
4. O servidor valida o intent contra um conjunto fixo de filtros suportados (mesmas regras de `/buscar`). Combinações fora desse conjunto retornam `unsupported`, não SQL ad hoc.
5. SQL determinístico é compilado pelo servidor e executado em PostgreSQL de leitura. A resposta é JSON estruturado.
6. Para CSV completo, `prepare_export` devolve um payload que o cliente envia para `/export/filters` (com email). O `/chat` em si nunca dispara um export.

## Intents suportados

O `submit_intent` tool aceita um dos seguintes valores em `intent`:

- **lookup_cnpj** — uma empresa pelo CNPJ exato (14 caracteres, alfanumérico, com ou sem máscara).
- **search_companies** — listagem com filtros. Requer pelo menos um de `uf`, `razao_social_prefix`, `nome_fantasia_prefix`, `cnae_query`. Aceita `municipio_query` (resolvido server-side) e `page`.
- **count_companies** — totais pré-computados. Suporta apenas `uf`, `uf + municipio`, ou `uf + cnae` (um código). Contagens livres não são suportadas.
- **lookup_cnae** — código CNAE exato (`code`) ou descrição em linguagem natural (`query`), nunca ambos.
- **prepare_export** — devolve um payload pronto para `/export/filters`. Não gera o CSV; o cliente decide submeter ou não.
- **unsupported** — quando nenhum intent acima cobre a pergunta. Inclui motivo (`reason`) e mensagem amigável (`message`).

Categorias explicitamente **não suportadas** em v1, retornadas como `unsupported`:

- Consultas de sócios / quadro societário / qualificação de sócio.
- Detalhes de endereço (rua, CEP, número, bairro), telefones, emails.
- Filtros por data (empresas abertas em X, fundadas em Y).
- Busca por múltiplos CNAEs ao mesmo tempo.
- Comparações livres, rankings, agregações analíticas ("qual a maior", "compare X e Y").

## Dados acessíveis pelo `/chat`

O `/chat` consulta tabelas pré-computadas em PostgreSQL otimizadas para os intents acima. As tabelas internas não são parte do contrato — o servidor escolhe e compila o SQL. Colunas retornadas em respostas:

- razao_social (texto, oficial)
- nome_fantasia (texto, comercial)
- cnpj (14 caracteres, alfanumérico)
- uf (UF, 2 letras)
- municipio_nome (texto, maiúsculas, sem acentos)
- situacao_cadastral (código: 02 = ativa, 08 = baixada)
- cnae_descricao (texto)
- data_inicio_atividade (YYYY-MM-DD)

Filtros padrão aplicados em `search_companies` e `prepare_export`: ativa (situacao = 02), matriz (identificador_matriz_filial = 1).

## API

Base URL: `https://api.cnpj.chat`

### POST /chat

Envie uma pergunta em português; receba um `ChatResponse` tipado.

**Request**

```json
{ "message": "padarias em SP" }
```

**Response shape** (discriminada por `intent`):

```jsonc
// search_companies
{
  "intent": "search_companies",
  "supported": true,
  "rows": [
    {
      "razao_social": "PADARIA EXEMPLO LTDA",
      "cnpj": "00000000000000",
      "uf": "SP",
      "municipio_nome": "SAO PAULO",
      "cnae_descricao": "Padaria e confeitaria com predominância de revenda"
    }
  ],
  "count": 4200,
  "pagination": { "page": 1, "has_more": true },
  "filters": { "uf": "SP", "cnae": ["4721102"] },
  "resolved": {
    "cnae": [
      { "code": "4721102", "descricao": "Padaria e confeitaria...", "score": 0.83 }
    ]
  }
}

// lookup_cnpj
{
  "intent": "lookup_cnpj",
  "supported": true,
  "company": {
    "cnpj": "00000000000191",
    "razao_social": "BANCO DO BRASIL SA",
    "uf": "DF",
    "municipio_nome": "BRASILIA",
    "cnae_descricao": "Bancos múltiplos, com carteira comercial"
  }
}

// count_companies
{
  "intent": "count_companies",
  "supported": true,
  "count": 1234567,
  "bucket": "uf",
  "filters": { "uf": "SP" }
}

// prepare_export
{
  "intent": "prepare_export",
  "supported": true,
  "export_payload": { "uf": "SP", "cnae": "4721102" },
  "filters": { "uf": "SP", "cnae": ["4721102"] },
  "resolved": { "cnae": [...] },
  "message": "Filtros prontos. Para gerar o CSV, envie esses parâmetros para /export/filters com seu email."
}

// unsupported
{
  "intent": "unsupported",
  "supported": false,
  "reason": "socios_query",
  "message": "Buscas por sócios ainda não estão disponíveis nesta versão do /chat."
}
```

Notas de contrato:

- Nenhuma resposta inclui `meta.sql`. O SQL é compilado pelo servidor; o LLM nunca o escreve.
- `prepare_export` **não** dispara a exportação. O cliente decide submeter `export_payload + email` para `/export/filters`.
- Códigos HTTP: `200` quando o intent foi extraído (mesmo `unsupported`); `400` para input inválido; `502` para falha do LLM ou validação do intent; `503` quando o serviço não está configurado.

### POST /export/filters

Gera o CSV completo a partir de filtros tipados; entrega por email.

**Request**

```json
{
  "email": "user@example.com",
  "uf": "SP",
  "cnae": "4721102"
}
```

Combinações suportadas seguem as mesmas regras do `/chat search_companies` / `prepare_export`. Resposta `202` quando o job foi aceito; o email com link de download chega quando o CSV estiver pronto.

### GET /export/download/:id

Stream do CSV gerado por `/export/filters`. ID vem no email.

## Tecnologia

- **Pipeline de dados**: Python, processamento mensal dos arquivos da Receita Federal.
- **Banco de dados**: PostgreSQL com tabelas e índices pré-computados para os intents do `/chat` e os filtros do `/buscar`, lido pelos Workers via Hyperdrive (conexão pooled na borda).
- **API**: Hono + TypeScript em Cloudflare Workers.
- **Serviços auxiliares**: a geração de CSV (`/export/filters`) roda em um container Python (psycopg2 + boto3) em VM dedicada (pg-export).
- **Frontend**: Astro estático + Tailwind CSS.
- **IA**: Anthropic Claude (`tool_use`) para classificar a pergunta em um intent tipado. O modelo nunca emite SQL.
- **Embeddings**: Cohere para resolver `cnae_query` contra um índice vetorial dos códigos CNAE.

## Fonte dos dados

Todos os dados vêm exclusivamente da Receita Federal do Brasil:
https://arquivos.receitafederal.gov.br/index.php/s/YggdBLfdninEJX9

Não há enriquecimento, estimativa ou dados de terceiros. Fonte única: o governo.

## Links

- Site: https://cnpj.chat
- API: https://api.cnpj.chat
- GitHub: https://github.com/caiopizzol/cnpj-data-pipeline