API de Empresas (CNPJ)

Integre a API da CNPJ Data usando autenticação via X-API-Key.

Esta documentação é voltada para integrações autenticadas e uso de créditos de API. Para uma consulta individual gratuita, sem login, utilize a Consulta Pública de CNPJ.

Passo 1 — Comprar créditos

Acesse o painel da CNPJ Data, vá até a seção API e adquira créditos de API.

Passo 2 — Gerar chave de API

No painel autenticado, na aba Minha API, gere sua chave e envie-a no header X-API-Key.

X-API-Key: <id>.<secret>

O header X-API-Key é permitido pelo CORS, então a API pode ser chamada diretamente do browser, sem proxy server-side.

Consulta pública por CNPJ — sem chave de API

GET/api/public/companies/{cnpj}

Endpoint aberto para consultar uma empresa por CNPJ sem autenticação e sem consumo de créditos. Ideal para testes, validações pontuais e protótipos.

curl -X GET \
  "https://api.cnpjdata.com.br/api/public/companies/33000167000101"

Resposta 200 (exemplo):

{
  "cnpjCompleto": "33.000.167/0001-01",
  "razaoSocial": "PETROLEO BRASILEIRO S A PETROBRAS",
  "nomeFantasia": "PETROBRAS - EDISE",
  "situacaoCadastralRef": { "codigo": "02", "descricao": "Ativa" },
  "cnaeRef": { "codigo": "0600001", "descricao": "Extração De Petróleo E Gás Natural" },
  "municipioRef": { "codigo": "6001", "descricao": "Rio De Janeiro" },
  "uf": "RJ",
  "telefone1": "2121660000",
  "dataInicioAtividade": "1966-09-28T00:00:00.000Z",
  "socios": [
    { "nomeSocio": "A******* G***** C**** L*******", "cnpjCpfSocio": "***91******", "entrada": "29/07/2025", "descricaoQualificacao": "Diretor" }
  ]
}

Não envie o header X-API-Key: esta rota é pública e não consome créditos. Os campos de identificação dos sócios vêm mascarados; para dados completos, consultas em lista e filtros avançados, utilize os endpoints autenticados abaixo.

CNPJ malformado ou com dígitos verificadores inválidos: 400 com code "CNPJ_INVALID". CNPJ válido, mas inexistente na base: 404 com code "CNPJ_NOT_FOUND".

Consultar uma empresa por CNPJ

GET/api/companies/{cnpj}

curl -X GET "https://api.cnpjdata.com.br/api/companies/01234567000189" \
  -H "X-API-Key: <id>.<secret>"

Envie o CNPJ sem máscara, apenas números. Cobrança: 1 crédito.

A API paga também retorna a lista de sócios e os dados disponíveis para o acesso autenticado. Na consulta pública, os campos de identificação dos sócios são mascarados.

Exemplo na consulta pública (dados mascarados):

