Consulta de CNPJ em Lote

Envie uma lista de até 10.000 CNPJs e receba, para cada um, o mesmo registro da Consulta de CNPJ, processado em segundo plano. Custa 1 crédito por CNPJ encontrado.

Sem código, o dashboard aceita uma lista de CNPJs e mostra o resultado de cada um.

Fluxo em dois passos:

1. POST /cnpj/bulk envia a lista e responde na hora com um jobId.
2. GET /cnpj/bulk/{jobId} devolve o progresso e os resultados. Repita até status ser "done" ou "failed".

Endpoint

Parâmetros

O que acontece no envio

Mais de 10.000 CNPJs: divida em blocos e envie um POST para cada um, aguardando os anteriores se receber 429.

Exemplo

Confira o status antes de ler data: em erro, a resposta não traz 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"]
  }'

Resposta

HTTP 202 Accepted

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

O envio responde em camelCase. O status responde em snake_case.

Status e resultados

Use a mesma API Key do envio. Não consome crédito e funciona com saldo zerado.

Polling:

• Comece a cada 5 s e aumente até 30 s em lotes grandes. Cada chamada devolve o array cnpjs inteiro, e cada registro de CNPJ é bem maior que o de um CPF.
• Defina um prazo máximo no cliente (ex.: 30 min). O tempo do lote depende de quantos CNPJs estão no envio.
• Em 5xx ou erro de rede, tente de novo no próximo ciclo. O GET é seguro para 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",
          "...": "demais campos da Consulta de CNPJ"
        }
      },
      {
        "cnpj": "12ABC34501DE35",
        "found": false,
        "data": null
      }
    ]
  }
}

Durante "processing", os contadores atualizam em intervalos e podem ficar atrás de cnpjs.

Erros

Formato do erro e retentativas: Códigos de Erro. Limite por minuto e créditos: Limites de Uso.

Detalhes

Estados do lote

Com overage, nenhum CNPJ é pulado: todos são consultados e o excedente é cobrado.

Casando os resultados com a sua lista

cnpjs não segue a ordem do envio e não inclui skipped nem não processados. Normalize sua lista (sem pontos, barra e traço, em maiúsculas) e case pelo campo cnpj. Os que faltarem são os que reenviar (inclui inválidos, que não custam 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 : 'não encontrado') : 'sem resultado')
}

// CNPJs para reenviar em um novo lote (se o lote falhou ou teve skipped)
const missing = [...new Set(myCnpjs.map(normalize))].filter((cnpj) => !results.has(cnpj))

Mais

• Envio não idempotente: cada POST aceito cria um lote novo e cobra os encontrados. Se a conexão cair sem jobId, confira o dashboard ou GET /quota antes de reenviar. Com resposta de erro, nenhum lote foi criado.
• Crédito: só found: true é cobrado, no mesmo custo e na mesma franquia da Consulta Simples de CPF. Inválidos, repetidos, não encontrados e skipped não.
• Fonte dos dados: a mesma da Consulta de CNPJ: base pública mensal da Receita Federal, tratada pelo OpenCNPJ. Os dados podem estar defasados até a próxima atualização mensal.
• Dados de exemplo: os CNPJs e os dados acima são fictícios.

Atualizado em 15 de outubro de 2026