Consultar CPF com Express
Consulte CPF com Express criando um endpoint no seu servidor que chama a API CPFHub.io com o fetch nativo do Node.js 18+. A API Key fica só no servidor.
Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta Simples e cole no seu assistente.
Antes de começar
- Crie uma conta grátis em app.cpfhub.io: o plano Grátis tem 50 créditos e não pede cartão.
- Copie sua API Key em app.cpfhub.io/api-keys.
- Guarde a chave em uma variável de ambiente, nunca no código:
export CPFHUB_API_KEY="sua_api_key"Instale a dependência:
npm install expressExemplo
// server.js
const express = require('express')
const app = express()
app.get('/cpf/:cpf', async (req, res) => {
const cpf = req.params.cpf.replace(/\D/g, '')
if (cpf.length !== 11) {
return res.status(400).json({ error: 'CPF deve ter 11 dígitos' })
}
try {
const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
headers: { 'x-api-key': process.env.CPFHUB_API_KEY },
signal: AbortSignal.timeout(10_000),
})
const body = await response.json()
if (response.ok) return res.json(body.data)
if (response.status === 404) return res.status(404).json({ error: 'CPF não encontrado' })
if (response.status === 422) return res.status(422).json({ error: 'CPF inválido' })
// 401, 403, 429 e 5xx: problema de chave, créditos ou limite. Registre e não exponha ao cliente.
console.error('CPFHub.io', response.status, body.error)
res.status(503).json({ error: 'Consulta de CPF indisponível no momento' })
} catch (err) {
console.error('CPFHub.io', err)
res.status(503).json({ error: 'Consulta de CPF indisponível no momento' })
}
})
app.listen(3000)Rode com node server.js e teste com curl http://localhost:3000/cpf/12345678909.
Resposta
CPF encontrado (200, consome 1 crédito):
{
"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):
{
"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
| Status | O que significa | O que fazer |
|---|---|---|
404 | CPF não está na base | Trate como "não encontrado". Não consome crédito. |
400 / 422 | CPF sem 11 dígitos ou com dígito verificador inválido | Corrija a entrada. Não consome crédito. |
401 | API Key ausente ou inválida | Confira a variável CPFHUB_API_KEY. |
403 | Créditos esgotados ou conta inativa | Veja o saldo em GET /quota ou recarregue no dashboard. |
429 | Limite de requisições por minuto | Espere os segundos do header Retry-After e tente de novo. |
5xx | Falha temporária | Tente 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.