> ## 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.

# Activar o desactivar monitoreo por entidad e integración

> PATCH /entities/toggle-status-monitoring — extensible por código de proveedor — en el servicio de monitoreo de entidades gu1 para screening continuo.

```
PATCH http://api.gu1.ai/entities/toggle-status-monitoring
```

Endpoint **genérico** para fijar si una entidad **está o no** en monitoreo continuo para un `integrationCode` (la lógica aguas abajo depende del código; hoy: **Gu1 sanciones globales**).

## Autenticación

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Requiere permiso de **edición** sobre la entidad indicada en `entityId`.

## Cuerpo (JSON)

<ParamField body="entityId" type="string" required>
  UUID de la entidad (debe pertenecer a tu organización).
</ParamField>

<ParamField body="integrationCode" type="string" required>
  Código de integración / enrichment. **Soportado hoy:** `global_gueno_sanctions_enrichment`.\
  Otros valores → **400** con `UNSUPPORTED_MONITORING_INTEGRATION`.
</ParamField>

<ParamField body="active" type="boolean">
  * `true` — **incluir** en monitoreo continuo cuando la org y el flujo lo permitan (reinclusión).
  * `false` — **excluir** (equivalente a `monitoringOptOut: true` en la ruta deprecada).
    Hay que enviar **al menos uno** de `active` o `riskMatrixId`.
</ParamField>

<ParamField body="riskMatrixId" type="string | null">
  Opcional. Solo **sanciones globales Gu1**. UUID de una matriz de riesgo de la org, o `null` para quitar el override por suscripción (el screening diario vuelve a usar la matriz **global de la entidad**).
  Si se fija un UUID, **solo esa matriz** se usa en la corrida de reglas disparada por monitoreo (p. ej. `trigger_monitoring_completed`); no se mezcla con la matriz asignada a la entidad. No modifica `entities.riskMatrixId`.
</ParamField>

## Respuestas de error

| HTTP | Código (ejemplo)                     | Cuándo                                                                  |
| ---- | ------------------------------------ | ----------------------------------------------------------------------- |
| 404  | `ENTITY_NOT_FOUND`                   | La entidad no existe en la org.                                         |
| 400  | `UNSUPPORTED_MONITORING_INTEGRATION` | `integrationCode` sin handler, o `riskMatrixId` en código no soportado. |
| 400  | `INVALID_RISK_MATRIX`                | Matriz inexistente, archivada o de otra org.                            |

## Ejemplo — excluir del monitoreo Gu1

```bash theme={null}
curl -sS -X PATCH "http://api.gu1.ai/entities/toggle-status-monitoring" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationCode": "global_gueno_sanctions_enrichment",
    "active": false
  }'
```

## Ruta deprecada (compatibilidad)

`PATCH /entities/{id}/gueno-sanctions-monitoring-opt-out` con `{ "monitoringOptOut": boolean }` sigue disponible pero está **deprecada**; equivale a este endpoint con `active: !monitoringOptOut`.