Monitoreo de sanciones globales Gu1 — Guía para el cliente

Documento orientado a integradores y equipos de compliance que quieren usar el monitoreo continuo (lista vigilada / watchlist) asociado al enriquecimiento Sanciones globales Gu1, desde el Marketplace hasta las llamadas a la API al crear entidades.

Mintlify (nuevo): grupo Monitoreo (entidades) con Referencia API para GET /entities/{id}/monitoring, historial y PATCH /entities/toggle-status-monitoring.
Creación de entidades (body monitoring, ejemplos): Crear entidad, Crear automáticamente y creación persona/empresa según aplique.

1. Qué problema resuelve

Modo	Qué hace
Consulta puntual	Al ejecutar el enriquecimiento de sanciones Gu1, se evalúa el nombre contra las listas en ese momento. No deja suscripción a cambios futuros.
Monitoreo (lista vigilada)	Tras la consulta, el sujeto puede quedar suscrito para corridas periódicas de screening (p. ej. diarias). Si el proveedor detecta cambios relevantes, Gu1 lo registra (eventos / detecciones) y puede impactar consumo según su contrato (equivalente a ejecuciones de enriquecimiento, packs, etc., según lo acordado).

En la plataforma Gu1 esto se materializa en:

Registro de suscripción por entidad e integración (watchlist interna).
Eventos y detecciones de monitoreo consultables por API y en la UI.
Posibilidad de exclusión voluntaria por entidad (monitoringOptOut) sin borrar la entidad.
Screening programado: para los sujetos dados de alta en lista vigilada, el screening diario masivo se ejecuta todos los días a las 22:00 hora Argentina (huso ART, UTC−3). Los hallazgos relevantes aparecen en el historial (pestaña Cambios y screening) y en la API de historial (tab=changes). Si tu contrato o ambiente indica otro horario, validalo con soporte Gu1.

2. Código de integración y alcance

Hoy el monitoreo vía cuerpo de creación está pensado para un solo código de enriquecimiento:

Código	Rol
`global_gueno_sanctions_enrichment`	Enriquecimiento de screening que puede ejecutarse en modo lista vigilada (alta en watchlist) si la org tiene monitoreo activado y el cliente envía el flag en `monitoring`.

Los códigos legacy *_check (p. ej. global_gueno_sanctions_check) ya no están soportados en la API ni en el catálogo activo. Usá siempre el código *_enrichment equivalente en autoExecuteIntegrations.enrichments.

3. Marketplace: qué ver y qué activar

Entrá al Marketplace de integraciones de vuestra organización.
Buscá la integración de Sanciones globales Gu1 (código de catálogo típico: global_gueno_sanctions_enrichment; en la UI puede mostrarse como “Gu1 — Sanciones globales” o similar).
Activá la integración para la org si aún no lo está (como cualquier otro enrichment de pago).
Si el producto ofrece “Monitoreo de listas diarias” (o texto equivalente), activá el toggle de monitoreo para esa integración.
- En el catálogo puede figurar un indicador de que la integración admite monitoreo; el toggle de org es lo que habilita el uso en API.
- Sin ese permiso a nivel org, el enriquecimiento sigue pudiendo ejecutarse como consulta normal; no se aplicará modo watchlist aunque pidas watchlist en monitoring.main para Gu1 sanciones.

Importante: el texto exacto de la UI y del marketplace puede variar por idioma y versión; la regla de negocio es: integración Gu1 sanciones activa + monitoreo org activo para esa integración.

4. Requisitos para que `monitoring` tenga efecto

Se tienen que cumplir todas estas condiciones al crear la entidad:

global_gueno_sanctions_enrichment incluido en la ejecución automática, es decir:
- en autoExecuteIntegrations.enrichments, o
- vía executeAllActiveEnrichments: true y ese enrichment activo para la org.
Objeto monitoring con main (y si aplica relationships en creación automática con depth) con la clave global_gueno_sanctions_enrichment en formato objeto (recomendado en integraciones nuevas):
- { "watchlist": true } — alta en lista vigilada; matriz de monitoreo = heredar la global de la entidad (entities.riskMatrixId).
- { "watchlist": true, "riskMatrixId": "<uuid>" } — misma suscripción; matriz solo para corridas disparadas por monitoreo (p. ej. screening diario).
- { "watchlist": true, "riskMatrixId": null } — explícito: heredar matriz global de la entidad para monitoreo.
- Compatibilidad: un valor booleano suelto (true / false) por código puede seguir aceptándose en la API por legado; en esta guía no lo usamos en ejemplos — preferí siempre el objeto anterior.
Monitoreo habilitado en Marketplace para esa integración (punto 3 anterior).

