Conceptos de integración

Visión general

La Suite Guardline expone APIs REST para la integración con los sistemas internos de la institución (core banking, ERP, CRM, sistemas heredados). La comunicación entre la institución y la plataforma sigue patrones bien definidos que garantizan seguridad, trazabilidad y consistencia en todas las operaciones.

Esta sección describe los conceptos que se aplican a todas las integraciones de la suite.

Patrones de comunicación

La integración con Guardline utiliza dos patrones de comunicación complementarios:

• Solicitudes de la institución hacia Guardline: llamadas REST autenticadas, con payloads en JSON. La institución envía datos (creación de onboardings, envío de transacciones, apertura de casos) y consulta resultados.
• Notificaciones de Guardline hacia la institución: webhooks disparados por la plataforma cuando ocurren eventos relevantes (conclusión de una verificación, decisión de un caso, alerta de fraude). La institución registra URLs de callback y selecciona qué eventos desea recibir.

Estos dos patrones se complementan. Las llamadas REST se usan para operaciones iniciadas por la institución, mientras que los webhooks eliminan la necesidad de sondeo (polling) y garantizan que la institución sea informada de los eventos en tiempo real.

Autenticación

Todas las llamadas a la API requieren autenticación mediante un token Bearer obtenido a través del flujo OAuth2 client credentials. La institución recibe credenciales (client ID y client secret) durante el proceso de contratación y las utiliza para obtener tokens de acceso con alcance y vigencia definidos.

Los tokens deben renovarse antes de su vencimiento. La plataforma rechaza solicitudes con tokens inválidos o vencidos.

Entornos

La plataforma ofrece dos entornos aislados:

• Sandbox: entorno de pruebas con datos sintéticos, disponible después de la firma del contrato. Replica la configuración de producción y permite validar la integración antes de la puesta en producción (go-live).
• Producción: entorno operativo con datos reales.

Cada entorno tiene URLs y credenciales propias. Los datos creados en el sandbox no afectan a producción y viceversa.

Formato de datos

• Todas las solicitudes y respuestas utilizan JSON (Content-Type application/json, codificación UTF-8).
• Las fechas siguen el formato ISO 8601 (ejemplo: 2025-01-15T14:30:00Z).
• Los identificadores son cadenas opacas generadas por la plataforma.

Versionado

La API sigue un versionado por path. Los cambios que rompen la compatibilidad se introducen en nuevas versiones. La versión anterior permanece disponible durante un período de transición comunicado con antelación.

Webhooks

Guardline notifica los eventos relevantes mediante webhooks configurables. Cada notificación incluye una firma HMAC que permite a la institución validar la autenticidad y la integridad del mensaje antes de procesarlo.

La configuración de webhooks involucra tres elementos:

• URL de callback: endpoint de la institución que recibirá las notificaciones.
• Eventos suscritos: selección de los tipos de evento que la institución desea recibir.
• Secreto HMAC: clave compartida usada para generar y validar la firma de cada notificación.

Cada módulo de la suite (ONP, FPP, CMP) tiene su propio conjunto de eventos. Los detalles de cada módulo se encuentran en las respectivas páginas de integración.