API de Empresas (CNPJ)

Integra la API de CNPJ Data mediante autenticación con X-API-Key.

Esta documentación está orientada a integraciones autenticadas y al uso de créditos de API. Para una consulta individual gratuita sin iniciar sesión, utiliza la Consulta Pública de CNPJ.

Paso 1 — Comprar créditos

Accede al panel de CNPJ Data, ve a la sección API y compra créditos de API.

Paso 2 — Generar una clave de API

En el panel autenticado, abre la pestaña Mi API, genera tu clave y envíala en el X-API-Key.

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

El header X-API-Key está permitido por CORS, por lo que la API puede llamarse directamente desde el navegador, sin proxy del lado del servidor.

Consulta pública de CNPJ — sin clave de API

GET/api/public/companies/{cnpj}

Endpoint abierto para consultar una empresa por CNPJ sin autenticación y sin consumir créditos. Ideal para pruebas, validaciones puntuales y prototipos.

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

Respuesta 200 (ejemplo):

{
  "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" }
  ]
}

No envíes el header X-API-Key: esta ruta es pública y no consume créditos. Los campos de identificación de los socios vienen enmascarados; para datos completos, consultas por lista y filtros avanzados, usa los endpoints autenticados de abajo.

CNPJ malformado o con dígitos verificadores inválidos: 400 con code "CNPJ_INVALID". CNPJ válido pero inexistente: 404 con code "CNPJ_NOT_FOUND".

Consultar una empresa por CNPJ

GET/api/companies/{cnpj}

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

Envía el CNPJ sin formato, solo con números. Coste: 1 crédito.

La API de pago también devuelve la lista de socios y los datos disponibles para el acceso autenticado. En la consulta pública, los campos de identificación de los socios están enmascarados.

Ejemplo en la consulta pública (datos enmascarados):

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

Ejemplo en la API de pago (datos disponibles):

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

Respuesta 200 (ejemplo):

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

Toda respuesta de consulta correcta incluye creditsCharged (créditos debitados en esa solicitud) y creditsBalance (saldo restante tras el débito; 0 cuando no se debita nada). Usa estos campos para mostrar coste y saldo en tiempo real, sin consultar /credits/balance.

La respuesta completa incluye los demás datos registrales disponibles.

Ver respuesta 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 dos o más empresas mediante una lista de CNPJ

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}'

Exportación completa de la 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}'

Respuesta 200 (ejemplo):

{
  "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
}

Sin page, la consulta equivale a page=1 y solo se cobran los registros devueltos. Para generar un archivo con todos los registros, envía "export": true en el body: en ese caso se cobra el total y el archivo se asocia al searchId.

El campo cnpjs es obligatorio y no puede estar vacío (400 "CNPJS_REQUIRED"). Todos los CNPJ se validan, incluidos los dígitos verificadores; cualquier CNPJ inválido rechaza la solicitud completa con 400 "CNPJ_INVALID".

Respuesta con export=true (igual que el export síncrono de filtros; creditsCharged = total de la 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
}

Ejemplos de error de validación:

{ "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 una 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 la cantidad de empresas antes de una consulta con filtros

Antes de realizar una consulta masiva con filtros, verifica cuántas empresas coinciden con los criterios seleccionados. Así puedes evaluar el volumen antes de solicitar los datos.

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>"

Respuesta 200:

{ "count": 123456 }

page y limit no se utilizan. Esta ruta no devuelve empresas, no genera un searchId y no consume créditos.

Ejemplos de filtros

Los filtros pueden combinarse en la URL. Parámetros aceptados: uf, codMunicipio, cidadeNome, cnae, porte, status, anoInicio, anoInicioMin e anoInicioMax.

Ubicación y período

Usa uf=SP y cidadeNome=Campinas para filtrar por ubicación. Para un año específico, usa anoInicio=2016. Para un intervalo, usa anoInicioMin=2015&anoInicioMax=2020.

CNAE

Indica el código CNAE completo usando solo números. No utilices puntos, guiones ni barras. Ejemplo: cnae=6201500.

Situación

Indica el código en el parámetro status. Ejemplo: status=02 para empresas activas.

Tamaño de la empresa

Código	Descripción
00	No informado
01	Microempresa
03	Pequeña empresa
05	Demás

Situación registral

Código	Descripción
01	Nula
02	Activa
03	Suspendida
04	Inapta
08	Dada de baja

Buscar por filtros — exportación completa

GET/api/companies

Envía export=true para generar un archivo con todos los registros encontrados. Sin export=true, la consulta siempre es paginada (sin page equivale a page=1), no genera archivo ni aparece en Mis 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>"

Con export=true, el parámetro page se ignora.

Respuesta 200 (estructura 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
}

Hasta 10.000 registros: el export es síncrono. La respuesta trae una muestra de los registros en data (respetando limit) y el archivo completo ya está disponible para descarga mediante el searchId. Se cobra el total de registros.

Más de 10.000 registros: el archivo se genera de forma asíncrona. La respuesta llega con "status": "processing" y data vacía, los créditos del total se debitan de inmediato y el archivo queda disponible mediante el searchId en cuanto finalice el procesamiento (normalmente en pocos minutos, proporcional al volumen).

Respuesta cuando la exportación es asíncrona (más de 10.000 registros):

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

La respuesta completa contiene los datos registrales disponibles. El cobro se basa en el total de registros encontrados; el archivo se asocia al searchId.

Ver modelo completo de una 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"
    }
  ]
}

