> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de reglas y MCP: gestión programática de reglas KYT

> Crea, ajusta, haz backtest y migra reglas KYT de Didit por código con la Management API y MCP: flujo crear, backtest y activar.

Todas las funciones relacionadas con las reglas de la **Business Console** también están disponibles de forma programática: a través de la **Management API** con la clave de API de tu aplicación y a través del **Didit MCP** para agentes de IA que actúan como un usuario de la consola con sesión iniciada. Úsalas para gestionar reglas desde código, mantener los conjuntos de reglas bajo control de versiones o dejar que un asistente de IA cree y migre reglas por ti.

## Qué interfaz usar en cada caso

| Interfaz | Autenticación | Ideal para |
| - | - | - |
| **Business Console** | Inicio de sesión en la consola | Revisión humana de cada cambio; creación visual de reglas y backtesting |
| **Management API** | `x-api-key` | Automatización desde tu backend, conjuntos de reglas en código, despliegues de reglas gestionados por CI |
| **Didit MCP** | Iniciar sesión con Didit (OAuth) | Asistentes y agentes de IA: el Copilot de la consola de Didit, Claude, Cursor o cualquier cliente MCP |

## Los endpoints

| Endpoint | Propósito |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/es/management-api/transactions/rules-list) | Listar reglas con filtros y ordenación por rendimiento |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/es/management-api/transactions/rules-create) | Crear una regla personalizada |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/es/management-api/transactions/rules-get) | Consultar una regla con sus contadores de ejecución |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/es/management-api/transactions/rules-update) | Actualizar una regla personalizada; cambiar el modo de cualquier regla |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/es/management-api/transactions/rules-delete) | Eliminar una regla personalizada (de forma permanente) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/es/management-api/transactions/rules-backtest) | Evaluar una regla hipotética contra tu historial |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/es/management-api/transactions/rules-library) | Explorar la biblioteca de 150+ reglas predefinidas con su estado de instalación |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/es/management-api/transactions/rules-install) | Instalar reglas predefinidas por clave, por paquete o por la intersección de ambos |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/es/management-api/transactions/rules-uninstall) | Desinstalar reglas predefinidas por clave, por paquete o por la intersección de ambos |

