CNPJ API Lite

📘 English version available here → README.en.md

Video Tutorial

Para uma apresentação em vídeo deste projeto, acesse: Como consultar qualquer CNPJ de graça — Projeto completo no GitHub

Visão Geral do Projeto

O CNPJ API Lite é um projeto de código aberto que permite consultar dados públicos do CNPJ (Cadastro Nacional da Pessoa Jurídica) diretamente no seu computador, sem depender de APIs pagas ou conexão com servidores externos. O projeto é dividido em três etapas:

1. Download: Baixar automaticamente os arquivos ZIP disponibilizados pela Receita Federal.
2. Preparação: Processar os arquivos e consolidar tudo em um banco de dados SQLite local.
3. Consulta: Iniciar uma API local com interface web para buscar e explorar os dados.

Funcionalidades

• Download Automático: Identifica a pasta mais recente no portal da Receita Federal e baixa apenas os arquivos ainda não baixados.
• Banco Local SQLite: Dados consolidados em um único arquivo .db, com índices e busca por texto completo (FTS5).
• Interface Web: Sidebar com filtros combinados de nome, CNPJ, sócio, UF, município, CNAE e situação cadastral — todos com seleção múltipla.
• Busca por Sócio: Encontra todas as empresas onde uma pessoa ou empresa é sócia.
• Paginação e Ordenação: Configurável entre 10, 50 e 100 resultados por página.
• Exportação: Exporta os resultados filtrados diretamente para CSV ou Excel (.xlsx).
• Guia de Campos: Página de documentação explicando cada campo dos dados da Receita Federal.
• API REST: Endpoints disponíveis para integração via /docs (Swagger).

Estrutura do Projeto

.
├── config/
│   └── config.yaml         # Configuração de caminhos, URLs e tipos de dados
├── data/
│   ├── incoming/           # Arquivos ZIP baixados da Receita Federal
│   └── cnpj.db             # Banco de dados SQLite gerado no Passo 2
├── logs/                   # Arquivos de log de cada etapa
├── scripts/
│   ├── download.py         # Passo 1: Download dos arquivos
│   ├── prepare.py          # Passo 2: Geração do banco de dados
│   └── api.py              # Passo 3: API e interface web
├── static/
│   ├── index.html          # Interface de consulta
│   └── guia.html           # Guia de campos
├── 0_prep_environment.bat  # Criação do ambiente virtual (executar uma vez)
├── 1_download.bat          # Executa o Passo 1
├── 2_prepare.bat           # Executa o Passo 2
├── 3_api.bat               # Executa o Passo 3
├── requirements.txt        # Dependências Python
└── README.md               # Documentação do projeto

Iniciando o Projeto

Pré-requisitos

• Python 3.12+
• Windows (os arquivos .bat são para Windows; os scripts Python funcionam em qualquer sistema)

Clone o repositório e prepare o ambiente

git clone https://github.com/jmfeck/cnpj-api-lite.git
cd cnpj-api-lite

Execute o arquivo 0_prep_environment.bat para criar o ambiente virtual e instalar as dependências automaticamente. Isso só precisa ser feito uma vez.

Configuração

O arquivo config/config.yaml contém as configurações principais. Normalmente não é necessário alterá-lo.

Exemplo de config.yaml:

base_url: 'https://arquivos.receitafederal.gov.br/index.php/s/gn672Ad4CF8N6TK?dir=/Dados/Cadastros/CNPJ'

data_incoming: 'data/incoming'
db_path: 'data/cnpj.db'
logs_dir: 'logs'

csv_sep: ';'
csv_dec: ','
csv_quote: '"'
csv_enc: 'latin1'

Passo 1: Download

Execute 1_download.bat (ou python scripts/download.py).

Este script irá:

1. Acessar o portal da Receita Federal via WebDAV
2. Identificar a pasta mais recente no padrão AAAA-MM
3. Listar todos os arquivos .zip disponíveis
4. Verificar quais arquivos já foram baixados (comparando tamanho)
5. Baixar apenas os arquivos necessários
6. Salvar tudo em data/incoming/

Passo 2: Preparação

Execute 2_prepare.bat (ou python scripts/prepare.py).

Este script irá:

1. Ler todos os arquivos .zip de data/incoming/
2. Processar os CSVs internos em chunks de 50.000 linhas
3. Consolidar tudo em um banco SQLite (data/cnpj.db)
4. Criar índices para buscas rápidas
5. Construir tabelas de busca por texto completo (FTS5) para nomes e sócios

⚠️ Esta etapa pode levar várias horas dependendo do hardware. O banco final tem cerca de 43 GB.

Passo 3: Consulta

Execute 3_api.bat (ou python -m uvicorn scripts.api:app).

O servidor sobe em http://localhost:8000 e abre automaticamente no navegador.

• Interface de consulta: http://localhost:8000
• Guia de campos: http://localhost:8000/guia.html
• Documentação da API: http://localhost:8000/docs

Exportação

Com qualquer filtro ativo, clique em ⬇ Exportar ▾ e escolha entre:

• CSV — compatível com qualquer ferramenta, encoding UTF-8 com BOM para Excel
• Excel (.xlsx) — com cabeçalho formatado, abre direto no Excel

O limite de exportação é de 100.000 linhas por vez.

Logs

Os arquivos de log são gerados automaticamente em logs/, registrando progresso, erros e tempo de execução de cada etapa.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.

Licença

Este projeto está licenciado sob a Licença MIT.