Guía técnica de PUI: registro, URL base, credenciales, webhooks, prueba de integración y errores HTTP sin exponer secretos.
PUI: registro, credenciales y webhooks para instituciones financieras
La integración técnica con la Plataforma Única de Identidad (PUI) suele generar confusión porque mezcla registro institucional, URL base, IPs, credenciales, webhooks, tokens y pruebas de seguridad. Para una financiera, el riesgo no está solo en publicar endpoints, sino en confundir secretos, ambientes o sociedades legales.
Esta guía explica, de forma práctica, qué información se prepara para el registro técnico, qué credenciales no deben mezclarse y cómo debe pensarse la prueba de webhook. Los ejemplos usan valores genéricos; no deben copiarse como configuración real.
Antes de empezar: qué se registra
Durante el registro técnico, la institución debe preparar información operativa y tecnológica. Los campos concretos pueden variar según el portal, manual vigente y requerimientos de la autoridad, pero normalmente se necesita:
- enlace técnico
- URL base institucional
- endpoints derivados
- IP pública fija de salida o datos de conectividad, si son requeridos
- ambiente de pruebas y ambiente productivo
- credenciales de autenticación
- reportes de seguridad cuando aplique
- información por institución, sociedad legal o registro separado
La regla de oro es esta:
no se debe registrar una configuración compartida si legal u operativamente hay entidades distintas que deben mantenerse separadas.
Si una organización opera más de una sociedad legal o registro independiente, conviene manejar una configuración PUI por sociedad. Eso permite separar credenciales, bitácoras, habilitación, trazabilidad y responsabilidades.
URL base y endpoints institucionales
La institución debe exponer una URL base desde la cual se deriven los endpoints que la PUI invocará.
Ejemplo genérico:
https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>
Endpoints derivados:
POST /login
POST /activar-reporte
POST /activar-reporte-prueba
POST /desactivar-reporte
Ejemplo completo con placeholders:
POST https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>/login
POST https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>/activar-reporte
POST https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>/activar-reporte-prueba
POST https://api.tu-institucion.mx/api/v1/pui/<institucion_slug>/<sociedad_slug>/desactivar-reporte
En producción, la URL debe usar HTTPS, certificado válido y una infraestructura capaz de responder de forma estable. En pruebas, lo recomendable es usar una URL separada, con credenciales separadas y datos no productivos.
IP pública: salida, entrada o ambas
Cuando se habla de "la IP para PUI", hay que precisar la dirección de comunicación.
Hay al menos dos flujos:
- PUI llama a la institución para activar, probar o desactivar reportes.
- La institución llama a PUI para autenticarse, notificar coincidencias, finalizar búsquedas o consultar reportes.
Por eso, antes de llenar una ficha técnica, se debe confirmar si se solicita:
- IP pública de salida de la institución
- IPs o rangos desde los que PUI llamará
- reglas de firewall para entrada
- listas blancas para salida
- ambas direcciones
No conviene publicar IPs reales en documentación abierta, tickets o wikis no controladas. Las IPs y reglas de red deben transmitirse por canales seguros y mantenerse actualizadas con control de cambios.
Las tres credenciales que no deben confundirse
La confusión más común es mezclar tres secretos distintos. Separarlos desde el diseño evita errores de autenticación difíciles de diagnosticar.
1. Credencial de la institución hacia PUI
Esta credencial permite que la institución consuma los endpoints de la PUI.
Normalmente incluye:
- identificador de institución
- clave o secreto de acceso
Uso típico:
POST /login de PUI
Esta credencial no la inventa el equipo interno. Debe provenir del proceso de registro o del enlace técnico correspondiente.
2. Credencial de PUI hacia la institución
Esta credencial permite que PUI consuma los endpoints expuestos por la institución.
Normalmente incluye:
- usuario esperado
- clave definida por la institución
Uso típico:
POST /login de la institución
La institución genera la clave, la guarda de forma segura y la registra donde corresponda. En una plataforma interna, esta clave debe almacenarse cifrada o hasheada según diseño, no en texto plano ni en repositorios.
3. Contraseña de cifrado biométrico
Cuando existan datos biométricos y la institución esté legalmente facultada para tratarlos, puede existir una clave específica para cifrado de fotos o huellas.
Esta contraseña no es la misma que la del login. Su finalidad es criptográfica, no de autenticación.
Debe tratarse como secreto de alta sensibilidad:
- no se publica en logs
- no se comparte por correo sin protección
- no se reutiliza como contraseña de API
- no se mezcla entre sociedades legales
- no se expone en tickets ni documentos abiertos
Webhook de prueba: qué valida
El endpoint de prueba permite validar conectividad antes de procesar reportes reales.
Endpoint:
POST <URL_BASE>/activar-reporte-prueba
Esta prueba debería confirmar:
- que la URL base es alcanzable
- que el flujo de autenticación funciona
- que el token Bearer se emite y se valida
- que el payload se recibe en formato esperado
- que los campos obligatorios se validan
- que el endpoint responde rápido
Un punto importante: /activar-reporte-prueba no debe crear un caso real. Su función es comprobar conectividad, autenticación y validación de payload.
Flujo esperado de prueba
Un flujo sano se ve así:
- Se captura el usuario técnico esperado por la institución.
- Se captura la clave que la institución generó para PUI.
- PUI llama a:
POST <URL_BASE>/login
- La institución valida usuario y clave.
- La institución devuelve un JWT.
- PUI llama a:
POST <URL_BASE>/activar-reporte-prueba
Authorization: Bearer <token>
- La institución valida token y payload.
- Si todo es correcto, responde
200.
Este flujo debe quedar registrado en bitácoras técnicas sin exponer secretos.
Códigos HTTP esperados
Los códigos HTTP deben ser consistentes. No ayudan mensajes ambiguos como "error general" para cualquier falla.
| Código | Significado práctico |
|---|---|
| 200 | La solicitud fue recibida, autenticada y validada correctamente. |
| 400 | El payload tiene formato inválido o faltan campos obligatorios. |
| 401 | Credenciales inválidas, token ausente, token expirado o firma inválida. |
| 403 | La configuración existe, pero no está autorizada para esa institución, sociedad o usuario. |
| 404 | URL, tenant, sociedad o recurso no encontrado. |
| 500 | Error interno no esperado en el backend. |
| 504 | Timeout o respuesta demasiado lenta. |
En endpoints de prueba, el objetivo es responder rápido. Cualquier búsqueda pesada debe ejecutarse fuera del hilo HTTP o simularse con validaciones acotadas.
Checklist antes de presionar "probar webhook"
Antes de ejecutar la prueba, revisa:
- la sociedad legal correcta existe en el sistema
- la configuración PUI está habilitada
- la URL base corresponde al ambiente correcto
- el usuario esperado coincide exactamente
- la clave registrada coincide con la capturada en el portal
- no se está usando la credencial de salida hacia PUI como contraseña de entrada
- no se está usando la clave biométrica como contraseña de login
- el certificado TLS es válido
- el endpoint
/logindevuelve un token con vigencia controlada /activar-reporte-pruebavalida token Bearer- el payload de prueba no crea casos reales
- los logs registran eventos sin secretos
- SAST, DAST y SCA están listos si son requeridos para autorización
Buenas prácticas de configuración
Para evitar incidentes, la configuración PUI debería seguir estas reglas:
Separar ambientes
QA y producción deben tener URLs, credenciales y bitácoras separadas. No se deben usar credenciales productivas para pruebas.
Separar sociedades legales
Si hay múltiples sociedades legales, cada una debe tener:
- slug técnico propio
- nombre legal propio
- URL base propia
- credenciales propias
- estado de habilitación independiente
- bitácora separable
No registrar secretos en lugares inseguros
No publicar claves en:
- wikis abiertas
- tickets
- notas internas visibles para muchas personas
- logs
- screenshots
- repositorios
Registrar trazabilidad útil
Los logs deben permitir responder:
- quién llamó
- a qué endpoint
- para qué sociedad
- con qué resultado
- qué validación falló
- cuánto tardó
No deben registrar tokens completos, claves, contraseñas ni biométricos sin protección.
Cómo ayuda una plataforma como Aura
Una plataforma de automatización como Acendes Aura puede reducir el riesgo operativo porque centraliza:
- configuración por institución o sociedad
- credenciales entrantes y salientes
- endpoints estándar
- autenticación JWT
- validación de payloads
- bitácoras
- estados de habilitación
- separación de ambientes
- evidencia técnica para pruebas
Esto no elimina la responsabilidad legal de la institución, pero reduce la probabilidad de errores técnicos y facilita que cumplimiento, seguridad y tecnología trabajen sobre una misma fuente de verdad.
Solicita una revisión técnica de integración PUI si necesitas evaluar URL base, credenciales y webhooks antes de registrar tu institución.
Preguntas frecuentes
¿La URL base debe ser distinta por sociedad legal?
Cuando cada sociedad requiere registro PUI independiente, sí conviene tener una URL base o ruta diferenciada por sociedad. Esto separa credenciales, bitácoras y trazabilidad.
¿La contraseña de login es la misma que la clave biométrica?
No. La credencial de autenticación y la contraseña de cifrado biométrico tienen finalidades distintas. Mezclarlas es un error operativo y de seguridad.
¿La prueba de webhook crea un reporte real?
No debería. El endpoint de prueba debe validar conectividad, autenticación y payload sin generar un caso real ni ejecutar búsquedas pesadas.
¿Qué pasa si la prueba devuelve 401?
Normalmente hay que revisar usuario, contraseña, token Bearer, firma del JWT, expiración del token o que se esté usando la credencial correcta para el sentido correcto de comunicación.
¿Qué evidencia de seguridad puede solicitarse?
El Manual Técnico contempla requisitos de ciberseguridad. En la práctica pueden pedirse evidencias como SAST, DAST y SCA, además de validación de TLS, autenticación y trazabilidad.
Referencias
- Manual Técnico de la Solución Tecnológica para Instituciones Diversas — SIDOF/DOF
- Lineamientos para el Desarrollo y Operación de la Plataforma Única de Identidad — SIDOF/DOF
- Guía completa: cómo conectarse a la PUI de RENAPO en 2026 — KonektaPUI
- Manual Técnico de la Solución Tecnológica para Instituciones Diversas, DOF, edición vespertina del 23 de enero de 2026.
Lecturas relacionadas: Qué es PUI y por qué importa en instituciones financieras | Plataforma Única de Identidad: lo que toda financiera debe saber | Validación de identidad