Las herramientas MCP correspondientes son `didit_transaction_rule_list`, `didit_transaction_rule_get`, `didit_transaction_rule_create`, `didit_transaction_rule_update`, `didit_transaction_rule_delete`, `didit_transaction_rule_backtest`, `didit_transaction_rule_library_list`, `didit_transaction_rule_install` y `didit_transaction_rule_uninstall`; consulta la [referencia de herramientas MCP](https://docs.didit.me/es/integration/mcp/tools.md).

El esquema completo (el catálogo de campos, los 19 operadores de condición, las ventanas de velocidad, las condiciones agrupadas y los seis tipos de acción) está documentado en la página [Reglas y puntuación](https://docs.didit.me/es/transaction-monitoring/rules.md) e integrado en la referencia de la API.

## Crear, hacer backtest y activar

El patrón de despliegue seguro para cualquier regla nueva:

**1. Crea la regla en modo TEST**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Structuring - inbound (custom)",
    "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
    "category": "finance",
    "mode": "TEST",
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "actions": [{"type": "add_score", "value": 35}]
  }'
```

Lee el payload en dos mitades. `scope` y `conditions` describen **la transacción que se evalúa**: una transacción financiera entrante en EUR con un `amount` sin convertir inferior a 10,000. Las entradas de `aggregation` describen **la ventana de 30 días para el mismo sujeto**: al menos 20 transacciones financieras entrantes en EUR, y ninguna de ellas de 10,000 EUR o más. Ambas entradas de agregación deben cumplirse, diga lo que diga `evaluation_mode`: ese ajuste solo rige las condiciones.

Este ejemplo usa el `amount` sin convertir y fija `currency` en EUR en ambas mitades, por lo que no depende de la normalización de divisas. Para hacer el backtest con datos de prueba en sandbox, envía al menos 20 transacciones financieras entrantes en EUR para el mismo sujeto en un plazo de 30 días, cada una con un `amount` inferior a 10,000. No se requiere ni `preferred_currency_amount` ni `amount_in_default_currency`. La ingesta en sandbox almacena estas transacciones; ejecuta el backtest de forma explícita.

Una regla en `TEST` se evalúa en cada transacción nueva y registra las coincidencias que habría encontrado, pero nunca modifica la puntuación ni el estado de la transacción.

> [!NOTE]
>
> **Un filtro de agregación no es una condición.** Una condición solo lee la transacción que se evalúa; un filtro de agregación solo acota la ventana histórica y compara por igualdad o pertenencia a una lista. No existe un filtro `lt`, así que no puedes contar *solo las transferencias inferiores a 10,000*.
>
> La entrada `max ... lt 10000` es la forma admitida de poner un tope a la ventana: exige que **todas** las transacciones de la ventana sean inferiores a 10,000, lo cual es más estricto que contar solo las pequeñas. Una sola transferencia de 12,000 entre las veinte impide que la regla se dispare. Elimina esa entrada si prefieres que el recuento funcione por sí solo, y entonces indícalo en el título: sin ella, la regla cuenta transferencias entrantes de cualquier importe, y diecinueve transferencias de 50,000 seguidas de una pequeña la cumplen.

**2. Haz el backtest contra tu historial**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "period_days": 90
  }'
```

```json theme={null}
{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }
```

Un recuento de `matched` inesperado significa que hay que ajustar los umbrales antes de que la regla pueda actuar sobre nada.

> [!WARNING]
>
> Haz el backtest con las opciones **exactas** que vas a activar: los mismos `conditions`, `aggregation`, `evaluation_mode` y `scope`. Si omites `conditions`, `aggregation` y `scope`, no añaden restricciones propias; prescindir del scope puede incluir sentidos o tipos de transacción que la regla guardada omite. Si omites `evaluation_mode`, toma `ALL` por defecto, así que omitirlo en una regla `ANY` puede reducir las coincidencias. Si omites `period_days`, toma 90 días por defecto; no selecciona un historial ilimitado.

**3. Activa la regla**

```bash theme={null}
curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "ACTIVE"}'
```

La regla se aplica de inmediato a todas las transacciones nuevas de una aplicación **en producción**.

> [!WARNING]
>
> Las aplicaciones de sandbox nunca evalúan reglas. Una transacción de sandbox se
> almacena y nada más, por lo que activar una regla en una aplicación de sandbox no cambia
> nada que puedas observar. El backtest es la forma admitida de probar una regla antes de
> pasarla a producción; consulta [Monitorización de transacciones en sandbox](https://docs.didit.me/es/integration/sandbox-testing.md#monitorización-de-transacciones-en-sandbox).

## Migrar reglas desde otro proveedor

Como la creación de reglas es una simple llamada a la API con un esquema totalmente documentado, un asistente de IA puede convertir por ti la exportación de reglas de otro proveedor en reglas de Didit.

1. **Exporta** tus reglas desde el proveedor actual: la mayoría de las herramientas exportan a CSV o Excel.
2. **Suelta el archivo** en el asistente de la consola de Didit (o en cualquier agente conectado por MCP, como Claude con el [MCP de Didit](https://docs.didit.me/es/integration/mcp/overview.md) añadido). Las hojas de cálculo se convierten a texto automáticamente.
3. El asistente **asigna cada fila** al esquema de Didit (condiciones, ventanas de velocidad, acciones) y te muestra esa correspondencia, señalando todo lo que no tiene equivalente en Didit, antes de crear nada.
4. Cuando le das el visto bueno, **crea las reglas en modo TEST**, hace un backtest con tu propio historial de transacciones e informa de las filas creadas, fallidas y sin correspondencia.
5. **Revisa las cifras y activa** las reglas que te parezcan correctas, desde la consola o con un `PATCH {"mode": "ACTIVE"}`.

Una exportación de un proveedor como esta:

```csv theme={null}
Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline
```

se convierte en reglas como estas:

```json theme={null}
{
  "title": "Structuring - Small Transfers",
  "description": "20+ outbound EUR transfers, all under 10,000 EUR, 30 days",
  "category": "finance",
  "mode": "TEST",
  "evaluation_mode": "ALL",
  "scope": {
    "transaction_types": ["finance"],
    "directions": ["OUTBOUND"]
  },
  "conditions": [
    {"field": "currency", "operator": "eq", "value": "EUR"},
    {"field": "amount", "operator": "lt", "value": 10000}
  ],
  "aggregation": [
    {
      "metric": "count", "operator": "gte", "value": 20,
      "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    },
    {
      "metric": "max", "field": "amount",
      "operator": "lt", "value": 10000, "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    }
  ],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}
```

La fila del CSV indica una dirección y una divisa, así que ambas mitades de la regla las incluyen: `scope` y `conditions` limitan la transacción evaluada a una transferencia saliente en EUR inferior a 10,000, y los filtros de agregación limitan la ventana de 30 días a las transferencias salientes en EUR de ese mismo sujeto. El `amount` sin normalizar solo es comparable dentro de una misma divisa: mantén la divisa fijada como se muestra arriba. Un límite entre divisas requiere un importe normalizado para cada transacción de la ventana. Cambiar solo a `preferred_currency_amount` no garantiza su disponibilidad: las agregaciones numéricas pueden tratar como cero los importes normalizados históricos que falten.

La entrada `max` es lo que mantiene la ventana por debajo de 10,000 EUR, porque un filtro de agregación no puede expresar *inferior a 10,000*; consulta la nota del [paso de creación](#crear-hacer-backtest-y-activar) más arriba para ver la contrapartida que implica. Conviene dejar explícito en la `description` de la regla todo lo que el esquema no pueda expresar con exactitud, en lugar de aproximarlo en silencio.

> [!TIP]
>
> Antes de recrear como personalizada una regla de un proveedor, consulta la [biblioteca de reglas](https://docs.didit.me/es/management-api/transactions/rules-library.md): Didit incluye 150+ ajustes predefinidos que cubren las tipologías habituales (fraccionamiento, velocidad, exposición a sanciones, reutilización de dispositivos, riesgo cripto), e instalar uno requiere una sola llamada a la API.

## Los errores de validación son precisos a propósito

Los endpoints de creación y actualización validan los valores de condiciones, agregación y alcance exactamente según lo que acepta el motor de reglas: operadores o métricas desconocidos, ventanas mal formadas (`"30days"` en lugar de `"30d"`), direcciones no válidas en el alcance, `contains_any` sin una lista, `fuzzy_match` sin un `score` y `change_status` con `AWAITING_USER` sin un `workflow_id` devuelven un `400` que indica el índice y el problema, en lugar de guardar una regla que nunca coincide sin avisar. Los agentes y scripts deben leer el cuerpo del error y corregir el payload. Las claves de alcance adicionales a `transaction_types`, `directions` y `action_types` se guardan, pero el motor las ignora, igual que la Business Console siempre las ha guardado.

## Próximos pasos

> [card] [Reglas y puntuación](https://docs.didit.me/es/transaction-monitoring/rules.md)
>
> El esquema completo de reglas: campos, operadores, ventanas de velocidad y acciones.

> [card] [API para crear reglas](https://docs.didit.me/es/management-api/transactions/rules-create.md)
>
> Referencia del endpoint con los esquemas de solicitud y respuesta.

> [card] [Biblioteca de reglas](https://docs.didit.me/es/transaction-monitoring/rules-library.md)
>
> El catálogo de 150+ ajustes predefinidos y sus paquetes.

> [card] [Visión general de MCP](https://docs.didit.me/es/integration/mcp/overview.md)
>
> Conecta un agente de IA a tu espacio de trabajo de Didit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.