> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoreo continuo de sanciones globales Gu1 para clientes
> Guía de integración del monitoreo continuo de sanciones globales Gu1 — suscripción de entidades, eventos, detecciones y configuración desde la API.
# 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)](/es/monitoring/overview)** con **Referencia API** para `GET /entities/{id}/monitoring`, historial y `PATCH /entities/toggle-status-monitoring`.
* **Creación de entidades** (body `monitoring`, ejemplos): [Crear entidad](/es/api-reference/entities/create), [Crear automáticamente](/es/api-reference/entities/create-automatic) 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
1. Entrá al **Marketplace** de integraciones de vuestra organización.
2. 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).
3. **Activá** la integración para la org si aún no lo está (como cualquier otro enrichment de pago).
4. 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:
1. **`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.
2. 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": "" }` — 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.
3. **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"?: "" | 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`).
```json theme={null}
POST BASE_URL/entities
Authorization: Bearer
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": { ... }`).
```json theme={null}
"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
```json theme={null}
{
"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:
```json theme={null}
"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.).
```json theme={null}
POST BASE_URL/entities/automatic
Authorization: Bearer
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
```http theme={null}
GET BASE_URL/entities/:id/monitoring
Authorization: Bearer
```
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)
```http theme={null}
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).
```http theme={null}
PATCH BASE_URL/entities/toggle-status-monitoring
Authorization: Bearer
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**:
1. Entrá a **Análisis de riesgo** y abrí el **detalle de la entidad** (persona o empresa).
2. Abrí la pestaña **Monitoreo en listas** (en la interfaz puede figurar abreviada como “Monitoreo”; es la misma vista).
3. 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.