Si falta (1) o (3), no hay error obligatorio por enviar monitoring: simplemente el enrichment corre como consulta puntual (sin suscripción a lista vigilada). Si falta (2), no se pide watchlist.

4.1 Matriz de riesgo solo para monitoreo (opcional)

Si no configurás una matriz por suscripción (risk_matrix_id en watchlist / null en API y UI), el screening diario y las reglas con trigger de monitoreo se comportan como hasta ahora: se usa la matriz global de la entidad (entities.riskMatrixId) y se ejecutan las reglas que correspondan a ese evento.
Si sí asignás una matriz por integración (body monitoring.main con objeto y riskMatrixId, PATCH .../toggle-status-monitoring, etc.), en esa corrida solo se evalúa esa matriz para las reglas disparadas por monitoreo; no se mezcla con la matriz global de la entidad. La matriz global no se sobrescribe salvo otros flujos explícitos.

5. Creación manual — `POST /entities`

Usá este endpoint cuando creás persona o empresa con payload propio (no flujo solo taxId).

5.1 Dónde va `monitoring`

monitoring.main: mapa código de enrichment → objeto { "watchlist"?: boolean, "riskMatrixId"?: "<uuid>" | null } (recomendado). Solo tiene efecto sobre la entidad principal del request. riskMatrixId opcional fija la matriz solo para corridas de monitoreo; null o ausencia del campo equivale a heredar la matriz global de la entidad. La API puede aceptar todavía un boolean por integración por compatibilidad; no lo documentamos como patrón nuevo.
monitoring.relationships: en POST /entities no se usa; ignorarlo.

5.2 Ejemplo — persona con suscripción a lista vigilada

Sustituí BASE_URL y el token por los de vuestro ambiente (p. ej. https://api.gu1.ai).

POST BASE_URL/entities
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "type": "person",
  "externalId": "cliente_screening_001",
  "name": "María González",
  "countryCode": "AR",
  "taxId": "27-12345678-1",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  }
}

5.2b Ejemplo — misma suscripción con matriz de riesgo solo para monitoreo

El mapa main sigue siendo un objeto cuya clave es el código de integración; no hace falta un array: cada proveedor futuro tendría su propia clave ("otro_enrichment_code": { ... }).

"monitoring": {
  "main": {
    "global_gueno_sanctions_enrichment": {
      "watchlist": true,
      "riskMatrixId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }
}

Si omitís "watchlist" dentro del objeto, se interpreta como true (alta en lista vigilada).
"riskMatrixId" debe ser un UUID válido de una matriz de vuestra organización (la API valida el formato en creación; en el camino de enrichment, un UUID inexistente u otra org puede ignorarse al persistir la watchlist).
Esto no reemplaza entities.riskMatrixId; solo afecta reglas disparadas por monitoreo cuando haya override en la fila watchlist.

En POST /entities/automatic el bloque es el mismo: monitoring.main (y relationships si aplica) con objeto por código, como en los ejemplos.

5.3 Ejemplo — empresa

{
  "type": "company",
  "externalId": "empresa_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  }
}

5.4 Uso de `executeAllActiveEnrichments: true`

Si en lugar de listar enrichments usás executeAllActiveEnrichments: true, el enrichment de Gu1 sanciones debe estar activo en la org para que entre en el lote. El objeto monitoring.main sigue siendo necesario para pedir explícitamente watchlist en ese run:

"monitoring": {
  "main": {
    "global_gueno_sanctions_enrichment": {
      "watchlist": true
    }
  }
},
"autoExecuteIntegrations": {
  "executeAllActiveEnrichments": true,
  "enrichments": []
}

6. Creación automática — `POST /entities/automatic`

Flujo típico: taxId + país (+ depth para accionistas / relacionadas). Además de los enrichments obligatorios por país que exige la API (no los omitáis; ver doc Mintlify), podés sumar Gu1 sanciones y monitoreo.

6.1 `monitoring.main` y `monitoring.relationships`

Clave	Uso
`monitoring.main`	Entidad raíz del árbol (la que resolvés con taxId).
`monitoring.relationships`	Cuando `depth` > 0 y se enriquecen socios / relacionadas en el mismo job, podés pedir watchlist para esas entidades con el mismo mapa de códigos.

6.2 Ejemplo mínimo (empresa + accionistas, ambos con monitoreo)

Los bloques autoExecuteIntegrations / autoExecuteIntegrationsShareholders deben incluir el enrichment donde corresponda; el ejemplo siguiente solo muestra la parte de monitoreo + Gu1 — en producción debéis añadir los códigos requeridos por país (p. ej. Brasil, etc.).

POST BASE_URL/entities/automatic
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "taxId": "30-71000001-2",
  "country": "AR",
  "type": "company",
  "depth": 1,
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    },
    "relationships": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  },
  "autoExecuteIntegrationsShareholders": {
    "executeAllActiveEnrichments": false,
    "enrichments": {
      "company": ["global_gueno_sanctions_enrichment"],
      "person": ["global_gueno_sanctions_enrichment"]
    }
  }
}

