Dados abertos do CNPJ: como baixar e usar a base da Receita Federal

A Receita Federal disponibiliza os dados públicos do Cadastro Nacional da Pessoa Jurídica para download. Isso permite construir uma base local, executar análises em massa e evitar uma chamada externa para cada registro. A contrapartida é um pipeline de dados considerável: são vários arquivos, sem cabeçalho, divididos por entidade, que precisam ser unidos, validados e atualizados a cada competência.

Este guia explica o caminho oficial e o trabalho real de engenharia. O volume exato muda todos os meses; por isso, dimensione armazenamento e tempo a partir dos arquivos da competência escolhida, não de um número fixo encontrado em tutorial antigo.

Onde baixar a base CNPJ da Receita Federal

Comece pelo conjunto oficial no Portal Brasileiro de Dados Abertos:

https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

O catálogo identifica o responsável pelo conjunto, metadados e recursos de download. A Receita Federal também mantém sua área de Dados Abertos em:

https://www.gov.br/receitafederal/pt-br/acesso-a-informacao/dados-abertos

Use os links publicados nessas páginas para chegar aos arquivos da competência atual. Diretórios e nomes podem mudar, portanto não dependa para sempre de uma URL copiada manualmente. Em automação, mantenha a URL base configurável e valide a lista de arquivos esperada antes de apagar ou substituir a base anterior.

O layout oficial está no documento CNPJ — Metadados:

https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Esse PDF é a referência para posição, significado e regras dos campos. O CSV não traz os nomes de coluna; sem o layout correto, uma leitura pode “funcionar” e ainda deslocar dados silenciosamente.

Estrutura dos arquivos

A base é normalizada em conjuntos relacionados. Os maiores costumam ser fragmentados em vários ZIPs numerados.

Empresas

Representa a entidade no nível do CNPJ básico, os oito primeiros dígitos compartilhados por matriz e filiais. Inclui campos como:

• CNPJ básico;
• razão social;
• natureza jurídica;
• qualificação do responsável;
• capital social;
• porte;
• ente federativo responsável, quando aplicável.

Uma linha de Empresas não corresponde necessariamente a um estabelecimento físico. Essa distinção é essencial para não contar matriz e filial de forma errada.

Estabelecimentos

Contém matriz e filiais. O CNPJ completo é formado pelo CNPJ básico, ordem do estabelecimento e dígitos verificadores. Entre os campos estão:

• indicador de matriz ou filial;
• nome fantasia;
• situação cadastral, data e motivo;
• data de início;
• CNAE principal e CNAEs secundários;
• tipo de logradouro, endereço, número, complemento e bairro;
• CEP, UF e município;
• telefones, fax e e-mail disponíveis.

O arquivo usa códigos para município, situação e outros domínios. Para exibir descrições, carregue também as tabelas auxiliares.

Sócios

O conjunto de Sócios representa o Quadro de Sócios e Administradores relacionado ao CNPJ básico. Inclui identificador do tipo de sócio, nome, qualificação, data de entrada, país e dados de representante quando aplicáveis.

CPFs de pessoas físicas aparecem descaracterizados conforme as regras oficiais; a base aberta não deve ser tratada como fonte de CPF completo. A qualificação é um código e deve ser ligada à tabela de Qualificações.

Simples Nacional

O arquivo do Simples relaciona-se ao CNPJ básico e contém indicadores e datas de opção ou exclusão do Simples Nacional e do SIMEI. Como o regime pode mudar, registre a competência da base junto da linha importada.

Tabelas auxiliares

O pacote também inclui domínios como:

• CNAEs;
• municípios;
• naturezas jurídicas;
• qualificações de sócios;
• motivos de situação cadastral;
• países.

São arquivos pequenos, mas fundamentais para traduzir códigos. Não substitua códigos por descrições durante a camada bruta: preserve ambos para auditoria e futuras mudanças de nomenclatura.

Tamanho e periodicidade

A publicação é organizada por competência e normalmente atualizada em ciclo mensal. Confirme a data do recurso no catálogo e dentro do diretório oficial antes do processamento. A presença de uma pasta nova não garante que todos os fragmentos terminaram de ser publicados.

O tamanho varia com a quantidade de registros e a compactação. O conjunto completo ocupa vários gigabytes compactado e pode exigir dezenas de gigabytes temporários durante download, descompressão, staging, índices e banco final. Não fixe no código uma estimativa de uma edição antiga.