Seguir una exportación asíncrona

Tras una exportación asíncrona, sigue el procesamiento mediante el 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>"

Respuesta 200 (ejemplo):

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

Recomendamos consultar el estado cada 5 a 10 segundos mientras esté "processing".

Estado	Significado
processing	Archivo en generación
ready	Listo para descarga
failed	Falló el procesamiento; los créditos debitados se reembolsan automáticamente

Descargar el archivo del resultado mediante la API

Cuando el estado sea "ready", descarga el archivo mediante el searchId. La ruta se autentica con X-API-Key y cierra el ciclo 100% programático: export → consulta de estado → descarga.

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>"

Respuesta 200 (ejemplo):

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

El enlace devuelto en url vale por 2 minutos: descárgalo justo después. El campo remainingDownloads indica cuántas descargas quedan hoy para este resultado (de 5).

Errores posibles: 404 "NOT_FOUND" (resultado de búsqueda no encontrado), 400 "BAD_REQUEST" (aún en procesamiento) y 400 "BAD_REQUEST" (límite diario de 5 descargas para este resultado alcanzado).

Buscar por filtros — paginación con page

GET/api/companies

Envía page y limit para consultar solo una página. Sin page, la consulta equivale a page=1.

El parámetro limit acepta de 1 a 100: valores superiores devuelven 400 "LIMIT_EXCEEDED" (sin truncamiento silencioso). Un page inválido (0, negativo o no entero) devuelve 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>"

Respuesta 200 (estructura resumida):

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

El cobro corresponde únicamente a la cantidad de registros devueltos en la página. Las consultas paginadas devuelven "searchId": null, no generan archivo ni aparecen en Mis consultas.

¿Necesitas todos los registros de un filtro? Usa export=true: mismo coste que paginar todo, pero con archivo completo, aviso por correo y modo asíncrono por encima de 10k. La paginación es para navegar y muestrear.

Ver modelo completo de una 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"
    }
  ]
}

Descargar el archivo del resultado

Accede al panel autenticado, ve a Mis consultas de API, localiza la consulta por su etiqueta y haz clic en Descargar — o usa la ruta de descarga de la API indicada arriba.

El enlace es válido durante 2 minutos y cada resultado puede descargarse hasta 5 veces al día (el panel y la API comparten el mismo límite).

Las consultas aún en processing quedan disponibles para descarga en cuanto el estado cambie a ready.

El listado del panel muestra el estado y el total de registros de cada consulta. Solo aparecen allí: consultas individuales por CNPJ, exports (síncronos y asíncronos) y listas en modo export — las consultas paginadas no generan historial.

Errores y códigos de respuesta

Toda respuesta de error usa el envelope { "code": "...", "message": "..." }. Haz el switch por el campo code; message es texto legible para mostrar. Algunas validaciones incluyen campos extra además del envelope (p. ej., invalidCnpjs e invalidCount en CNPJ_INVALID de listas): trata code como principal y los extras como contexto.

HTTP	Código	Cuándo ocurre
400	CNPJ_INVALID	CNPJ malformado o con dígitos verificadores inválidos (incluye la ruta pública)
404	CNPJ_NOT_FOUND	CNPJ válido, pero inexistente en la base
400	CNPJS_REQUIRED	Lista de CNPJ vacía o ausente en POST /companies/list
400	INVALID_PAGE · INVALID_LIMIT · LIMIT_EXCEEDED	Paginación inválida (INVALID_PAGE, INVALID_LIMIT o LIMIT_EXCEEDED)
400	API_CREDITS_INSUFFICIENT	Saldo de créditos insuficiente
401	API_KEY_*	Problemas con la clave de API (ausente, inválida, etc.)
429	RATE_LIMITED	Límite de solicitudes excedido