Preguntas frecuentes

¿Qué devuelve la API de CPFHub.io?

Consulta Simple (GET /cpf/{cpf}) y consulta por lote (POST /cpf/bulk): nombre completo, género y fecha de nacimiento a partir del CPF (el número de identificación fiscal de personas físicas en Brasil). Consulta en Tiempo Real (POST /cpf/realtime): nombre, fecha de nacimiento, año de fallecimiento (deathYear, un entero o null), situación de registro en la Receita Federal (la autoridad tributaria federal de Brasil), código de control y comprobante. No devuelve score, correo electrónico ni el día o el mes del fallecimiento.

¿CPFHub.io consulta la Receita Federal en vivo?

Depende de la ruta. GET /cpf/{cpf} responde desde nuestra base de datos con un tiempo típico de ~150 ms (no es un SLA), con nombre, género y fecha de nacimiento (1 crédito por CPF encontrado). POST /cpf/realtime consulta la Receita Federal en el momento de la llamada y devuelve situación de registro, año de fallecimiento (deathYear, un entero o null), código de control y comprobante, pero exige la fecha de nacimiento del titular y tarda alrededor de 1 segundo (tiempo típico, no un SLA). Consume 1,5 créditos solo en una respuesta HTTP 200. Las fallas, incluida una fecha de nacimiento que no coincide (HTTP 422), no consumen créditos. Las rutas son independientes, así que una nunca recurre a la otra.

¿Se puede validar un CPF y un nombre en el registro?

Sí. Envías el CPF, recibes el nombre y la fecha de nacimiento, y los comparas con lo que el usuario escribió en tu flujo (prevención de fraude o registro). La regla de coincidencia queda en tu sistema.

¿Hay consulta por lote?

Sí. POST /cpf/bulk es asíncrono y acepta hasta 10.000 CPF por solicitud. Solo los CPF encontrados consumen créditos. Sirve para depurar una base de datos. Sin código, usa la consulta por lote del dashboard (app.cpfhub.io/lote) con un archivo CSV o TXT.

¿CPFHub.io hace KYC (conoce a tu cliente) con selfie u OCR?

No. El producto es la consulta de CPF: simple (GET), por lote y en tiempo real en la Receita Federal (POST). Sin biometría, selfie ni OCR de documentos.

¿Cuál es el SLA (garantía de disponibilidad)?

Por plan, en la página de precios (/precios): Gratis 95%, Pro 99%, Enterprise 99,9%. El tiempo típico de la Consulta Simple es de ~150 ms y el de la Consulta en Tiempo Real es de alrededor de 1 segundo. Son referencias típicas, no un SLA. En la consulta por lote, el tiempo depende de cuántos CPF hay en el envío, y cada consulta queda en el mismo rango de la Consulta Simple.

¿La Consulta en Tiempo Real devuelve el año de fallecimiento?

Sí. POST /cpf/realtime devuelve deathYear, el año de fallecimiento, siempre presente como un entero o null. No devuelve el día ni el mes. null aparece cuando no hay fallecimiento registrado o cuando el valor recibido es inválido (no tiene 4 dígitos, está fuera del rango entre 1900 y el año actual, o es anterior al año de nacimiento).

¿Cómo obtengo mi clave de API?

Al crear tu cuenta, se genera una clave de API automáticamente. 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.

¿El plan Gratis tiene un límite de consultas?

Sí. El plan Gratis incluye 50 créditos al mes y la API deja de responder cuando se agotan. Los planes de pago ofrecen volúmenes mayores. Mira los planes disponibles en la página de precios.

¿Existe un entorno de pruebas (sandbox)?

Las pruebas se hacen directo en la API de producción: toda cuenta incluye 50 créditos gratis al mes. Úsalos para probar tu integración en producción sin costo. Un CPF no encontrado (404) y los CPF con formato o dígito verificador incorrecto (400/422) nunca consumen créditos, así que puedes probar escenarios de error con tranquilidad.

¿Qué pasa cuando no se encuentra el CPF?

