Autenticación
Todas las solicitudes a la API de CPFHub.io deben autenticarse con una clave de API enviada en el header x-api-key.
Obtener tu clave de API
Al crear tu cuenta se genera automáticamente una clave de API. Entra a app.cpfhub.io/api-keys para verla y copiarla cuando quieras.
Si lo necesitas, puedes generar una clave nueva en esa misma página. Cada cuenta tiene una única clave activa. Al generar una nueva, la anterior deja de funcionar en un máximo de 5 minutos y empieza a responder 401 con "API Key inativa" (clave de API inactiva).
Cambiar la clave en producción
No existe un período con dos claves válidas. Genera la clave nueva solo cuando puedas actualizar el secreto en tu sistema de inmediato, para no interrumpir las consultas.
La clave es una cadena opaca. No valides el prefijo, la longitud ni el formato en tu código.
Guarda tu clave de forma segura
Nunca expongas tu clave de API en código del lado del cliente, repositorios públicos ni logs. Usa variables de entorno.
Enviar la clave de API
Incluye el header x-api-key en todas las solicitudes:
curl "https://api.cpfhub.io/cpf/12345678909" \
-H "x-api-key: $CPFHUB_API_KEY"Guarda la clave en una variable de entorno (CPFHUB_API_KEY en el ejemplo) y léela desde ahí en tu código.
URL base
Todas las solicitudes deben usar HTTPS:
https://api.cpfhub.ioLas solicitudes por http:// reciben una redirección 301 a HTTPS. Muchos clientes HTTP convierten un POST en GET al seguir esa redirección, lo que rompe la Consulta en Tiempo Real y la consulta por lote. Usa siempre https://.
Errores de autenticación
La API responde solo en portugués, por eso los mensajes de error se muestran tal como llegan, con la traducción entre paréntesis.
| Código | Mensaje (error) | Cuándo |
|---|---|---|
401 | API Key não fornecida (clave de API no enviada) | No se envió el header x-api-key |
401 | API Key inválida (clave de API inválida) | La clave no existe |
401 | API Key inativa (clave de API inactiva) | La clave fue reemplazada por una nueva en el dashboard |
403 | Usuário inativo. Entre em contato com o suporte. (usuario inactivo, contacta a soporte) | Cuenta desactivada |
403 | Conta bloqueada. Entre em contato com o suporte. (cuenta bloqueada, contacta a soporte) | Cuenta bloqueada |
En estos casos el campo error es una cadena:
{
"success": false,
"error": "API Key não fornecida"
}La misma clave de API sirve para todos los endpoints: Consulta Simple, Consulta en Tiempo Real, Consulta por Lote y saldo de créditos.
Para ver todos los detalles de cada error, consulta Códigos de Error.
Actualizado el 3 de octubre de 2026