cnpj.ia.br
docs · base agosto/2026Atualizado em

De onde vêm os dados e com que frequência mudam

Fonte primária nos dados abertos da Receita Federal, atualização mensal com a data da base em toda resposta de consulta e busca, o que é enriquecimento da Oportunidados, o que é derivado e como contamos.

A base é uma foto mensal dos dados abertos do CNPJ publicados pela Receita Federal, enriquecida pela Oportunidados com contatos e site. Toda resposta de consulta e de busca informa em meta.data_as_of a data da foto que respondeu; hoje é agosto/2026. Nenhum campo reflete o instante da chamada: a API serve a foto mensal, e diz qual em cada resposta.

Fontes

Grupo de campos Origem Componente de meta.source
Cadastro, situação, natureza jurídica, porte, capital, CNAE, endereço, Simples e MEI Dados abertos do CNPJ da Receita Federal, arquivos mensais rfb_open_data
Quadro societário (sem CPF), regime tributário Dados abertos da Receita Federal rfb_open_data
Telefones e e-mail Dados abertos da Receita Federal, quando declarados rfb_open_data
Site e contatos extras Enriquecimento da Oportunidados, com a origem em cada item (contatos_extras[].origem) oportunidados
Faixa de faturamento e faixa de funcionários Derivação da Oportunidados a partir do porte e de dados oficiais de vínculos oportunidados

O campo meta.source vale rfb_open_data+oportunidados em toda resposta, para deixar claro que os dois tipos de dado convivem. Os dados abertos da Receita Federal são de uso livre nos termos publicados no portal de dados abertos do governo federal; o enriquecimento é da Oportunidados e segue os termos de uso.

Ciclo de atualização

A Receita Federal publica os arquivos uma vez por mês. Quando a nova foto entra em produção, data_as_of passa a informar a data dela. Durante a carga a API pode responder 503 maintenance com Retry-After; a janela é anunciada em status.cnpj.ia.br e o changelog registra cada nova base. Dia e duração típicos da janela serão publicados depois de ciclos medidos em produção.

GET /v1/status responde sem chave e sem custo com api_version, data_as_of, maintenance, retry_after_seconds: é o jeito de um sistema saber a data da base e se há manutenção em curso antes de disparar um lote.

curl 
curl "https://api.cnpj.ia.br/v1/status"

O que é derivado

  • faixa_faturamento é derivada do porte declarado à Receita Federal e carrega origem: "porte". Não é estimativa nem valor apurado; é a faixa legal que corresponde ao porte.
  • faixa_funcionarios é texto: número exato ou intervalo, conforme a fonte oficial de vínculos; null quando não há dado.
  • As descrições que acompanham os códigos vêm das tabelas indicadas em Campos da resposta: oficiais da Receita Federal onde a fonte está apontada, internas onde a página diz isso. A API entrega código e descrição juntos para você não precisar de tabela local.
  • has_phone, has_email, has_website e has_mobile_phone são calculados sobre os dados da própria base e dizem se o perfil full teria o contato.

Como contamos

Os totais de CNPJs registrados e de CNPJs ativos que o site publica vêm da base servida, sempre acompanhados da data da base (agosto/2026). “Registrado” é todo estabelecimento presente nos arquivos da Receita Federal, em qualquer situação cadastral; “ativo” é situação cadastral 02. Os dois números são recalculados a cada foto mensal e nunca projetados entre uma foto e outra.

Relacionados

Perguntas frequentes

Os dados refletem o instante da consulta?

Não. A base é uma foto mensal dos dados abertos da Receita Federal, e toda resposta diz qual foto respondeu em meta.data_as_of. Uma alteração cadastral feita hoje aparece na próxima carga mensal.

Como sei quando a base foi atualizada?

Por três caminhos: meta.data_as_of em qualquer resposta, GET /v1/status sem chave, e o changelog das docs, que registra cada base nova com a data.

O que acontece durante a atualização?

A API pode responder 503 maintenance com Retry-After enquanto a nova foto é carregada. A janela é anunciada na status page. Respeite o Retry-After e repita; nada é cobrado.

A faixa de faturamento é uma estimativa?

Não. É derivada do porte que a empresa declarou à Receita Federal, e o próprio campo diz isso em origem: "porte". É a faixa legal correspondente ao porte, não um valor apurado nem estimado pela Oportunidados.

Posso usar os dados fora da API, em um banco meu?

Os dados cadastrais da Receita Federal são abertos e você pode armazená-los. O enriquecimento da Oportunidados e o uso dos contatos seguem os termos de uso aceitável; a página de privacidade explica o que pode e o que não pode.