Si relationships no va o va con false, las relacionadas no piden alta en lista vigilada en ese job (aunque tengan el enrichment en su lote).
Alineá autoExecuteIntegrationsShareholders (o equivalente en vuestro contrato) con los enrichments que realmente corrán para personas/empresas en el árbol.

7. Después de crear: consultar estado y opt-out

Todas las rutas asumen el prefijo habitual de API y autenticación Bearer.

7.1 Estado de monitoreo por entidad

GET BASE_URL/entities/:id/monitoring
Authorization: Bearer <API_KEY>

Respuesta orientativa (simplificada): incluye si el monitoreo org está activo (orgMonitoringEnabled), datos de la fila de watchlist (nombre de búsqueda, UID aguas arriba si existe), si está activa, si hubo detección el día corriente en zona configurada (guenoDailyScreeningHitToday), etc. Útil para mostrar en backoffice propio.

7.2 Historial (timeline)

GET BASE_URL/entities/:id/monitoring/history?tab=subscriptions&limit=20&offset=0
GET BASE_URL/entities/:id/monitoring/history?tab=changes&limit=20&offset=0

tab=subscriptions: altas/bajas de lista vigilada (ciclos de vida).
tab=changes: snapshots / detecciones de screening periódico.

Query opcional: integrationCode (por defecto el de Gu1 sanciones enrichment).

7.3 Activar o desactivar monitoreo (API genérica)

Endpoint único para fijar si la entidad participa en el monitoreo continuo por código de integración (extensible a futuros proveedores).

PATCH BASE_URL/entities/toggle-status-monitoring
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "entityId": "uuid-de-la-entidad",
  "integrationCode": "global_gueno_sanctions_enrichment",
  "active": false
}

active: false: la entidad deja de incluirse en el monitoreo continuo para esa integración (baja de la lista vigilada en el proveedor cuando aplica).
active: true: reinclusión si la org sigue con monitoreo habilitado y el flujo lo permite.

Compatibilidad: PATCH /entities/:id/gueno-sanctions-monitoring-opt-out con { "monitoringOptOut": true|false } sigue existiendo pero está deprecado; equivale a este endpoint con integrationCode = global_gueno_sanctions_enrichment y active: !monitoringOptOut. Permisos: edición de entidad (entities:edit) sobre el entityId enviado; ver doc Mintlify.

7.4 Aplicación web Gu1: pestaña Monitoreo

Además de la API, el equipo puede revisar y operar desde la aplicación web:

Entrá a Análisis de riesgo y abrí el detalle de la entidad (persona o empresa).
Abrí la pestaña Monitoreo en listas (en la interfaz puede figurar abreviada como “Monitoreo”; es la misma vista).
Ahí verán, por integración compatible (p. ej. Sanciones globales Gu1):
- si el monitoreo está habilitado a nivel organización (si la org lo apagó en Marketplace, se muestra acotado);
- estado en lista (en lista / fuera de lista / sin registro), nombre de búsqueda enviado al proveedor e ID en lista cuando exista;
- el interruptor Incluir en monitoreo (equivale a participar o no en el monitoreo continuo para esa integración). Al desactivarlo, la app puede pedir confirmación antes de dar de baja la suscripción, para evitar errores;
- un bloque Historial (acordeón) con dos pestañas: por defecto Cambios y screening (snapshots y novedades del screening periódico) y Suscripciones y bajas (altas y bajas de lista vigilada), alineado con los parámetros tab=changes / tab=subscriptions de la API.

En la tabla de entidades de Análisis de riesgo puede mostrarse un indicador de monitoreo por enriquecimiento (hasEnrichmentMonitoring); tras cambiar monitoreo desde Marketplace, esta pestaña o la API, conviene refrescar la lista o volver a entrar al listado para ver el ícono actualizado.

8. Preguntas frecuentes

