Integración CMP

Visión general

La Case Management Platform (CMP) es el módulo de la Suite Guardline responsable de la gestión de casos que exigen análisis humano. La integración con la CMP permite que sistemas externos abran casos de forma programática en cada mesa de análisis, den seguimiento al desenlace y reciban notificaciones sobre los eventos relevantes del ciclo de vida.

El modelo sigue una separación clara de responsabilidades: el motor de la institución detecta y abre el caso; Guardline pone en cola, distribuye, analiza y decide. La institución no necesita conocer colas, niveles de atribución ni SLA para integrarse: envía la alerta con el identificador de origen y recibe de vuelta el identificador del caso.

Mesas y puertas de entrada

Cada mesa de la CMP tiene un endpoint propio de ingesta. Todos reciben JSON por POST y se autentican con un token de API con alcance restringido a esa mesa.

Mesa	Origen típico	Endpoint	Alcance del token
Fraude	Motor de prevención de fraude (FPP o de terceros)	/api/v1/ingest/fraude	ingest:fraude
MED	Solicitudes del Mecanismo Especial de Devolução	/api/v1/ingest/med	ingest:med
AML	Motor de monitoreo de lavado de dinero	/api/v1/ingest/pld	ingest:pld
Cadastro PF y Cadastro PJ	Onboarding (ONP o motor de decisión propio)	/api/v1/ingest/kyc	ingest:kyc

El endpoint de onboarding atiende tanto a personas físicas (KYC, incluidos los menores de edad con representante legal) como a personas jurídicas (KYB); la mesa se elige según el tipo de recorrido informado en el payload.

Compatibilidad con motores externos

La CMP acepta casos de cualquier origen. Las instituciones que utilizan un motor de decisión propio (o de terceros) envían las alertas directamente a la mesa correspondiente, y la CMP opera colas, niveles de atribución, SLA, comité y registro de auditoría de la misma forma que opera con los casos generados por los demás módulos de la Suite Guardline.

Esta característica permite que la institución centralice la gestión de casos en un único entorno, independientemente de cuántos motores de decisión estén en operación.

Flujo de integración

El flujo típico de integración con la CMP sigue estos pasos:

1. El administrador de la CMP crea un token de API con el alcance de la mesa y lo entrega al sistema de origen.
2. El sistema de origen (motor de decisión, FPP, ONP u otro) envía la alerta al endpoint de la mesa, informando el identificador del evento en el origen y los datos del contexto.
3. La CMP valida el payload, aplica idempotencia sobre el identificador de origen, calcula el riesgo y el SLA según la política de la mesa y devuelve el identificador del caso.
4. El motor de distribución asigna el caso a un analista disponible en la cola de entrada de la mesa.
5. El analista revisa el expediente y registra la decisión (aprobar, rechazar, dejar pendiente, escalar, transferir a otra mesa o convocar al comité), siempre con justificación.
6. El desenlace regresa al sistema de origen: vía ONP, para los casos de onboarding; vía webhook firmado, para los eventos de la mesa AML.

Autenticación

Los endpoints de ingesta exigen el header X-API-Key con un token de API en el formato cmp_ seguido de 64 caracteres hexadecimales. Los tokens son creados por el administrador de la institución en el panel de la CMP, con alcance por mesa, límite de solicitudes por ventana temporal y vigencia opcional. El valor del token se muestra una única vez, en la creación; la plataforma almacena solo el hash.

Una credencial ausente o inválida responde 401; un token válido con alcance de otra mesa responde 403; el límite de solicitudes excedido responde 429. Todo rechazo queda asentado en el registro de auditoría con origen, ruta y motivo. Un token puede emitirse con el alcance genérico ingest, que atiende las cuatro mesas; ese es el alcance aplicado cuando no se informa ningún otro en la creación.

El endpoint de onboarding puede exigir, adicionalmente, una firma HMAC-SHA256 del cuerpo de la solicitud (headers X-Guardline-Timestamp y X-Guardline-Signature), habilitada por instancia durante el setup de la integración. Es el mismo formato de firma que usan los webhooks de la ONP.

Idempotencia

Cada endpoint deduplica sobre una clave natural elegida por el sistema de origen: external_id en la mesa de Fraude, alerta_externo_id en la mesa AML y el identificador de la ejecución de onboarding (o case_id) en las mesas de Cadastro. La mesa MED usa el primer campo presente entre id, event_id, notification_id y med_id; sin ninguno de ellos, la clave pasa a ser un hash del cuerpo de la solicitud, que no sobrevive a ninguna variación de serialización y por eso no reemplaza el envío de un identificador propio. La primera llamada crea el caso y responde 201; los reenvíos responden 200 con el identificador del caso existente, sin sobrescribir nada. Esto hace que sea seguro repetir la llamada después de un timeout de red.

En la mesa AML hay una regla adicional: una alerta nueva para un CPF o CNPJ que ya tiene un caso activo se consolida en ese caso en lugar de abrir otro. La excepción es la COE (comunicación de operación en efectivo): los movimientos en efectivo a partir de R$ 50.000,00, cuando el sistema de origen los identifica como operación en efectivo, abren siempre un caso propio, sin consolidación, y saltan el triaje.

Retorno de las decisiones

La vía por la cual la decisión del analista llega al sistema de origen depende de la mesa:

• Cadastro PF y Cadastro PJ (onboarding): la CMP devuelve a la ONP las decisiones terminales, de aprobación y de rechazo, y la ONP reanuda la ejecución y emite sus propios eventos de onboarding hacia la institución. Quien integra ONP y CMP consume un único flujo de webhooks, el de la ONP. Las decisiones intermedias, como escalar o solicitar información adicional, permanecen en la CMP y no generan evento en la ONP.
• AML: las transiciones del flujo (archivo en triaje, deliberación del comité, registro, error, rectificación y cancelación de la comunicación al COAF) se publican por webhook firmado hacia los receptores configurados.
• Fraude y MED: la decisión, sus efectos operativos y la justificación quedan registrados en el detalle del caso y en el registro de auditoría de la CMP. La publicación por webhook para esas mesas se habilita bajo demanda en el setup de la integración.

Notificaciones

Los webhooks de salida de la CMP llevan un envelope único (event, delivery_id, correlation_key, case_id, attempt, timestamp, payload), se firman con HMAC-SHA256 sobre el cuerpo en bruto (header X-Webhook-Signature) e identifican el evento y la entrega en headers propios, lo que permite el enrutamiento y la deduplicación sin interpretar el cuerpo. Las entregas sin respuesta 2xx en 10 segundos se repiten dos veces, a partir de una bandeja de salida persistente drenada cada 60 segundos: el segundo intento entra en el drenaje siguiente y el tercero al menos 30 segundos después. Agotados los tres, la entrega se cierra como fallida y el reenvío se realiza bajo demanda por parte de la operación de Guardline.

La configuración de qué eventos recibir, la URL de destino y el secreto de firma se definen durante el setup de la integración, conforme se describe en los conceptos de integración.

Referencia de la API

Los contratos completos (campos de cada endpoint, reglas de derivación de riesgo y prioridad, ejemplos, códigos de error, administración de tokens y verificación de los webhooks) están en la referencia de la API de la CMP.