La API devuelve HTTP 404 con error.message "CPF não encontrado na base de dados" (en portugués, "CPF no encontrado en la base de datos"). Esa consulta no descuenta créditos de tu plan, así que solo pagas por las consultas exitosas.

¿Los CPF con formato o dígito verificador incorrecto también consumen créditos?

No. Un CPF con formato incorrecto (HTTP 400) o dígitos verificadores errados (HTTP 422) no consume créditos. El motivo viene en error.message. Solo se cobran las consultas en las que se encuentra el CPF: HTTP 200 en la Consulta Simple y en la Consulta en Tiempo Real, o found: true en cada ítem del lote.

¿La API almacena los CPF que consulto?

Sí. Cada consulta queda registrada con el CPF consultado, el resultado, la fecha y la cuenta que hizo la consulta, incluso cuando el CPF no se encuentra. El registro sirve para el historial del dashboard, el cobro de créditos, la auditoría y la prevención de fraude. En la Consulta en Tiempo Real también se guarda el comprobante en HTML. Los detalles de retención están en la página de cumplimiento.

¿La API es compatible con la LGPD (la ley brasileña de protección de datos)?

Sí. La API consulta solo datos de fuentes públicas y no devuelve información sensible más allá de nombre, género y fecha de nacimiento (y, en la consulta en tiempo real, la situación de registro y el año de fallecimiento en la Receita Federal). El uso está permitido para fines legítimos, como verificación de identidad, validación de registros y prevención de fraude.

¿Cuál es el tiempo de respuesta promedio?

El tiempo típico de la Consulta Simple es de ~150 ms y el de la Consulta en Tiempo Real es de alrededor de 1 segundo. Son referencias típicas, no un SLA. En la consulta por lote, el tiempo depende de cuántos CPF hay en el envío, y cada consulta queda en el mismo rango de la Consulta Simple. El SLA de disponibilidad varía según el plan: Gratis 95%, Pro 99%, Enterprise 99,9%. Revisa /precios y el estado en app.cpfhub.io/status.

¿Puedo usar la API en el frontend (navegador)?

Técnicamente sí, pero no se recomienda. Exponer tu clave de API en código del lado del cliente es un riesgo de seguridad. Haz siempre las llamadas desde un backend (servidor, función serverless, API Route de Next.js) y nunca incluyas la clave en código público.

¿Existe un límite de solicitudes por segundo o por minuto?

Sí, por minuto y por clave de API: por defecto, 30 solicitudes por minuto en la Consulta Simple (cada envío de lote cuenta como 1) y 5 por minuto en la Consulta en Tiempo Real. Los planes personalizados pueden tener límites distintos, así que confírmalo con el soporte de CPFHub.io en suporte@cpfhub.io. Por encima del límite, la API responde HTTP 429 con el header Retry-After (segundos de espera), sin consumir créditos. Además, cuando los créditos se agotan en un plan sin cobro de excedente, la API responde HTTP 403 con el mensaje "Limite de créditos excedido" ("límite de créditos excedido").

¿Existe un SDK para mi lenguaje?

La API es REST: un GET con el header x-api-key, que funciona en cualquier lenguaje con un cliente HTTP. La página de SDKs y ejemplos trae ejemplos listos para 18 lenguajes y frameworks, como Node.js, Next.js, Python, PHP, Laravel, Ruby, Go, Java, .NET y curl. El SDK oficial publicado es el de Python (pip install cpfhub). Para los demás lenguajes, usa el cliente HTTP.

¿Cómo cancelo mi suscripción?

Entra al dashboard en app.cpfhub.io, ve a Configuración → Suscripción y haz clic en Cancelar plan. La solicitud de cancelación se procesa de inmediato, y conservas el acceso al plan hasta el final del período que ya pagaste.

¿CPFHub.io ofrece soporte técnico?

Sí. Los clientes con planes de pago tienen soporte por correo electrónico con un SLA de respuesta de hasta 24 horas hábiles. Para dudas rápidas, la documentación y el playground cubren la mayoría de los casos.