Consulta de CNPJ por Lote

Envía una lista de hasta 10.000 CNPJ y recibe, para cada uno, el mismo registro de la Consulta de CNPJ, procesado en segundo plano. Cuesta 1 crédito por CNPJ encontrado.

Sin código, el dashboard acepta una lista de CNPJ y muestra el resultado de cada uno.

Flujo en dos pasos:

1. POST /cnpj/bulk envía la lista y responde al instante con un jobId.
2. GET /cnpj/bulk/{jobId} devuelve el progreso y los resultados. Repite hasta que status sea "done" o "failed".

Endpoint

Parámetros

Qué pasa en el envío

Más de 10.000 CNPJ: divídelos en bloques y envía un POST por cada uno, esperando a los anteriores si recibes 429.

Ejemplo

Revisa el status antes de leer data: en caso de error, la respuesta no trae jobId.

curl -X POST "https://api.cpfhub.io/cnpj/bulk" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cnpjs": ["11222333000181", "12.ABC.345/01DE-35"]
  }'

Respuesta

HTTP 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "processing",
    "totalRecords": 2,
    "invalid": 0
  }
}

El envío responde en camelCase. El status responde en snake_case.

Status y resultados

Usa la misma API Key del envío. No consume crédito y funciona con saldo cero.

Polling:

• Empieza cada 5 s y aumenta hasta 30 s en lotes grandes. Cada llamada devuelve el array cnpjs completo, y cada registro de CNPJ es bastante mayor que el de un CPF.
• Define un plazo máximo en el cliente (ej.: 30 min). El tiempo del lote depende de cuántos CNPJ hay en el envío.
• Ante 5xx o un error de red, vuelve a intentar en el siguiente ciclo. El GET es seguro de repetir.

curl "https://api.cpfhub.io/cnpj/bulk/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "x-api-key: $CPFHUB_API_KEY"

HTTP 200 OK

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "done",
    "file_name": null,
    "format": null,
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "created_at": "2026-10-15T14:15:16.000Z",
    "updated_at": "2026-10-15T14:15:18.000Z",
    "cnpjs": [
      {
        "cnpj": "11222333000181",
        "found": true,
        "data": {
          "cnpj": "11222333000181",
          "razao_social": "EMPRESA EXEMPLO LTDA",
          "situacao_cadastral": "Ativa",
          "...": "demás campos de la Consulta de CNPJ"
        }
      },
      {
        "cnpj": "12ABC34501DE35",
        "found": false,
        "data": null
      }
    ]
  }
}

Durante "processing", los contadores se actualizan por intervalos y pueden ir por detrás de cnpjs.

Errores

La API responde solo en portugués. Los mensajes de error aparecen tal como llegan.

Formato del error y reintentos: Códigos de Error. Límite por minuto y créditos: Límites de Uso.

Detalles

Estados del lote

Con excedente, ningún CNPJ se omite: todos se consultan y el excedente se cobra.

Cruzar los resultados con tu lista

cnpjs no sigue el orden del envío y no incluye skipped ni los no procesados. Normaliza tu lista (sin puntos, barra ni guion, en mayúsculas) y cruza por el campo cnpj. Los que falten son los que debes reenviar (incluye los inválidos, que no cuestan nada).

const normalize = (cnpj: string) => cnpj.replace(/[./-]/g, '').toUpperCase()

const results = new Map(job.cnpjs.map((item) => [item.cnpj, item]))

for (const original of myCnpjs) {
  const result = results.get(normalize(original))
  console.log(original, result ? (result.found ? result.data.razao_social : 'no encontrado') : 'sin resultado')
}

// CNPJ para reenviar en un nuevo lote (si el lote falló o tuvo skipped)
const missing = [...new Set(myCnpjs.map(normalize))].filter((cnpj) => !results.has(cnpj))

Más

• Envío no idempotente: cada POST aceptado crea un lote nuevo y cobra los encontrados. Si la conexión se cae sin jobId, revisa el dashboard o GET /quota antes de reenviar. Con respuesta de error, no se creó ningún lote.
• Crédito: solo se cobra found: true, al mismo costo y de la misma franquicia que la Consulta Simple de CPF. Inválidos, repetidos, no encontrados y skipped no se cobran.
• Fuente de los datos: la misma de la Consulta de CNPJ: base pública mensual de la Receita Federal, procesada por OpenCNPJ. Los datos pueden estar desactualizados hasta la próxima actualización mensual.
• Datos de ejemplo: los CNPJ y los datos anteriores son ficticios.

Actualizado el 15 de octubre de 2026