Como referência verificável, a competência 2026-07, publicada em 12 de julho de 2026, possuía 37 ZIPs: dez de Empresas, dez de Estabelecimentos, dez de Sócios, um do Simples e seis tabelas auxiliares. A soma era de 7.643.363.104 bytes compactados, cerca de 7,64 GB em unidade decimal. Esse número descreve apenas aquela competência e não deve virar capacidade fixa.

Antes de iniciar:

1. obtenha Content-Length ou liste os tamanhos publicados;
2. some todos os ZIPs;
3. reserve espaço para os compactados e descompactados;
4. acrescente espaço do banco, WAL, índices e operação de troca;
5. mantenha a competência anterior até validar a nova.

Em nuvem, custo de I/O e tempo de criação de índices podem ser mais relevantes que o download.

Formato, encoding e leitura

As edições amplamente utilizadas do conjunto são arquivos ZIP contendo textos delimitados por ponto e vírgula, sem cabeçalho. Pipelines existentes normalmente leem os textos em Latin-1/ISO-8859-1, mas o leiaute oficial consultado não declara o encoding. Portanto, trate essa codificação como observação operacional: detecte e valide encoding, delimitador e quantidade de colunas em cada competência.

Exemplo de leitura em Python:

import csv
import zipfile
from pathlib import Path

EMPRESAS_COLUMNS = [
    "cnpj_basico",
    "razao_social",
    "natureza_juridica",
    "qualificacao_responsavel",
    "capital_social",
    "porte",
    "ente_federativo_responsavel",
]

def rows_from_zip(zip_path: Path):
    with zipfile.ZipFile(zip_path) as archive:
        for member in archive.namelist():
            with archive.open(member) as raw:
                lines = (line.decode("latin-1") for line in raw)
                reader = csv.reader(lines, delimiter=";")
                for values in reader:
                    if len(values) != len(EMPRESAS_COLUMNS):
                        raise ValueError(
                            f"{member}: esperado {len(EMPRESAS_COLUMNS)} campos, recebido {len(values)}"
                        )
                    yield dict(zip(EMPRESAS_COLUMNS, values))

Esse exemplo é didático. Inserir linha a linha com ORM será lento para a base completa. Prefira COPY do PostgreSQL, carga em lote, ferramentas colunares ou engine distribuída conforme o objetivo.

Prepare o pipeline para o CNPJ alfanumérico

A Receita Federal prevê CNPJ alfanumérico para novas inscrições a partir de 31 de julho de 2026. CNPJs existentes permanecem válidos, mas validações que aceitam somente \d{14} precisam evoluir conforme a especificação oficial.

Preserve o identificador como texto, não aplique conversão numérica e mantenha a regra de validação versionada. Antes de alterar a produção, acompanhe https://www.gov.br/receitafederal/pt-br/acesso-a-informacao/acoes-e-programas/programas-e-atividades/cnpj-alfanumerico/cnpj-alfa e o leiaute da competência efetivamente baixada.

Chaves e joins corretos

O relacionamento principal é o CNPJ básico:

SELECT
  e.cnpj_basico,
  e.razao_social,
  est.cnpj_ordem,
  est.cnpj_dv,
  est.nome_fantasia,
  est.situacao_cadastral
FROM empresas AS e
JOIN estabelecimentos AS est
  ON est.cnpj_basico = e.cnpj_basico;

O CNPJ completo pode ser materializado como texto:

est.cnpj_basico || est.cnpj_ordem || est.cnpj_dv

Use TEXT ou CHAR, não número. CNPJ, CNAE, CEP e códigos podem começar com zero e não participam de cálculos aritméticos.

Sócios e Simples também se ligam pelo CNPJ básico. Como uma empresa pode ter vários estabelecimentos e vários sócios, juntar tudo em uma única consulta sem agregação produz multiplicação de linhas. Por exemplo, três estabelecimentos e quatro sócios podem gerar doze combinações. Modele relações separadas ou agregue cada lado antes do join.

Um pipeline ETL seguro

1. Descoberta da competência

Liste os recursos oficiais e selecione uma competência fechada. Grave URL, nome, tamanho e data de coleta em um manifesto.

2. Download retomável

Baixe para uma área temporária com retry e checksum local. Um arquivo existente só deve ser aceito se tamanho e integridade do ZIP estiverem corretos.

3. Validação estrutural

Abra cada ZIP, confira se não está corrompido, conte colunas por tipo e valide amostras. Rejeite a carga se faltar qualquer fragmento esperado.

4. Camada bruta

Carregue valores como texto em tabelas de staging. Isso preserva zeros, vírgula decimal e conteúdo original. Adicione colunas competencia, arquivo_origem e linha_origem quando rastreabilidade for importante.

