CPFHub.io
Começar grátis

Consultar CPF com Next.js

Consulte CPF com Next.js no servidor, com um Route Handler dinâmico do App Router. A API Key nunca chega ao navegador.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta Simples e cole no seu assistente.

Abrir no Cursor

Antes de começar

  1. Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
  2. Copie sua API Key em app.cpfhub.io/api-keys.
  3. Guarde a chave em uma variável de ambiente, nunca no código:
bash
export CPFHUB_API_KEY="sua_api_key"

Exemplo

TypeScript
// app/api/cpf/[cpf]/route.ts
export async function GET(
  _req: Request,
  { params }: { params: Promise<{ cpf: string }> },
) {
  const cpf = (await params).cpf.replace(/\D/g, '')
  if (cpf.length !== 11) {
    return Response.json({ error: 'CPF deve ter 11 dígitos' }, { status: 400 })
  }

  const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
    cache: 'no-store',
    signal: AbortSignal.timeout(10_000),
  })
  const body = await res.json()

  if (res.ok) return Response.json(body.data)
  if (res.status === 404) return Response.json({ error: 'CPF não encontrado' }, { status: 404 })
  if (res.status === 422) return Response.json({ error: 'CPF inválido' }, { status: 422 })

  // 401, 403, 429 e 5xx: problema de chave, créditos ou limite. Registre e não exponha ao cliente.
  console.error('CPFHub.io', res.status, body.error)
  return Response.json({ error: 'Consulta de CPF indisponível no momento' }, { status: 503 })
}

Coloque CPFHUB_API_KEY no .env.local (sem o prefixo NEXT_PUBLIC_, para não ir ao navegador). No front-end, chame /api/cpf/12345678909.

Resposta

CPF encontrado (200, consome 1 crédito):

JSON
{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

CPF não encontrado (404, não consome crédito):

JSON
{
  "success": false,
  "data": null,
  "error": { "message": "CPF não encontrado na base de dados" }
}

O CPF 12345678909 é fictício, usado só nos exemplos. gender pode vir null.

Erros

StatusO que significaO que fazer
404CPF não está na baseTrate como "não encontrado". Não consome crédito.
400 / 422CPF sem 11 dígitos ou com dígito verificador inválidoCorrija a entrada. Não consome crédito.
401API Key ausente ou inválidaConfira a variável CPFHUB_API_KEY.
403Créditos esgotados ou conta inativaVeja o saldo em GET /quota ou recarregue no dashboard.
429Limite de requisições por minutoEspere os segundos do header Retry-After e tente de novo.
5xxFalha temporáriaTente de novo após alguns segundos.

O campo error pode vir como texto ("error": "...") ou como objeto ("error": { "message": "..." }), conforme o status. Os exemplos acima tratam os dois formatos. Lista completa em Códigos de Erro.

Próximos passos