> ## 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 regles i MCP - Gestió programàtica de regles KYT

> Crea, ajusta, fes backtest i migra regles KYT per programa amb Didit: endpoints de l'API de gestió, eines MCP i flux crear-backtest-activar.

Totes les funcionalitats de regles de la Consola empresarial també estan disponibles de forma programàtica: a través de la **Management API** amb la teva clau d'API de l'aplicació, i a través del **Didit MCP** per a agents d'IA que actuen com a usuari de la consola amb la sessió iniciada. Fes-les servir per gestionar regles des del codi, mantenir els conjunts de regles al control de versions o deixar que un assistent d'IA construeixi i migri regles per tu.

## Quina superfície cal utilitzar en cada cas

| Superfície | Autenticació | Ideal per a |
| - | - | - |
| **Consola empresarial** | Inici de sessió a la consola | Revisió humana de cada canvi; construcció visual de regles i backtesting |
| **Management API** | `x-api-key` | Automatització des del teu backend, conjunts de regles en codi, desplegaments de regles gestionats amb CI |
| **Didit MCP** | Inicia sessió amb Didit (OAuth) | Assistents i agents d'IA: el Copilot de la consola de Didit, Claude, Cursor o qualsevol client MCP |

## Els endpoints

| Endpoint | Finalitat |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/ca/management-api/transactions/rules-list) | Llista les regles amb filtres i ordenació per rendiment |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/ca/management-api/transactions/rules-create) | Crea una regla personalitzada |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ca/management-api/transactions/rules-get) | Llegeix una regla amb els comptadors d'execució |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ca/management-api/transactions/rules-update) | Actualitza una regla personalitzada; canvia el mode de qualsevol regla |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ca/management-api/transactions/rules-delete) | Elimina una regla personalitzada (permanentment) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/ca/management-api/transactions/rules-backtest) | Avalua una regla hipotètica amb el teu historial |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/ca/management-api/transactions/rules-library) | Explora la biblioteca de 150+ regles predefinides amb l'estat d'instal·lació |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/ca/management-api/transactions/rules-install) | Instal·la regles predefinides per clau, per paquet o per la intersecció de tots dos |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/ca/management-api/transactions/rules-uninstall) | Desinstal·la regles predefinides per clau, per paquet o per la intersecció de tots dos |

Les eines MCP corresponents són `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` i `didit_transaction_rule_uninstall`: consulta la [referència d'eines MCP](https://docs.didit.me/ca/integration/mcp/tools.md).

L'esquema complet (el catàleg de camps, els 19 operadors de condició, les finestres de velocitat, les condicions agrupades i els sis tipus d'acció) està documentat a la pàgina [Regles i puntuació](https://docs.didit.me/ca/transaction-monitoring/rules.md) i inclòs a la referència de l'API.

## Crear, fer backtest i activar

El patró de desplegament segur per a qualsevol regla nova:

**1. Crea la regla en mode 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}]
  }'
```

Llegeix el payload en dues meitats. `scope` i `conditions` descriuen **la transacció que s'avalua**: una transacció financera entrant en EUR amb un `amount` brut inferior a 10.000. Les entrades de `aggregation` descriuen **la finestra de 30 dies per al mateix subjecte**: almenys 20 transaccions financeres entrants en EUR, i cap d'elles de 10.000 EUR o més. Totes dues entrades d'agregació s'han de complir, independentment del que digui `evaluation_mode`: aquesta configuració només regeix les condicions.

Aquest exemple fa servir `amount` brut i fixa `currency` a EUR en totes dues meitats, de manera que no depèn de la normalització del tipus de canvi. Per fer backtest amb dades de prova del sandbox, envia almenys 20 transaccions financeres entrants en EUR per al mateix subjecte dins de 30 dies, cadascuna amb `amount` inferior a 10.000. No cal ni `preferred_currency_amount` ni `amount_in_default_currency`. La ingestió al sandbox emmagatzema aquestes transaccions; executa el backtest de manera explícita.

Una regla `TEST` s'avalua en cada transacció nova i registra les coincidències que hauria produït, però mai no modifica la puntuació ni l'estat de la transacció.

> [!NOTE]
>
> **Un filtre d'agregació no és una condició.** Una condició només llegeix la transacció que s'avalua; un filtre d'agregació només restringeix la finestra històrica, i compara per igualtat o per pertinença a una llista. No hi ha cap filtre `lt`, de manera que no pots comptar **només les transferències inferiors a 10.000**.
>
> L'entrada `max ... lt 10000` és la manera admesa de posar un sostre a la finestra: exigeix que **cada** transacció de la finestra sigui inferior a 10.000, cosa més estricta que comptar només les petites. Una sola transferència de 12.000 entre les vint impedeix que la regla s'activi. Elimina aquesta entrada si prefereixes que el recompte es consideri per si sol, i aleshores digues-ho al títol: sense ella, la regla compta transferències entrants de qualsevol mida, i la regla coincidirà amb dinou transferències de 50.000 seguides d'una de petita.

**2. Fes backtest contra el teu 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 recompte `matched` sorprenent indica que els llindars s'han d'ajustar abans que la regla pugui actuar sobre cap transacció.

> [!WARNING]
>
> Fes backtest de la configuració **exacta** que estàs a punt d'activar: els mateixos `conditions`, `aggregation`, `evaluation_mode` i `scope`. Els `conditions`, `aggregation` i `scope` omesos no afegeixen restriccions pròpies; si n'elimines l'scope, es poden incloure direccions o tipus de transacció que la regla desada ignora. Si `evaluation_mode` s'omet, el valor per defecte és `ALL`, de manera que ometre'l en una regla `ANY` pot reduir les coincidències. Si `period_days` s'omet, el valor per defecte és de 90 dies; no selecciona un historial sense límit.

**3. Activa**

```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 s'aplica immediatament a totes les transaccions noves d'una aplicació **en producció**.