¿Enviar solo monitoring sin autoExecuteIntegrations alinea Gu1?
No. Tiene que ejecutarse el enrichment global_gueno_sanctions_enrichment en ese mismo flujo. ¿Puedo usar global_gueno_sanctions_check para monitoreo?
No. Los códigos *_check fueron eliminados (2026-06-04). Para screening puntual o lista vigilada al crear, usá siempre global_gueno_sanctions_enrichment en autoExecuteIntegrations.enrichments (y en monitoring.main si querés watchlist). ¿Qué pasa si olvidamos activar el toggle en Marketplace?
El enrichment puede correr op 0 (consulta puntual). No se activa watchlist hasta que la org habilite monitoreo y volváis a ejecutar con monitoring si hace falta (o usáis flujos de backfill que exponga el producto). ¿monitoring.main admite otros códigos hoy?
Hoy el producto está preparado para global_gueno_sanctions_enrichment en ese mapa. Otras claves pueden ignorarse hasta que exista soporte explícito. ¿A qué hora corre el screening diario?
Para listas vigiladas Gu1, el lote diario se programa a las 22:00 hora Argentina (ART, UTC−3). Los resultados se reflejan en historial y API según el procesamiento; si necesitás confirmación contractual exacta, consultá con soporte. ¿Dónde veo si hubo novedades hoy?
En la respuesta de GET /entities/:id/monitoring puede venir el indicador guenoDailyScreeningHitToday (según configuración y corrida del día). En la UI, el detalle en la pestaña Monitoreo y el historial en Cambios y screening ayudan a auditar.

9. Resumen operativo

Objetivo	Acción
Habilitar uso de API	Marketplace: integración Gu1 sanciones + monitoreo org.
Suscribir al crear (manual)	`POST /entities` + `monitoring.main` + `autoExecuteIntegrations.enrichments` con `global_gueno_sanctions_enrichment`.
Suscribir raíz + relacionadas (automático)	`POST /entities/automatic` + `monitoring.main` + opcional `monitoring.relationships` + `depth` y enrichments en socios.
Ver estado	`GET /entities/:id/monitoring`
Historial	`GET /entities/:id/monitoring/history?...`
Activar / desactivar monitoreo por integración	`PATCH .../toggle-status-monitoring` (`entityId`, `integrationCode`, `active`)
Ver / ajustar en la app web	Análisis de riesgo → detalle de entidad → pestaña Monitoreo en listas (historial + switch); screening diario 22:00 ART.
Monitoreo org (Marketplace)	Integración Gu1 activa + toggle de monitoreo en la card; al activar, opción de registrar entidades existentes en lista (backfill con filtros en la UI).

10. Referencias internas del repositorio

Validación del body (shape de monitoring): apps/api/src/validators/entities.validator.ts
Lógica consulta puntual vs watchlist al ejecutar enrichment: packages/integrations/src/services/integration-execution.service.ts
Rutas HTTP: apps/api/src/routes/entities.route.ts

Si necesitáis esta guía en inglés o portugués, se puede duplicar la estructura bajo docs/en/guias/ o docs/pt/guias/ con el mismo contenido traducido.

​Monitoreo de sanciones globales Gu1 — Guía para el cliente

​1. Qué problema resuelve

​2. Código de integración y alcance

​3. Marketplace: qué ver y qué activar

​4. Requisitos para que monitoring tenga efecto

​4.1 Matriz de riesgo solo para monitoreo (opcional)

​5. Creación manual — POST /entities

​5.1 Dónde va monitoring

​5.2 Ejemplo — persona con suscripción a lista vigilada

​5.2b Ejemplo — misma suscripción con matriz de riesgo solo para monitoreo

​5.3 Ejemplo — empresa

​5.4 Uso de executeAllActiveEnrichments: true

​6. Creación automática — POST /entities/automatic

​6.1 monitoring.main y monitoring.relationships

​6.2 Ejemplo mínimo (empresa + accionistas, ambos con monitoreo)

​7. Después de crear: consultar estado y opt-out

​7.1 Estado de monitoreo por entidad

​7.2 Historial (timeline)

​7.3 Activar o desactivar monitoreo (API genérica)

​7.4 Aplicación web Gu1: pestaña Monitoreo

​8. Preguntas frecuentes

​9. Resumen operativo

​10. Referencias internas del repositorio

Monitoreo de sanciones globales Gu1 — Guía para el cliente

1. Qué problema resuelve

2. Código de integración y alcance

3. Marketplace: qué ver y qué activar

4. Requisitos para que `monitoring` tenga efecto

4.1 Matriz de riesgo solo para monitoreo (opcional)

5. Creación manual — `POST /entities`

5.1 Dónde va `monitoring`

5.2 Ejemplo — persona con suscripción a lista vigilada

5.2b Ejemplo — misma suscripción con matriz de riesgo solo para monitoreo

5.3 Ejemplo — empresa

5.4 Uso de `executeAllActiveEnrichments: true`

6. Creación automática — `POST /entities/automatic`

6.1 `monitoring.main` y `monitoring.relationships`

6.2 Ejemplo mínimo (empresa + accionistas, ambos con monitoreo)

7. Después de crear: consultar estado y opt-out

7.1 Estado de monitoreo por entidad

7.2 Historial (timeline)

7.3 Activar o desactivar monitoreo (API genérica)

7.4 Aplicación web Gu1: pestaña Monitoreo

8. Preguntas frecuentes

9. Resumen operativo

10. Referencias internas del repositorio