{"id":34615552,"url":"https://github.com/caiopizzol/cnpj-data-pipeline","last_synced_at":"2026-05-24T00:06:13.361Z","repository":{"id":299219441,"uuid":"1002386248","full_name":"caiopizzol/cnpj-data-pipeline","owner":"caiopizzol","description":"Pipeline open-source que baixa e processa os dados da Receita Federal para PostgreSQL","archived":false,"fork":false,"pushed_at":"2026-05-12T09:33:25.000Z","size":1932,"stargazers_count":252,"open_issues_count":4,"forks_count":68,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-05-12T11:15:00.543Z","etag":null,"topics":["brazil","cnpj","etl","open-data","pipeline","postgresql","python","receita-federal"],"latest_commit_sha":null,"homepage":"https://cnpj.chat","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caiopizzol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-15T11:11:27.000Z","updated_at":"2026-05-12T09:33:28.000Z","dependencies_parsed_at":"2026-04-22T21:03:02.811Z","dependency_job_id":null,"html_url":"https://github.com/caiopizzol/cnpj-data-pipeline","commit_stats":null,"previous_names":["cnpj-chat/cnpj-data-pipeline","caiopizzol/cnpj-data-pipeline"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/caiopizzol/cnpj-data-pipeline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiopizzol%2Fcnpj-data-pipeline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiopizzol%2Fcnpj-data-pipeline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiopizzol%2Fcnpj-data-pipeline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiopizzol%2Fcnpj-data-pipeline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiopizzol","download_url":"https://codeload.github.com/caiopizzol/cnpj-data-pipeline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiopizzol%2Fcnpj-data-pipeline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazil","cnpj","etl","open-data","pipeline","postgresql","python","receita-federal"],"created_at":"2025-12-24T14:24:46.647Z","updated_at":"2026-05-24T00:06:13.348Z","avatar_url":"https://github.com/caiopizzol.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/2ab351f0-a940-4b55-a875-d5773ddf0515\" width=\"80\" height=\"80\" alt=\"cnpj.chat\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCNPJ Data Pipeline\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Baixa e processa dados de empresas brasileiras da Receita Federal para PostgreSQL.\n  \u003cbr\u003e\n  Parte do \u003ca href=\"https://cnpj.chat\"\u003ecnpj.chat\u003c/a\u003e — dados públicos de empresas, acessíveis para todos.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/caiopizzol/cnpj-data-pipeline/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/caiopizzol/cnpj-data-pipeline\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.11+-blue\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/caiopizzol/cnpj-data-pipeline\"\u003e\u003cimg src=\"https://codecov.io/gh/caiopizzol/cnpj-data-pipeline/graph/badge.svg\" alt=\"codecov\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e [!IMPORTANT]\n\u003e **Desde v1.3.2** — _A Receita Federal migrou os arquivos CNPJ para um novo repositório Nextcloud. Esta versão já suporta a nova URL e realiza downloads via WebDAV automaticamente. Nenhuma configuração adicional necessária._\n\n\u003e [!TIP]\n\u003e **Novo** — _Estratégia de carga configurável. Use `LOADING_STRATEGY=replace` para carga completa mais rápida (TRUNCATE + INSERT) ou `upsert` (default) para manter disponibilidade durante a carga._\n\n## Requisitos\n\n- [uv](https://docs.astral.sh/uv/) — gerencia pacotes e versões do Python. Substitui pip e virtualenv\n- [just](https://github.com/casey/just) — roda os comandos do projeto. Substitui Makefile\n- [Docker](https://docs.docker.com/get-docker/) — roda o PostgreSQL sem instalar banco local\n- **Python 3.11+** — `uv` instala automaticamente se necessário\n\n### Instalação\n\n**macOS** (Homebrew):\n```bash\nbrew install uv just\n```\n\n**Linux / Windows:** veja a instalação do [uv](https://docs.astral.sh/uv/getting-started/installation/) e do [just](https://github.com/casey/just#installation).\n\n\u003e `uv` e `just` são binários prontos — não precisa de Rust ou compilação.\n\n## Início Rápido\n\n```bash\ncp .env.example .env\njust up      # Iniciar PostgreSQL\njust run     # Executar pipeline\n```\n\n## Via Docker\n\nImagem pronta publicada a cada release no GitHub Container Registry. Não precisa clonar o repositório.\n\n```bash\n# Listar meses disponíveis\ndocker run --rm ghcr.io/caiopizzol/cnpj-data-pipeline --list\n\n# Processar um mês em um Postgres seu\ndocker run --rm \\\n  -e DATABASE_URL=postgres://user:pass@host:5432/cnpj \\\n  ghcr.io/caiopizzol/cnpj-data-pipeline --month 2024-11\n\n# Exportar para Parquet (sem banco)\ndocker run --rm \\\n  -e OUTPUT_FORMAT=parquet \\\n  -v $(pwd)/parquet:/app/parquet \\\n  ghcr.io/caiopizzol/cnpj-data-pipeline\n```\n\nO schema é aplicado automaticamente na primeira execução. Para rodar com o Postgres do projeto, use `docker compose run --rm pipeline \u003cargs\u003e`.\n\n## Comandos\n\n```bash\njust install # Instalar dependências\njust up      # Iniciar PostgreSQL\njust down    # Parar PostgreSQL\njust db      # Entrar no banco (psql)\njust run     # Executar pipeline\njust reset   # Limpar e reiniciar banco\njust lint    # Verificar código\njust format  # Formatar código\njust test    # Rodar testes\njust check   # Rodar todos (lint, format, test)\n```\n\n## Uso\n\n```bash\njust run                          # Processar mês mais recente\njust run --list                   # Listar meses disponíveis\njust run --month 2024-11          # Processar mês específico\njust run --month 2024-11 --force  # Forçar reprocessamento\n```\n\n## Configuração\n\n```bash\nDATABASE_URL=postgres://postgres:postgres@localhost:5435/cnpj\nBATCH_SIZE=500000\nTEMP_DIR=./temp\nDOWNLOAD_WORKERS=4\nRETRY_ATTEMPTS=3\nRETRY_DELAY=5\nCONNECT_TIMEOUT=30\nREAD_TIMEOUT=300\nKEEP_DOWNLOADED_FILES=false\nLOADING_STRATEGY=upsert  # \"upsert\" ou \"replace\"\nOUTPUT_FORMAT=postgres   # \"postgres\" ou \"parquet\"\nPARQUET_OUTPUT_DIR=./parquet\nPARQUET_TYPED_OUTPUT=false  # Quando true, datas e numéricos saem tipados (Date, Float64, Int32)\nPROCESS_WORKERS=1        # Arquivos do mesmo grupo em paralelo (ex: 4)\n```\n\n### Estratégia de carga (PostgreSQL)\n\n| Estratégia | Comando | Quando usar |\n|------------|---------|-------------|\n| `upsert` | `LOADING_STRATEGY=upsert just run` | Atualização incremental. Banco continua acessível durante a carga. |\n| `replace` | `LOADING_STRATEGY=replace just run` | Carga completa mensal. Mais rápido — faz TRUNCATE e insere direto. |\n\n### Formato de saída\n\n| Formato | Comando | Quando usar |\n|---------|---------|-------------|\n| `postgres` | `just run` | Default. Carrega no PostgreSQL. |\n| `parquet` | `OUTPUT_FORMAT=parquet just run` | Exporta direto para Parquet. Sem banco de dados — ideal para DuckDB, Pandas, Spark. |\n\n### Parquet\n\nCom `OUTPUT_FORMAT=parquet`, o pipeline exporta direto para arquivos Parquet com compressão ZSTD. Sem necessidade de PostgreSQL.\n\n```bash\nOUTPUT_FORMAT=parquet just run\n```\n\nSaída (~6GB a partir de ~85GB de CSVs):\n```\nparquet/\n  cnaes.parquet\n  motivos.parquet\n  municipios.parquet\n  naturezas_juridicas.parquet\n  paises.parquet\n  qualificacoes_socios.parquet\n  empresas.parquet\n  estabelecimentos.parquet\n  socios.parquet\n  dados_simples.parquet\n  manifest.json\n```\n\nConsulte com DuckDB:\n```sql\nSELECT * FROM 'parquet/empresas.parquet' WHERE cnpj_basico = '00000000';\nSELECT COUNT(*) FROM 'parquet/estabelecimentos.parquet' WHERE uf = 'SP';\n```\n\n## Schema\n\n\u003e Documentação completa: [docs/data-schema.md](docs/data-schema.md)\n\u003e\n\u003e Sobre normalização e tabelas derivadas: [docs/post-processing.md](docs/post-processing.md) · [docs/data-audit.md](docs/data-audit.md)\n\n```\nEMPRESAS (1) ─── (N) ESTABELECIMENTOS\n         ├─── (N) SOCIOS\n         └─── (1) DADOS_SIMPLES\n```\n\n## Fonte de Dados\n\nEstes dados são **públicos e oficiais**, disponibilizados pela própria Receita Federal do Brasil.\n\n| | |\n|---|---|\n| **Fonte** | [Portal de Dados Abertos — CNPJ](https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj) |\n| **Repositório** | [Receita Federal — Nextcloud](https://arquivos.receitafederal.gov.br/index.php/s/YggdBLfdninEJX9) |\n| **Atualização** | Mensal |\n| **Formato** | CSV (`;` separador, ISO-8859-1) |\n| **Base legal** | [Lei 12.527/2011](https://www.planalto.gov.br/ccivil_03/_ato2011-2014/2011/lei/l12527.htm) (Lei de Acesso à Informação), art. 8° |\n| **Regulamentação** | [Decreto 10.046/2019](https://www.planalto.gov.br/ccivil_03/_ato2019-2022/2019/decreto/D10046.htm) |\n| **Nota Técnica** | [RFB/COCAD n° 47/2024](https://www.gov.br/receitafederal/dados/nota_cocad_no_47_2024.pdf/) (alterada pela [NT 86/2024](https://www.gov.br/receitafederal/dados/nota-cocad-rfb-86-2024.pdf/)) |\n| **Metadados** | [Layout dos arquivos (PDF)](https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf) |\n\nO conjunto de dados CNPJ no Portal de Dados Abertos contém três recursos:\n\n| Recurso | Descrição | Status |\n|---------|-----------|--------|\n| Dicionário de dados | Layout e metadados dos arquivos | Referência |\n| **Inscrições no CNPJ** | Dados cadastrais de empresas, estabelecimentos, sócios e Simples Nacional | **Processado por este pipeline** |\n| Regimes Tributários | Forma de tributação (ECF): Lucro Real, Presumido, Arbitrado, Imunes/Isentas | Ainda não suportado |\n\nA Coordenação-Geral de Gestão de Cadastros e Benefícios Fiscais (Cocad) classifica estes dados como **dados públicos, de livre acesso a qualquer interessado** (NT 47/2024, item 10). CPFs de sócios são mascarados conforme art. 198 da [Lei 5.172/1966](https://www.planalto.gov.br/ccivil_03/leis/l5172compilado.htm) (CTN).\n\nEstes dados **não** são vazados, obtidos ilegalmente, ou protegidos por sigilo fiscal.\n\n## Contribuidores\n\n\u003ca href=\"https://github.com/caiopizzol\"\u003e\u003cimg src=\"https://github.com/caiopizzol.png\" width=\"50\" height=\"50\" alt=\"caiopizzol\" title=\"Caio Pizzol\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/fabriciopereiradiniz\"\u003e\u003cimg src=\"https://github.com/fabriciopereiradiniz.png\" width=\"50\" height=\"50\" alt=\"fabriciopereiradiniz\" title=\"Fabrício Pereira Diniz\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/dversoza\"\u003e\u003cimg src=\"https://github.com/dversoza.png\" width=\"50\" height=\"50\" alt=\"dversoza\" title=\"dversoza\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/renerlemes\"\u003e\u003cimg src=\"https://github.com/renerlemes.png\" width=\"50\" height=\"50\" alt=\"renerlemes\" title=\"Rener Lemes\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiopizzol%2Fcnpj-data-pipeline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiopizzol%2Fcnpj-data-pipeline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiopizzol%2Fcnpj-data-pipeline/lists"}