> [!WARNING]
>
> Les aplicacions de sandbox mai no avaluen regles. Una transacció de sandbox només s'emmagatzema, i res més, de manera que activar una regla en una aplicació de sandbox no canvia res que puguis observar. El backtest és la manera admesa de provar una regla abans que entri en producció: consulta [Monitoratge de transaccions en sandbox](https://docs.didit.me/ca/integration/sandbox-testing.md#monitoratge-de-transaccions-en-sandbox).

## Migrar regles d'un altre proveïdor

Com que la creació de regles és una simple crida d'API amb un esquema totalment documentat, un assistent d'IA pot convertir l'exportació de regles d'un altre proveïdor en regles de Didit per a tu.

1. **Exporta** les regles del proveïdor actual. La majoria d'eines exporten a CSV o Excel.
2. **Puja el fitxer** a l'assistent de la consola de Didit (o a qualsevol agent connectat per MCP, com Claude amb el [MCP de Didit](https://docs.didit.me/ca/integration/mcp/overview.md) afegit). Els fulls de càlcul es converteixen automàticament a text.
3. L'assistent **mapeja cada fila** a l'esquema de Didit (condicions, finestres de velocitat, accions) i et mostra el mapeig, indicant qualsevol cosa que no tingui equivalent a Didit, abans de crear res.
4. Amb la teva confirmació, **crea les regles en mode TEST**, fa un backtest amb el teu historial de transaccions i informa de les files creades, fallides i no mapejables.
5. **Revisa els números i activa** les regles que semblin correctes, des de la consola o amb un `PATCH {"mode": "ACTIVE"}`.

Una exportació d'un proveïdor com aquesta:

```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
```

es converteix en regles com aquestes:

```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ó i una divisa, així que les dues meitats de la regla les contenen: `scope` i `conditions` fixen la transacció avaluada a una transferència EUR sortint inferior a 10.000, i els filtres d'agregació fixen la finestra de 30 dies a les transferències EUR sortints d'aquest mateix subjecte. L'`amount` brut només és comparable dins d'una mateixa divisa, per això cal mantenir la divisa fixada tal com s'ha indicat. Un topall entre divises requereix un import normalitzat per a cada transacció de la finestra. Canviar només a `preferred_currency_amount` no garanteix la disponibilitat: els imports normalitzats històrics que falten poden tractar-se com a zero en les agregacions numèriques.

L'entrada `max` és la que manté la finestra per sota de 10.000 EUR, perquè un filtre d'agregació no pot expressar *per sota de 10.000*. Consulta la nota del [pas de creació](#crear-fer-backtest-i-activar) de més amunt per veure el compromís que comporta. Qualsevol cosa que l'esquema no pugui expressar exactament convé dir-la explícitament a la `description` de la regla, en lloc d'aproximar-la sense avisar.

> [!TIP]
>
> Abans de recrear una regla d'un proveïdor com a personalitzada, consulta la [biblioteca de regles](https://docs.didit.me/ca/management-api/transactions/rules-library.md). Didit inclou 150+ preconfiguracions que cobreixen les tipologies habituals (estructuració, velocitat, exposició a sancions, reutilització de dispositiu, risc cripto), i instal·lar-ne una és una sola crida.

## Els errors de validació són precisos a propòsit

Els endpoints de creació i actualització validen les condicions, l'agregació i els valors de l'abast amb exactitud segons el que accepta el motor de regles. Els operadors o mètriques desconeguts, les finestres mal formades (`"30days"` en lloc de `"30d"`), les direccions d'abast no vàlides, `contains_any` sense llista, `fuzzy_match` sense `score` i `change_status` a `AWAITING_USER` sense `workflow_id` retornen un `400` que indica l'índex i el problema, en lloc d'emmagatzemar una regla que mai no coincideix sense avisar. Els agents i els scripts han de llegir el cos de l'error i corregir el payload. Les claus d'abast addicionals, més enllà de `transaction_types`, `directions` i `action_types`, s'emmagatzemen però el motor les ignora, igual que la Business Console les ha desat sempre.

## Següents passos

> [card] [Regles i puntuació](https://docs.didit.me/ca/transaction-monitoring/rules.md)
>
> L'esquema complet de regles: camps, operadors, finestres de velocitat i accions.

> [card] [API de creació de regles](https://docs.didit.me/ca/management-api/transactions/rules-create.md)
>
> Referència de l'endpoint amb els esquemes de sol·licitud i resposta.

> [card] [Biblioteca de regles](https://docs.didit.me/ca/transaction-monitoring/rules-library.md)
>
> El catàleg de 150+ preconfiguracions i els seus paquets.

> [card] [Visió general de MCP](https://docs.didit.me/ca/integration/mcp/overview.md)
>
> Connecta un agent d'IA al teu espai de treball de Didit.


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