Dados oficiais da Receita Federal do Brasil em JSON: cadastro completo,
busca por nome, raiz e sócio, enriquecimento em massa e demonstrações
financeiras de companhias abertas. Uma requisição, uma resposta.
A API da CNPGolden é REST, responde em JSON codificado em UTF-8 e usa
os códigos de status HTTP convencionais. Todos os endpoints ficam sob
uma única URL base:
https://api.cnpgolden.com.br/api/v1
O que dá para fazer
Consultar um CNPJ e receber razão social, situação
cadastral, endereço, contato, CNAEs, regime tributário e quadro
societário numa só chamada.
Buscar empresas por razão social, por raiz de CNPJ
(matriz e filiais) ou pelo nome de um sócio.
Enriquecer bases com até 1.000 CNPJs por requisição.
Ler balanços de companhias abertas brasileiras
(DRE, balanço patrimonial, fluxo de caixa), a partir dos dados
públicos da CVM.
Versionamento
A versão faz parte do caminho (/api/v1). Campos novos podem
ser adicionados às respostas a qualquer momento — trate isso como uma
mudança compatível e não quebre seu parser com campos desconhecidos.
Remoções ou renomeações só aconteceriam em uma /api/v2.
Rotas legadas. As URLs
www.cnpgolden.com.br/api/cnpj/<cnpj>,
/api/search/by-name e /api/search/bulk
estão descontinuadas: hoje elas exigem X-API-Key,
respondem com o header Deprecation: true e serão
removidas. Migre para https://api.cnpgolden.com.br/api/v1.
Início rápido
Da conta à primeira resposta em três passos.
1. Crie uma conta gratuita
A conta é gratuita e, com o e-mail confirmado, recebe
70 créditos por mês.
Criar conta.
2. Gere sua chave
Em Minha conta → API, crie
uma chave. Ela começa com cnpg_live_ e é exibida uma única
vez — guarde em uma variável de ambiente, nunca no código versionado.
Sem chave nenhuma, GET /cnpj ainda responde — limitado a
10 consultas por IP por dia. Dá para testar a
integração antes de criar a conta.
Autenticação
Envie sua chave no header X-API-Key em toda requisição.
Não há OAuth, nem Authorization: Bearer, nem chave por
query string.
X-API-Key: cnpg_live_SUA_CHAVE_AQUI
Gerenciando chaves
Até 5 chaves ativas por conta — use chaves
separadas por ambiente ou por serviço.
A chave completa aparece uma única vez, na criação.
Depois só o prefixo fica visível.
Revogar é imediato: a chave revogada passa a responder
401 na requisição seguinte.
Guardamos apenas o hash SHA-256 da chave — nem nós conseguimos
recuperá-la. Perdeu, gere outra.
Se estiver recebendo 429 sem explicação, confira o prefixo da
chave. Uma chave malformada que não comece com
cnpg_live_ não gera 401: a requisição cai
no caminho anônimo e passa a valer o limite por IP (10/dia). O
401 só aparece quando a chave tem o prefixo correto mas
é desconhecida ou foi revogada.
Nunca use a chave no navegador do usuário final. Ela
gasta os seus créditos. Chame a API do seu
servidor. (O console desta página é uma
exceção consciente: a chave que você digita ali fica no seu
navegador e vai direto para a API — não passa pelo nosso servidor
nem é armazenada.)
Créditos, limites e cobrança
Cada chamada gasta créditos do seu saldo, com o custo fixo da tabela abaixo
(lida ao vivo da configuração pública). A conta grátis recebe
70 créditos por mês com o
e-mail confirmado; para mais, assine um pacote ou compre créditos avulsos.
Como o consumo é debitado
Primeiro saem os créditos que vencem antes (os do mês, grátis ou da assinatura).
Depois, os avulsos, que não vencem.
Sem saldo, a API responde 402 com custo, saldo
e faltam.
Há também um limite de chamadas por minuto:
10 na conta grátis e o do degrau na assinatura.
Acima dele a API responde 429 com Retry-After.
Ação
Custo
Balanços pela API Consulta de demonstrações financeiras (CVM) com chave de API.
1 crédito por consulta
Busca pela API Busca por nome, raiz ou sócio com chave de API, por resultado devolvido.
1 crédito a cada 10 resultados
Consulta de CNPJ pela API Uma consulta completa de CNPJ com chave de API.
1 crédito por consulta
Consulta em lote pela API POST /search/bulk, por CNPJ enviado.
{
"error": "Forbidden",
"feature": "bulk",
"message": "Consulta em massa (bulk) exige uma conta. Crie a sua em cnpgolden.com.br/conta/cadastrar",
"success": false
}
{
"error": "Too Many Requests",
"message": "Muitas chamadas por minuto. Espere alguns segundos e tente de novo.",
"success": false
}
{
"error": "Too Many Requests",
"message": "Quota gratuita diária de 10 consultas por IP atingida. Crie uma conta para continuar.",
"success": false
}
{
"error": "ranking_nao_gerado",
"message": "O ranking por município ainda não foi gerado.",
"success": false
}
{
"error": "Internal server error",
"message": "Erro interno do servidor",
"success": false
}
O 402 traz um caminho de saída legível por máquina: os
campos custo, saldo e faltam
permitem montar na sua aplicação o aviso "faltam N créditos".
Paginação e limites
Os endpoints de busca aceitam per_page, limitado a
100 — valores maiores são reduzidos silenciosamente.
Use has_more para saber se existem mais resultados.
O parâmetro page não funciona em todos os
endpoints. Ele pagina de verdade em
/search/by-socio, /search/socio/empresas e
/cvm/empresas. Em /search/by-name e
/search/by-raiz ele é aceito e devolvido na resposta,
mas não altera o resultado — a consulta aplica
LIMIT sem OFFSET. Nesses dois, trabalhe com
per_page até 100 e refine o termo de busca.
Contagens
Em /search/by-raiz, total_available é a
contagem real de estabelecimentos da raiz. Já em
/search/by-name, tanto total quanto
total_available refletem apenas o lote devolvido, não o
total de correspondências na base.
Acompanhamento do saldo
A API não retorna headers X-RateLimit-*.
Para acompanhar saldo, extrato e vencimentos, use
Minha conta → Créditos.
Trate o 402 como "sem saldo" e o 429 como limite por minuto.
Outros tetos
/search/bulk: 1.000 CNPJs por arquivo.
/search/by-socio: 5.000 registros candidatos antes do
agrupamento — quando o teto é atingido, a resposta traz
truncated: true.
/cvm/comparar: 5 companhias por chamada.
/cvm/empresas: página fixa de 50 itens.
CNAEs secundários em GET /cnpj: os 5 primeiros.
Formato do CNPJ
O CNPJ tem 14 caracteres: raiz (8) +
estabelecimento (4) +
dígito verificador (2). O estabelecimento
0001 identifica a matriz; qualquer outro é filial.
Nunca limpe um CNPJ com um filtro de apenas-dígitos.
Desde a mudança de 2026 da Receita Federal, as 12 primeiras posições
aceitam letras (0-9A-Z) e só os 2 dígitos verificadores
continuam numéricos. Um replace(/\D/g, '') transformaria
12ABC34501DE35 em 1234501, e a consulta
falharia. Remova apenas pontuação e converta para maiúsculas.
A API aceita qualquer máscara — 00.000.000/0001-91 e
00000000000191 são equivalentes. Letras minúsculas são
convertidas automaticamente.
Dígito verificador
A API não valida o dígito verificador: ela confere
apenas o formato e consulta a base. Um CNPJ bem formado mas inexistente
retorna 404, e não 400. Para validar o DV antes
de gastar créditos, use o
validador gratuito ou o
endpoint /cnpj-alfa/validar.
Testar agora
Dispare uma requisição real e veja a resposta. Sua chave fica apenas
neste navegador e vai direto para api.cnpgolden.com.br —
não passa pelo nosso servidor web nem é armazenada.
Só endpoints GET aparecem aqui. Para
POST /search/bulk, copie o exemplo de cURL da
seção do endpoint.
CNPJ
Consulta e busca no cadastro de empresas da Receita Federal (base completa de CNPJs, estabelecimentos e quadro societário).
GET/cnpj
Consultar um CNPJ
Retorna o cadastro completo de um estabelecimento: razão social, nome fantasia, situação cadastral, endereço, contato, CNAEs, regime tributário (Simples/MEI) e quadro societário — tudo em uma única requisição.
1 crédito por consultaFunciona sem chave (10/IP/dia)
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
cnpj obrigatório
query
string
—
CNPJ com 14 caracteres. Aceita qualquer máscara — pontuação é removida e letras são convertidas para maiúsculas antes da consulta.
Único endpoint que responde sem chave de API, limitado a 10 consultas por IP por dia. Com chave, cada consulta gasta créditos do seu saldo.
Os campos situacao e porte vêm como código bruto da Receita (ex.: "02", "05") e as datas como AAAAMMDD. Os endpoints de busca devolvem esses mesmos campos já formatados — a diferença é intencional e está documentada em cada um.
cnaes_secundarias é truncado nos 5 primeiros códigos.
Não há validação de dígito verificador: um CNPJ bem formado mas inexistente retorna 404, não 400.
Todo campo textual ausente volta como string vazia (""), nunca null; capital_social ausente volta como 0.
tipo_estabelecimento (MATRIZ/FILIAL) vem do campo identificador_matriz_filial da Receita (1 = matriz, 2 = filial). Não deduza a matriz pelo sufixo 0001: empresa que muda de sede rebaixa o 0001 original a filial e promove outro estabelecimento a matriz.
estabelecimentos_raiz e estabelecimentos_raiz_ativos contam todos os estabelecimentos da mesma raiz (8 primeiros caracteres), inclusive o consultado. São recalculados a cada carga da base; para listá-los, use GET /search/by-raiz.
GET/search/by-name
Buscar empresas por razão social
Busca estabelecimentos cuja razão social contenha o termo informado (correspondência parcial, sem distinção de maiúsculas).
1 crédito a cada 10 resultados
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
nome obrigatório
query
string
—
Termo de busca. Mínimo 3 e máximo 200 caracteres. Os caracteres %, _ e \ são escapados.
apenas_ativas opcional
query
boolean
true
Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page opcional
query
integer
1
Aceito e ecoado na resposta, mas SEM EFEITO neste endpoint — a consulta usa LIMIT sem OFFSET. Use per_page para ampliar o resultado (máx. 100). Ver a seção Paginação.
per_page opcional
query
integer
100
Itens por página. Limitado a 100 — valores maiores são reduzidos.
pagenão pagina aqui (ver seção Paginação). Use per_page até 100.
total e total_available são iguais a len(data) — refletem o lote devolvido, não a contagem total de correspondências na base. Para saber se há mais resultados, use has_more.
per_page na resposta é a quantidade efetivamente devolvida, que pode ser menor que a solicitada.
Aqui porte vem por extenso (MICRO, PEQUENO, GRANDE, NÃO INFORMADO) e as datas em DD/MM/AAAA — diferente de GET /cnpj.
GET/search/by-raiz
Listar estabelecimentos de uma raiz de CNPJ
Retorna matriz e filiais que compartilham a mesma raiz de 8 caracteres — a forma de mapear toda a rede de um grupo empresarial.
1 crédito a cada 10 resultados
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
raiz obrigatório
query
string
—
Raiz do CNPJ: exatamente 8 caracteres alfanuméricos. Um CNPJ completo de 14 caracteres é rejeitado — envie apenas os 8 primeiros.
apenas_ativas opcional
query
boolean
false
Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page opcional
query
integer
1
Aceito e ecoado na resposta, mas SEM EFEITO neste endpoint — a consulta usa LIMIT sem OFFSET. Use per_page para ampliar o resultado (máx. 100). Ver a seção Paginação.
per_page opcional
query
integer
100
Itens por página. Limitado a 100 — valores maiores são reduzidos.
Diferente de by-name, aqui total_availableé a contagem real de estabelecimentos da raiz.
has_more compara com o valor fixo 100, não com o per_page enviado.
GET/search/by-socio
Buscar sócios por nome
Localiza pessoas físicas ou jurídicas no quadro societário e informa em quantas empresas cada uma aparece. Use o par nome + doc do resultado para abrir a lista de empresas em /search/socio/empresas.
1 crédito a cada 10 resultados
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
nome obrigatório
query
string
—
Nome do sócio. Mínimo 3 e máximo 200 caracteres. Espaços viram curingas: Maria Silva busca %MARIA%SILVA%.
apenas_ativas opcional
query
boolean
false
Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page opcional
query
integer
1
Página dos resultados. Aplicada via OFFSET neste endpoint.
per_page opcional
query
integer
100
Itens por página. Limitado a 100 — valores maiores são reduzidos.
Este endpoint pagina de verdade — page aplica OFFSET.
O conjunto de candidatos é limitado a 5.000 registros antes do agrupamento; quando esse teto é atingido a resposta traz truncated: true. Refine o nome para reduzir o conjunto.
Proteção de dados: para pessoa física (tipo_socio: 2), doc_display vem mascarado como ***4567****. O campo doc mantém os dígitos mascarados publicados pela Receita e é o que deve ser reenviado no drill-down.
GET/search/socio/empresas
Listar empresas de um sócio
Detalha as empresas ligadas a um sócio específico. Os valores de nome e doc devem vir exatamente como retornados por /search/by-socio — a correspondência é exata.
1 crédito a cada 10 resultados
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
nome obrigatório
query
string
—
Nome exato do sócio (máx. 250 caracteres).
doc opcional
query
string
""
Documento mascarado, exatamente como veio no campo doc de /search/by-socio (máx. 20 caracteres).
cod_pais opcional
query
integer
—
Código do país para desambiguar sócios estrangeiros. Precisa ser numérico.
apenas_ativas opcional
query
boolean
false
Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page opcional
query
integer
1
Página dos resultados. Aplicada via OFFSET neste endpoint.
per_page opcional
query
integer
100
Itens por página. Limitado a 100 — valores maiores são reduzidos.
{
"success": true,
"data": [
{
"cnpj": "00000000000191",
"cnpj_formatado": "00.000.000/0001-91",
"razao_social": "BANCO DO BRASIL SA",
"nome_fantasia": "DIRECAO GERAL",
"situacao": "02",
"data_abertura": "19660801",
"logradouro": "SAUN QUADRA 5 LOTE B TORRES I, II E III",
"numero": "SN",
"complemento": "ANDAR 1 A 16 TORRE I,II,III",
"bairro": "ASA NORTE",
"municipio": "BRASILIA",
"uf": "DF",
"cep": "70040912",
"telefone": "(61) 3493-9002",
"email": "[email protected]",
"atividade_principal": "Bancos multiplos, com carteira comercial",
"optante_simples": "N",
"found": true
},
{
"cnpj": "99999999999999",
"cnpj_formatado": "99.999.999/9999-99",
"found": false,
"error": "CNPJ não encontrado"
}
],
"total": 2,
"found": 1,
"not_found": 1,
"timestamp": "2026-08-28T14:03:11.482913"
}
Erros possíveis
Status
Situação
400
Arquivo ausente ou inválido
400
Lote acima do limite
403
Recurso exige conta
401
Chave inválida ou revogada
402
Saldo de créditos não cobre a chamada
429
Limite de chamadas por minuto
500
Erro interno
Notas
Custo sobre o total: o lote é cobrado em créditos pelo número de CNPJs válidos do arquivo, com a regra "1 crédito a cada N CNPJs" aplicada uma vez ao total (veja a tabela de custos).
Linhas que não resultem em exatamente 14 caracteres são descartadas em silêncio antes da contagem — elas não aparecem na resposta nem contam para o limite de 1.000.
Cada item traz found. Quando false, vêm apenas cnpj, cnpj_formatado, found e error.
data_abertura volta crua (AAAAMMDD), enquanto telefone já vem formatado — ou null se o DDD/número for inválido.
Comparado a GET /cnpj, o bulk não devolve socios, capital_social, porte, natureza_juridica, cnae_principal, codigo_municipio, tipo_logradouro nem os campos de MEI.
GET/municipios
Listar municípios com empresa ativa
Devolve todos os municípios do país que têm estabelecimento na base, com o código da Receita, a UF e o identificador usado nas demais rotas de município. A resposta é estável e cacheável por um dia — baixe uma vez e filtre do seu lado.
codmun é o código de município da Receita Federal, não o do IBGE.
slug é estável: uma vez publicado, não muda em recargas posteriores.
Depende da carga do ranking por município; antes dela a rota responde 503.
GET/municipios/{municipio}/empresas
Maiores empresas de um município
Ranking das maiores empresas de grande porte do município, por um índice que pesa 70% o número de estabelecimentos ativos no Brasil inteiro e 30% o capital social, ambos em escala logarítmica. O agrupamento é por raiz de CNPJ: matriz e filiais contam como uma empresa só. Há duas visões: visao=matriz lista só as empresas sediadas na cidade (matriz ativa lá); visao=presenca lista toda empresa com ao menos uma unidade ativa na cidade, mesmo com a matriz em outro município — e aí matriz_na_cidade vem false e matriz_municipio diz onde ela fica. Empresas com registro ativo na CVM vêm com capital_aberto: true.
1 crédito a cada 10 resultados
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
municipio obrigatório
path
string
—
O slug ou o codmun devolvidos por GET /municipios.
visao opcional
query
string
—
matriz (sediadas na cidade) ou presenca (qualquer unidade ativa na cidade). Padrão: presenca.
limite opcional
query
integer
—
Quantas empresas devolver, de 1 a 200 (padrão 200). Valores maiores são reduzidos a 200.
O teto de 200 é o tamanho do ranking materializado: não há página 2.
unidades_ativas conta o Brasil inteiro; unidades_cidade só o município.
capital_social é da empresa (raiz), em reais.
Só entram entidades empresariais (natureza jurídica 2xxx) de grande porte (porte 05): órgãos públicos, associações, igrejas, fundações e empresários individuais ficam fora, assim como CNPJs com remoção de dados concluída.
indice vai de 0 a 100: 70% ln(1+unidades)/ln(1+máximo do país) + 30% o mesmo para o capital social. Capital acima de R$ 10 bi em empresa de até 2 unidades não entra no índice (indício de erro de cadastro), mas continua em capital_social.
capital_aberto reflete o cadastro da CVM no momento da consulta; dfs_slug, quando presente, é o endereço da página de Balanços em /demonstracoes-financeiras/{dfs_slug}.
O ranking é recalculado a cada carga da Receita Federal; gerado_em diz quando foi a última vez.
Demonstrações Financeiras
Balanços de companhias abertas brasileiras a partir dos dados públicos da CVM (DFP anual e ITR trimestral). Todos os valores monetários estão em MIL R$.
GET/cvm/search
Autocompletar companhias abertas
Busca rápida por nome ou código CVM, limitada a 15 resultados. Feita para caixas de autocompletar.
1 crédito por consulta
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
q obrigatório
query
string
—
Termo de busca (nome ou código CVM). Vazio devolve [].
Responde um array puro, sem o envelope {success, data} usado nos endpoints de CNPJ.
Só retorna companhias que já possuem KPIs carregados.
GET/cvm/by-cnpj/{cnpj}
Descobrir o código CVM a partir do CNPJ
Ponte entre os dois domínios: informe um CNPJ e descubra se aquela empresa tem demonstrações financeiras publicadas, recebendo o cd_cvm para as demais chamadas.
1 crédito por consulta
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
cnpj obrigatório
path
string
—
CNPJ completo (14) ou apenas a raiz (8). A pontuação é ignorada nos dois lados da comparação.
Valores em MIL R$. O ano é escolhido automaticamente (exercício anual mais recente com KPIs carregados).
GET/cvm/empresa/{cd_cvm}
Demonstrações completas de uma companhia
Retorna cadastro, períodos disponíveis, indicadores do período e do anterior, e todos os quadros já preenchidos (DRE, BPA, BPP, DFC, DVA, DMPL, DRA) em uma só chamada.
1 crédito por consulta
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
cd_cvm obrigatório
path
string
—
Código CVM de 6 dígitos. Valores mais curtos são completados com zeros à esquerda.
origem opcional
query
string
DFP
DFP para o anual, ITR para o trimestral. Se não houver dados na origem pedida, a API tenta a outra automaticamente e informa qual usou no campo origem da resposta.
ano opcional
query
integer
—
Ano do exercício. Padrão: o mais recente disponível.
dt_refer opcional
query
string
—
Data de referência (AAAA-MM-DD). Ignorada se não estiver na lista dts.
Resposta pesada: quadros_data traz todas as linhas de todos os quadros. Para um quadro só, use /cvm/empresa/{cd_cvm}/quadro/{quadro}.
Cada linha tem ind_* (individual) e con_* (consolidado), nos exercícios ultimo e penultimo, com var_ind/var_con em % — null quando o período anterior é zero ou ausente.
nivel é a profundidade da conta no plano de contas, derivada da quantidade de pontos em cd_conta (3.01 → nível 1).
GET/cvm/empresa/{cd_cvm}/quadro/{quadro}
Um único quadro contábil
Versão enxuta do endpoint anterior: devolve apenas as linhas do quadro pedido.
1 crédito por consulta
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
cd_cvm obrigatório
path
string
—
Código CVM de 6 dígitos.
quadro obrigatório
path
string
—
DRE (resultado), BPA (ativo), BPP (passivo), DFC_MI/DFC_MD (fluxo de caixa), DVA (valor adicionado), DMPL (mutações do PL), DRA (resultado abrangente).
Códigos CVM inexistentes são silenciosamente omitidos de dados — compare o tamanho do array com o que você enviou.
GET/cvm/empresas
Listar e filtrar companhias abertas
Catálogo paginado com filtros por setor, UF e município, ordenável por qualquer indicador. Retorna também as facetas para montar filtros na sua interface.
1 crédito por consulta
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
page opcional
query
integer
1
Página. Pagina de verdade (OFFSET).
q opcional
query
string
—
Termo livre (nome ou CNPJ).
setor opcional
query
string
—
Setor exato, como listado em facets.setores.
uf opcional
query
string
—
UF de 2 letras.
municipio opcional
query
string
—
Município exato. As opções só aparecem em facets.municipios quando uf é informada.
order_by opcional
query
string
lucro_liquido
Campo de ordenação. Valor inválido volta ao padrão.
Os números do modelo de créditos: o custo de cada ação, os pacotes de assinatura (créditos por mês, preço mensal e anual, limite por minuto) e as regras (créditos grátis do mês, avulso, validade). A página de preços do site lê exatamente daqui.
Custo de uma ação = teto(quantidade ÷ por_unidades) × creditos.
CNPJ Alfanumérico
Gerador, validador e calculadora de dígito verificador do novo CNPJ alfanumérico (Receita Federal, vigência 2026). Gratuito e sem chave — atenção: roda em www.cnpgolden.com.br e usa um envelope de resposta diferente.
GET/cnpj-alfa/gerar
Gerar CNPJs alfanuméricos fictícios
Gera CNPJs no novo formato alfanumérico com dígito verificador correto, para testar seus sistemas antes da vigência de 2026. Os números são fictícios e não correspondem a empresas reais.
Sem chaveHost: www.cnpgolden.com.br
Parâmetros
Nome
Em
Tipo
Padrão
Descrição
quantidade opcional
query
integer
1
Quantos gerar, de 1 a 100.
raiz opcional
query
string
—
Fixa os 8 primeiros caracteres.
estabelecimento opcional
query
string
—
Fixa os 4 caracteres do estabelecimento (ex.: 0001).
com_razao_social opcional
query
boolean
false
Quando verdadeiro, cada item vira um objeto com razão social fictícia; caso contrário cnpjs é uma lista de strings.
Servido por www.cnpgolden.com.br, não por api.cnpgolden.com.br.
Envelope diferente: sucesso/erro, e não success/error.
POST/cnpj-alfa/validar
Validar CNPJs alfanuméricos
Confere o dígito verificador de um ou vários CNPJs. O algoritmo é um superconjunto estrito do numérico: CNPJs antigos são validados exatamente como antes.
Envelope sucesso/erro. Servido por www.cnpgolden.com.br.
Dicionário de campos
Alguns campos vêm com os códigos originais da Receita Federal. As
tabelas abaixo traduzem os mais usados.
Situação cadastral (situacao)
Código
Significado
01
Nula
02
Ativa
03
Suspensa
04
Inapta
08
Baixada
Porte da empresa (porte)
Código
Significado
00
Não informado
01
Micro empresa
03
Empresa de pequeno porte
05
Empresa de grande porte (demais)
Tipo de sócio (tipo_socio)
Código
Significado
1
Pessoa jurídica
2
Pessoa física
3
Estrangeiro
O formato varia entre endpoints — isso é intencional e
documentado. Em GET /cnpj,
situacao e porte vêm como código bruto e as
datas como AAAAMMDD. Nos endpoints de busca, o porte vem
por extenso e as datas em DD/MM/AAAA. Em
/search/bulk, data_abertura volta crua mas
telefone já vem formatado. Confira a seção do endpoint
que você usa.
Valores monetários
Em GET /cnpj, capital_social está em reais.
Nos endpoints de demonstrações financeiras, todos os valores
estão em MIL R$ — um lucro_liquido de
35600000 significa R$ 35,6 bilhões.
Perguntas frequentes
Como consultar um CNPJ via API?
Faça um GET para https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=…
com sua chave no header X-API-Key. A resposta traz o
cadastro completo em JSON. Sem chave, o mesmo endpoint responde até
10 vezes por IP por dia.
Existe uma API de CNPJ gratuita?
Sim. A conta é gratuita, sem cartão de crédito, e recebe
70 créditos por mês com o e-mail confirmado
(1 crédito por consulta de CNPJ).
De onde vêm os dados?
Dos arquivos de dados abertos do CNPJ publicados pela Receita Federal
do Brasil, cobrindo todos os estabelecimentos ativos e inativos. A
carga é atualizada mensalmente;
GET /database/last-update informa a data do arquivo em uso.
A API suporta o CNPJ alfanumérico de 2026?
Sim, em todos os endpoints. Veja a
seção de formato para a armadilha mais
comum na hora de limpar a entrada.
Como consultar vários CNPJs de uma vez?
Com POST /search/bulk:
um arquivo .txt, um CNPJ por linha, até 1.000 por
requisição, cobrado em créditos sobre o total do arquivo.
Existe spec OpenAPI ou coleção do Postman?
A spec OpenAPI 3.1 está em
/openapi.json
e importa direto no Postman, Insomnia ou geradores de SDK. Há também
um espelho em Markdown em
/api-docs.md.
Posso usar a chave no frontend?
Não. A chave gasta os seus créditos — chame a API
a partir do seu servidor e exponha só o que sua aplicação precisa.
A versão vive no caminho da URL. Enquanto /api/v1 existir,
nenhum campo será removido ou renomeado.
Compatível (pode acontecer a qualquer momento):
novos campos nas respostas, novos endpoints, novos parâmetros
opcionais. Seu parser deve ignorar o que não conhece.
Incompatível (só em uma /api/v2):
remoção ou renomeação de campos, mudança de tipo, mudança no
significado de um código.
A base da Receita Federal é recarregada mensalmente. Durante a recarga,
consultas continuam respondendo com os dados do ciclo anterior.
Comece com 1.500 consultas por mês
Plano gratuito, sem cartão de crédito. Gere sua chave e faça a primeira
requisição em menos de cinco minutos.