Guía técnica de API PUI: login, JWT, activar reporte, prueba de webhook, desactivar reporte y trazabilidad para financieras.
API PUI: activar reporte, login, JWT y webhooks
La integración con la Plataforma Única de Identidad (PUI) no debe verse como "conectar un endpoint". Para una institución financiera, el reto real es operar un flujo completo: autenticación, JWT, activación de reportes, prueba de webhook, desactivación, bitácoras y trazabilidad.
Este artículo explica cómo pensar la API PUI desde una arquitectura institucional. Los ejemplos son genéricos y no contienen credenciales, IPs, URLs privadas ni datos de clientes.
Qué flujo cubre la API PUI
En una integración PUI existen dos direcciones de comunicación:
- La institución llama a PUI para autenticarse, consultar o notificar según el flujo aplicable.
- PUI llama a la institución para probar, activar o desactivar reportes mediante webhooks.
Ese segundo flujo es el que suele causar más dudas: la institución debe exponer endpoints seguros y responder con consistencia. No basta con recibir un JSON; hay que validar autenticación, payload, sociedad legal, estado del reporte y bitácoras.
Endpoints institucionales básicos
El patrón técnico usual es exponer una URL base institucional y derivar endpoints estándar.
Ejemplo genérico:
https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>
Endpoints:
POST /login
POST /activar-reporte
POST /activar-reporte-prueba
POST /desactivar-reporte
La URL base debe corresponder al ambiente correcto. Pruebas y producción no deberían compartir credenciales, logs ni llaves.
Login: la entrada al webhook
Cuando PUI llama a la institución, primero debe autenticarse contra el endpoint:
POST <URL_BASE>/login
El objetivo del login es validar que la llamada proviene del actor esperado y emitir un token temporal.
Un diseño sano debe considerar:
- usuario esperado
- clave o secreto configurado por sociedad
- rate limiting
- registro de intentos fallidos
- expiración corta del token
- firma robusta del JWT
- separación de credenciales por sociedad legal
Lo importante: la credencial que usa PUI para entrar a la institución no es la misma que la credencial que usa la institución para consumir PUI. Mezclarlas es una de las causas más comunes de errores 401.
JWT: qué debe contener y qué no
Después de un login exitoso, la institución devuelve un JWT. Ese token permite que PUI llame al webhook de prueba, activación o desactivación.
Un JWT institucional debería incluir lo mínimo necesario:
- sujeto o identificador técnico del usuario
- sociedad legal o configuración autorizada
- fecha de emisión
- fecha de expiración
- alcance permitido, si aplica
No debería incluir:
- contraseñas
- secretos de API
- datos biométricos
- datos personales innecesarios
- información de clientes
- campos que no sean necesarios para autorizar la llamada
La validación posterior debe confirmar firma, expiración, sociedad, usuario y permisos antes de procesar cualquier reporte.
Activar reporte
El endpoint de activación recibe una solicitud formal para iniciar la búsqueda o monitoreo de una persona dentro del alcance de la PUI.
POST <URL_BASE>/activar-reporte
Authorization: Bearer <token>
La institución debe validar:
- token Bearer
- estructura del payload
- identificador del reporte
- CURP o identificador aplicable
- datos mínimos obligatorios
- sociedad legal correcta
- estado de habilitación de la integración
- duplicidad del reporte
Después de validar, el backend debería registrar el evento y activar el flujo interno que corresponda: búsqueda inmediata, búsqueda histórica o monitoreo posterior.
Un error frecuente es intentar hacer toda la búsqueda pesada dentro de la misma petición HTTP. Eso aumenta el riesgo de timeout. Lo más robusto es responder rápido cuando la solicitud es válida y procesar tareas intensivas de forma asíncrona, manteniendo trazabilidad.
Activar reporte prueba
El endpoint de prueba permite validar conectividad sin crear un caso real:
POST <URL_BASE>/activar-reporte-prueba
Authorization: Bearer <token>
Esta prueba debe confirmar:
- que la URL base es alcanzable
- que
/loginemite un JWT válido - que el token Bearer se valida correctamente
- que el payload cumple el formato esperado
- que la sociedad legal existe y está habilitada
- que el endpoint responde en tiempo razonable
La prueba no debe generar un caso real ni iniciar búsquedas pesadas. Su función es comprobar integración, autenticación y validación.
Desactivar reporte
Cuando PUI indique que un reporte debe cerrarse o desactivarse, la institución debe recibir:
POST <URL_BASE>/desactivar-reporte
Authorization: Bearer <token>
El sistema debe:
- validar token
- encontrar el reporte activo
- marcarlo como desactivado
- detener monitoreos futuros
- conservar bitácora
- evitar borrar evidencia histórica requerida
Desactivar no significa eliminar sin rastro. En una institución financiera, la trazabilidad es parte central del cumplimiento.
Códigos HTTP recomendados
Los códigos HTTP deben comunicar qué ocurrió sin exponer secretos.
| Código | Uso recomendado |
|---|---|
| 200 | Solicitud válida y procesada. |
| 400 | Payload incompleto o inválido. |
| 401 | Falta autenticación, token inválido o credenciales incorrectas. |
| 403 | Credenciales válidas, pero sin permiso para esa sociedad o endpoint. |
| 404 | URL, sociedad o reporte no encontrado. |
| 409 | Reporte duplicado o estado incompatible. |
| 500 | Error interno no esperado. |
| 504 | Timeout o dependencia lenta. |
La respuesta debe ser útil para operación, pero no debe revelar claves, tokens, reglas internas ni detalles sensibles.
Trazabilidad: la parte que no se ve en el API
Una integración PUI no está completa si solo responde 200. Debe poder demostrar qué ocurrió.
Como mínimo, registra:
- timestamp
- endpoint
- sociedad legal
- identificador del reporte
- resultado
- código HTTP
- validaciones fallidas
- duración de la petición
- correlación entre login y webhook
No registres:
- contraseña de login
- token completo
- llave biométrica
- fotos o huellas sin protección
- payloads sensibles en texto plano
La bitácora debe permitir auditoría sin convertirse en una fuga de información.
Seguridad mínima para producción
Antes de habilitar producción, revisa:
- HTTPS con certificado vigente
- separación QA/productivo
- JWT con expiración corta
- rotación de secretos
- validación estricta de payloads
- rate limiting
- monitoreo de errores
401,403,500y504 - alertas por fallas repetidas
- pruebas SAST, DAST y SCA cuando sean requeridas
- procedimiento para revocar credenciales
También conviene definir quién puede ver logs, quién puede reintentar pruebas y quién aprueba cambios de credenciales.
Cómo ayuda Acendes Aura
Una plataforma como Acendes Aura puede ayudar a convertir la integración PUI en un flujo controlado:
- URL base por institución o sociedad
- credenciales entrantes y salientes separadas
- emisión y validación de JWT
- endpoints estándar
- bitácora técnica
- trazabilidad por reporte
- configuración por ambiente
- separación de sociedades legales
- monitoreo de errores
- conexión con procesos internos
La API es solo la superficie. El valor está en conectar la llamada técnica con datos, procesos, evidencias y responsables.
Habla con Acendes si necesitas preparar tu institución para API PUI, webhooks y trazabilidad.
Preguntas frecuentes
¿La API PUI es una API de KYC?
No. La PUI no debe entenderse como una herramienta comercial de KYC o scoring. Su finalidad está relacionada con búsqueda, localización e identificación de personas desaparecidas o no localizadas, conforme al marco aplicable.
¿El endpoint de prueba crea un reporte real?
No debería. /activar-reporte-prueba debe validar conectividad, autenticación y estructura del payload sin crear un caso real ni ejecutar búsquedas pesadas.
¿Por qué se usa JWT?
El JWT permite emitir un token temporal después del login y validar llamadas posteriores sin reenviar la contraseña en cada petición. Debe tener expiración corta y firma segura.
¿Qué diferencia hay entre 401 y 403?
401 indica que la autenticación falló o falta. 403 indica que la autenticación puede ser válida, pero no tiene permiso para esa sociedad, endpoint o configuración.
¿Se deben guardar tokens en logs?
No. Los logs deben registrar metadatos suficientes para auditoría, pero no tokens completos, contraseñas, llaves biométricas ni datos sensibles innecesarios.
Referencias
- Lineamientos para el Desarrollo y Operación de la Plataforma Única de Identidad — SIDOF/DOF
- Manual Técnico de la Solución Tecnológica para Instituciones Diversas — SIDOF/DOF
- Guía completa: cómo conectarse a la PUI de RENAPO en 2026 — KonektaPUI
Lecturas relacionadas: PUI: registro, credenciales y webhooks | Qué es PUI y por qué importa | Plataforma Única de Identidad para financieras