Integración con interfaces de reporte regulatorio: mapeo, firma, acuses y reenvío
EN BREVE: Lo difícil del reporte regulatorio no es enviar una petición, sino otras tres cosas: cada regulador tiene su propio formato de mensaje y lo cambia, los acuses suelen ser asíncronos, y tanto los reportes omitidos como los erróneos tienen consecuencias. Dividimos el trabajo en tres capas. Los datos de origen se convierten primero en objetos estándar internos y después en el mensaje de cada regulador para una versión concreta de la especificación. Una capa de envío común se ocupa de la firma, el cifrado, los reintentos y los acuses. Cada reporte y cada acuse se conservan como registro de auditoría, con procedimientos definidos de reenvío y conciliación.
1.0 Separar el formato del envío
El patrón heredado habitual es un servicio por región, con el mapeo de campos, la firma y el envío programados a fuego. Cada cambio de especificación exige un despliegue, los servicios regionales se van separando y el mismo fallo de firma hay que corregirlo varias veces.
Una estructura más sólida separa capas según la frecuencia con que cambian:
| Capa | Responsabilidad | Cambia con |
|---|---|---|
| Recoger | Extraer datos de los sistemas de la empresa y convertirlos en objetos estándar internos | Los sistemas de la empresa |
| Mapear | Objetos estándar al mensaje de un regulador y una versión de especificación | Las versiones de especificación |
| Enviar | Autenticación, firma, cifrado, transporte, acuses, reintentos | Rara vez |
Los mapeos se gestionan por regulador y versión de especificación. Cuando entra una versión nueva, la antigua sigue disponible; el cambio ocurre en la fecha de entrada en vigor y volver atrás es cambiar la fecha.
2.0 El mapeo como configuración, con pruebas
Las reglas de mapeo son configuración: correspondencia de campos, conversión de tablas de códigos, conversión de unidades y validación de campos obligatorios. El personal de implantación las mantiene desde una interfaz, no en el código. La configuración también puede estar mal, así que:
- Cada mapeo tiene datos de muestra y mensajes esperados que se comparan automáticamente tras cada cambio.
- Las tablas de códigos, como los códigos de actividad o las divisiones administrativas, se versionan por separado y se referencian con su versión.
- Los cambios de configuración pasan por aprobación y quedan registrados, de modo que se sabe quién cambió qué y cuándo.
Siempre habrá casos que no encajen en la configuración. Dé a esas excepciones una interfaz de plugins estable, en lugar de dejar que el lenguaje de configuración crezca hasta convertirse en un lenguaje de programación que el personal de implantación no puede mantener y los desarrolladores prefieren no tocar.
3.0 La capa de envío
- Los certificados y claves se montan en solo lectura, nunca se guardan en la base de datos ni se muestran en la interfaz de configuración, y la rotación sigue un procedimiento escrito.
- Un único entorno de ejecución admite los transportes que exigen los reguladores, ya sea HTTP, conexiones TCP persistentes o una cola de mensajes, en lugar de una pila de reintentos y logs distinta para cada uno.
- Cada reporte lleva un número de serie de negocio único, y un reenvío reutiliza ese número para que el regulador pueda deduplicar. Si el regulador no deduplica, se consulta un estado local “confirmado” antes de cualquier reenvío.
- Un acuse síncrono normalmente solo significa “recibido”. El resultado del procesamiento llega como acuse asíncrono o hay que consultarlo, y hacen falta ambas vías.
4.0 Reintentos, reenvío y conciliación
| Situación | Tratamiento |
|---|---|
| Fallo de red o timeout | Espera exponencial con tope; superado el tope, cola manual |
| Rechazo por la validación del regulador | Sin reintento automático; el motivo va al responsable de los datos y el reporte corregido se reenvía |
| Reportes omitidos durante una caída | Reenvío por ventana de tiempo, con el motivo registrado |
| Periódicamente | Conciliar con las confirmaciones del regulador y listar lo no confirmado o discrepante |
Reintentar un error de validación no consigue nada salvo una serie de errores idénticos, y puede activar los límites de peticiones del regulador.
5.0 Auditoría
De cada reporte se conserva la instantánea de los datos de origen, el mensaje generado, el resumen de la firma, la hora de envío y el acuse. Ante una disputa hay que poder demostrar qué se reportó en un momento dado y qué se recibió de vuelta. La conservación sigue los requisitos del regulador y las normas de cumplimiento de la propia empresa.
Si va a sustituir un servicio de reporte heredado con todo cableado en el código o a conectarse con un regulador nuevo, consulte Web, nube y gestión de dispositivos o hable de un proyecto con nosotros.
Referencias
- Enterprise Integration Patterns, Guaranteed Delivery: https://www.enterpriseintegrationpatterns.com/patterns/messaging/GuaranteedMessaging.html
Preguntas frecuentes
Las especificaciones regionales cambian a menudo. ¿De verdad la configuración puede seguir el ritmo?
La mayoría de los cambios añaden campos, actualizan tablas de códigos o ajustan validaciones, y la configuración cubre eso. Cuando cambian también la estructura del mensaje o el transporte, hay que modificar la plantilla de mapeo o incluso la capa de envío. Por eso los mapeos se versionan por especificación y la versión antigua y la nueva conviven un tiempo, con el cambio en la fecha de entrada en vigor.
El entorno de pruebas del regulador no se comporta como producción. ¿Y entonces?
Es habitual. Guardamos anonimizado cada acuse real de las pruebas de integración como muestra de éxito, de errores de validación y de cada código de error, y conciliamos con más frecuencia tras la puesta en producción para detectar lo que el entorno de pruebas nunca mostró.
¿Podemos empezar con una sola región?
Empezar con una región es sensato, siempre que la estructura esté pensada para varios reguladores: objetos estándar, capa de mapeo y capa de envío separados. La segunda región solo añade un mapeo en lugar de copiar un servicio entero.
Nuestro personal de implantación no programa. ¿Puede mantener los mapeos?
Las correspondencias de campos y las tablas de códigos del día a día se mantienen desde la interfaz, y cada cambio se compara automáticamente con datos de muestra, así que un error aparece al instante como diferencia. Las excepciones que la configuración no puede expresar las implementan los desarrolladores mediante una interfaz de plugins.