5. Transformação

Normalize espaços, converta datas explicitamente, trate capital social com vírgula decimal, componha o CNPJ e traduza códigos por tabelas auxiliares. Não converta vazio automaticamente para zero.

6. Testes de qualidade

Verifique:

• quantidade de arquivos e linhas;
• tamanho em relação à competência anterior;
• unicidade de chaves esperadas;
• percentuais de CNPJ válido;
• códigos sem correspondência nas tabelas auxiliares;
• distribuição de situações e UFs;
• amostras conhecidas.

Mudança grande pode ser real, mas precisa ser investigada antes da publicação.

7. Índices

Crie índices depois da carga em massa quando isso for mais eficiente. Os principais candidatos são CNPJ básico, CNPJ completo e colunas usadas em filtros, como situação, UF, município e CNAE. Índice demais aumenta disco e tempo de atualização.

8. Troca atômica

Não atualize a única tabela de produção enquanto usuários consultam. Carregue um novo schema ou conjunto de tabelas, valide, e faça a troca por view, rename ou partição. Mantenha rollback para a competência anterior.

Atualização mensal sem reconstruir o serviço

A publicação é um snapshot, não um log de alterações. Uma abordagem simples é reconstruir a base em staging e trocar. Outra é comparar snapshots e gerar diferenças, mas isso aumenta complexidade.

Para servir uma API com disponibilidade:

• mantenha banco de leitura separado do ETL;
• faça a carga em infraestrutura temporária;
• replique ou troque apenas após os testes;
• aqueça caches essenciais;
• registre a competência em toda resposta;
• monitore latência e erros após a troca.

O artigo como integrar CNPJ em Python e Node mostra o lado consumidor de uma API, incluindo cache e retry.

Quando processar a base por conta própria

Faz sentido quando:

• consultas em massa são parte central do produto;
• a equipe precisa de SQL analítico sobre o universo completo;
• existe competência para operar banco e ETL;
• a atualização mensal é aceitável;
• autonomia e previsibilidade justificam o investimento;
• o uso respeita finalidade, segurança e regras aplicáveis.

Exemplos incluem pesquisa acadêmica, segmentação agregada, motores de busca e data warehouse corporativo. O diretório de empresas ilustra uma experiência de navegação que depende de dados previamente organizados, não de uma chamada síncrona por card.

Quando usar uma API pronta

Uma API de dados empresariais tende a ser melhor quando:

• o volume não justifica um pipeline nacional;
• a equipe precisa entregar rápido;
• atualização, suporte e disponibilidade têm valor;
• são necessários dados de outras fontes;
• QSA e contatos precisam vir consolidados;
• o custo de engenharia supera a assinatura.

Não compare apenas preço por consulta com custo de armazenamento. Inclua horas de engenharia, reprocessamento, observabilidade, segurança, backup, atualização e atendimento a incidentes.

Uma arquitetura híbrida também é comum: snapshot aberto para busca e análise ampla, API para atualização pontual e campos enriquecidos.

Governança e LGPD

Ser dado público não elimina responsabilidade. Defina finalidade, base legal quando houver dados pessoais, controle de acesso, retenção e resposta a solicitações. Evite reconstruir identificadores que a fonte descaracteriza. Proteja e-mail, telefone e dados societários contra uso abusivo.

Registre a origem e a competência. Quando um usuário questionar um resultado, a equipe deve conseguir explicar qual arquivo e transformação produziram aquele dado.

Perguntas frequentes

A base CNPJ é gratuita?

Sim. O conjunto oficial é disponibilizado como dado aberto. Isso não torna gratuitos armazenamento, processamento, operação nem eventuais fontes adicionais.

A Receita publica um único CSV pronto?

Não. O conjunto é dividido em Empresas, Estabelecimentos, Sócios, Simples e tabelas auxiliares, com fragmentação dos maiores arquivos. É necessário unir as partes pelas chaves do layout.

Qual é o tamanho exato do download?

Ele muda a cada competência. Consulte o tamanho de todos os recursos oficiais antes de baixar e reserve espaço adicional para descompressão, staging, banco, índices e rollback.

Posso atualizar apenas os CNPJs que mudaram?

A distribuição é feita como snapshot. Você pode comparar duas competências e derivar diferenças, mas terá de processar ambos os estados e tratar inclusões, alterações e remoções com cuidado.

Base própria substitui uma API?

Depende. Ela atende muito bem busca e análise sobre o snapshot, mas não entrega automaticamente atualização sob demanda, SLA, suporte ou enriquecimento de outras fontes. Muitas operações combinam base aberta e API.