{
  "socios": [
    {
      "nomeSocio": "S***** M****** A****",
      "cnpjCpfSocio": "***00******",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Exemplo na API paga (dados disponíveis):

{
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Resposta 200 (exemplo):

{
  "searchId": "uuid-da-busca",
  "creditsCharged": 1,
  "creditsBalance": 919,
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "situacaoCadastralCodigo": "02",
  "uf": "SP"
}

Toda resposta de consulta bem-sucedida inclui creditsCharged (créditos debitados naquela requisição) e creditsBalance (saldo restante após o débito; 0 quando nada é debitado). Use esses campos para exibir custo e saldo em tempo real, sem precisar consultar /credits/balance.

A resposta completa inclui os demais dados cadastrais disponíveis.

Ver resposta completa

{
  "searchId": "uuid-da-busca",
    "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Consultar duas ou mais empresas por lista de CNPJs

POST/api/companies/list

curl -X POST "https://api.cnpjdata.com.br/api/companies/list" \
  -H "X-API-Key: <id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["01234567000189","00987654000110"],"page":1,"limit":20}'

Exportação completa da lista:

curl -X POST "https://api.cnpjdata.com.br/api/companies/list" \
  -H "X-API-Key: <id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["02204106000132","19131243000197"],"export":true}'

Resposta 200 (exemplo):

{
  "searchId": null,
  "data": [{ "cnpjCompleto": "01.234.567/0001-89", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 2,
  "totalPages": 1,
  "creditsCharged": 2,
  "creditsBalance": 918
}

Sem page, a consulta equivale a page=1 e debita apenas os registros retornados. Para gerar um arquivo com todos os registros, envie "export": true no body: nesse caso o total é debitado e o arquivo fica associado ao searchId.

O campo cnpjs é obrigatório e não pode ser vazio (400 "CNPJS_REQUIRED"). Todos os CNPJs são validados, incluindo os dígitos verificadores; qualquer CNPJ inválido rejeita a requisição inteira com 400 "CNPJ_INVALID".

Resposta com export=true (igual ao export síncrono dos filtros; creditsCharged = total da lista):

{
  "searchId": "uuid-da-busca",
  "data": [{ "cnpjCompleto": "02.204.106/0001-32", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 2,
  "totalPages": 1,
  "creditsCharged": 2,
  "creditsBalance": 916
}

Exemplos de erro de validação:

{ "code": "CNPJS_REQUIRED", "message": "Envie uma lista de CNPJs não vazia." }

{ "code": "CNPJ_INVALID", "message": "2 CNPJ(s) inválido(s) na lista. Corrija e reenvie.",
  "invalidCnpjs": ["11111111111111", "123"], "invalidCount": 2 }

Ver modelo completo de uma empresa

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Ver quantidade de empresas antes da consulta por filtros

Antes de realizar uma consulta massiva por filtros, verifique quantas empresas correspondem aos critérios selecionados. Assim, você avalia o volume antes de solicitar os dados.

GET/api/companies/count

curl -X GET "https://api.cnpjdata.com.br/api/companies/count?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicio=2016" \
  -H "X-API-Key: <id>.<secret>"

Resposta 200:

{ "count": 123456 }

page e limit não são utilizados. Essa rota não retorna empresas, não gera searchId e não consome créditos.

Exemplos de filtros

Os filtros podem ser combinados na URL. Parâmetros aceitos: uf, codMunicipio, cidadeNome, cnae, porte, status, anoInicio, anoInicioMin e anoInicioMax.

Localização e período

Use uf=SP e cidadeNome=Campinas para filtrar por localização. Para um ano específico, use anoInicio=2016. Para um intervalo, use anoInicioMin=2015&anoInicioMax=2020.

CNAE

Informe o código CNAE completo, apenas com números. Não use pontos, hífen ou barra. Exemplo: cnae=6201500.

Situação

Informe o código no parâmetro status. Exemplo: status=02 para empresas ativas.

Porte da empresa

Código	Descrição
00	Não Informado
01	Micro Empresa
03	Empresa De Pequeno Porte
05	Demais

Situação cadastral

Código	Descrição
01	Nula
02	Ativa
03	Suspensa
04	Inapta
08	Baixada

Buscar por filtros — exportação completa

GET/api/companies

Envie export=true para gerar um arquivo com todos os registros encontrados. Sem export=true, a consulta é sempre paginada (sem page, equivale a page=1), não gera arquivo e não aparece em Minhas consultas.

curl -X GET "https://api.cnpjdata.com.br/api/companies?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicio=2016&export=true" \
  -H "X-API-Key: <id>.<secret>"

Com export=true, o parâmetro page é ignorado.

Resposta 200 (estrutura resumida):

{
  "searchId": "uuid-da-busca",
  "data": [{ "cnpjCompleto": "01.234.567/0001-89", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 58,
  "totalPages": 3,
  "creditsCharged": 58,
  "creditsBalance": 861
}

Até 10.000 registros: o export é síncrono. A resposta traz uma amostra dos registros em data (respeitando limit) e o arquivo completo já está disponível para download pelo searchId. O débito é o total de registros.

Acima de 10.000 registros: o arquivo é gerado de forma assíncrona. A resposta vem com "status": "processing" e data vazia, os créditos do total são debitados na hora e o arquivo fica disponível pelo searchId assim que o processamento concluir (normalmente em poucos minutos, proporcional ao volume).

Resposta quando a exportação é assíncrona (acima de 10.000 registros):

{
  "searchId": "uuid-da-busca",
  "status": "processing",
  "data": [],
  "page": 1,
  "limit": 20,
  "total": 123456,
  "totalPages": 6173,
  "creditsCharged": 123456,
  "creditsBalance": 0
}

A resposta completa contém os dados cadastrais disponíveis. Cobrança: total de registros encontrados; o arquivo é associado ao searchId.

Ver modelo completo de uma empresa

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Acompanhar uma exportação assíncrona

Após uma exportação assíncrona, acompanhe o processamento pelo searchId:

GET/api/companies/exports/{searchId}/status

curl -X GET "https://api.cnpjdata.com.br/api/companies/exports/<searchId>/status" \
  -H "X-API-Key: <id>.<secret>"

Resposta 200 (exemplo):

{
  "searchId": "uuid-da-busca",
  "status": "processing",
  "total": 123456,
  "error": null,
  "createdAt": "2026-08-31T14:30:00.000Z"
}

Recomendamos verificar o status a cada 5 a 10 segundos enquanto estiver "processing".

Status	Significado
processing	Arquivo sendo gerado
ready	Pronto para download
failed	Falhou no processamento; os créditos debitados são estornados automaticamente

Baixar o arquivo do resultado via API

Quando o status estiver "ready", baixe o arquivo pelo searchId. A rota é autenticada por X-API-Key e fecha o ciclo 100% programático: export → polling de status → download.

GET/api/companies/exports/{searchId}/download

curl -X GET "https://api.cnpjdata.com.br/api/companies/exports/<searchId>/download" \
  -H "X-API-Key: <id>.<secret>"

Resposta 200 (exemplo):

{
  "url": "https://bucket.s3.amazonaws.com/api-search/uuid-da-busca.json?X-Amz-Signature=...",
  "expiresAt": "2026-09-29T22:32:00.000Z",
  "remainingDownloads": 4
}

O link retornado em url vale por 2 minutos — baixe logo em seguida. O campo remainingDownloads indica quantos downloads restam hoje para este resultado (de 5).

Erros possíveis: 404 "NOT_FOUND" (resultado de busca não encontrado), 400 "BAD_REQUEST" (consulta ainda em processamento) e 400 "BAD_REQUEST" (limite diário de 5 downloads para este resultado atingido).

Buscar por filtros — paginação com page

GET/api/companies

Envie page e limit para consultar apenas uma página. Sem page, a consulta equivale a page=1.

O parâmetro limit aceita de 1 a 100: valores acima de 100 retornam 400 "LIMIT_EXCEEDED" (sem truncamento silencioso). page inválido (0, negativo ou não inteiro) retorna 400 "INVALID_PAGE".

curl -X GET "https://api.cnpjdata.com.br/api/companies?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicioMin=2015&anoInicioMax=2020&page=2&limit=20" \
  -H "X-API-Key: <id>.<secret>"

Resposta 200 (estrutura resumida):

{
  "searchId": null,
  "data": [{ "cnpjCompleto": "12.345.678/0001-99", "uf": "SP" }],
  "page": 2,
  "limit": 20,
  "total": 58,
  "totalPages": 3,
  "creditsCharged": 20,
  "creditsBalance": 919
}

Cobrança: apenas a quantidade de registros retornados na página. Consultas paginadas retornam "searchId": null, não geram arquivo e não aparecem em Minhas consultas.

Precisa de todos os registros de um filtro? Use export=true: mesmo custo de paginar tudo, mas com arquivo completo, e-mail de aviso e modo assíncrono acima de 10k. A paginação é para navegar e amostrar.

Ver modelo completo de uma empresa

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Baixar o arquivo do resultado

Acesse o painel autenticado, vá em Minhas consultas de API, localize a consulta pelo label e clique em Baixar — ou use a rota de download via API acima.

O link é válido por 2 minutos e cada resultado pode ser baixado até 5 vezes por dia (painel e API compartilham o mesmo limite).

Consultas ainda em processing ficam disponíveis para download assim que o status mudar para ready.

A listagem no painel mostra o status e o total de registros de cada consulta. Só aparecem lá: consulta individual por CNPJ, exports (síncronos e assíncronos) e listas em modo export — consultas paginadas não geram histórico.

Erros e códigos de resposta

Toda resposta de erro usa o envelope { "code": "...", "message": "..." }. Faça o switch pelo campo code; message é texto legível para exibição. Algumas validações incluem campos extras além do envelope (ex.: invalidCnpjs e invalidCount em CNPJ_INVALID de listas) — trate code como principal e os extras como contexto.

HTTP	Código	Quando ocorre
400	CNPJ_INVALID	CNPJ malformado ou com dígitos verificadores inválidos (inclui a rota pública)
404	CNPJ_NOT_FOUND	CNPJ válido, mas inexistente na base
400	CNPJS_REQUIRED	Lista de CNPJs vazia ou ausente no POST /companies/list
400	INVALID_PAGE · INVALID_LIMIT · LIMIT_EXCEEDED	Paginação inválida (INVALID_PAGE, INVALID_LIMIT ou LIMIT_EXCEEDED)
400	API_CREDITS_INSUFFICIENT	Saldo de créditos insuficiente
401	API_KEY_*	Problemas na chave de API (ausente, inválida etc.)
429	RATE_LIMITED	Rate limit excedido