> ## 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 e MCP per le regole KYT: gestione programmatica

> Crea, ottimizza, esegui il backtest e migra le regole KYT in Didit tramite API di gestione, strumenti MCP e il flusso crea, backtest, attiva.

Ogni funzionalità di regole disponibile nella **Business Console** è accessibile anche in modo programmatico: tramite la **Management API** con la tua chiave API dell'applicazione e tramite il **Didit MCP** per gli agenti AI che operano come utenti della console dopo aver effettuato l'accesso. Usali per gestire le regole dal codice, conservare i set di regole nel controllo di versione o lasciare che un assistente AI crei e migri le regole per te.

## Quando usare quale superficie

| Superficie | Autenticazione | Ideale per |
| - | - | - |
| **Business Console** | Accesso alla console | Revisione manuale di ogni modifica; creazione visiva delle regole e backtest |
| **Management API** | `x-api-key` | Automazione dal tuo backend, set di regole nel codice, deployment delle regole gestiti da CI |
| **Didit MCP** | Accesso con Didit (OAuth) | Assistenti AI e agenti: il Copilot della console Didit, Claude, Cursor o qualsiasi client MCP |

## Gli endpoint

| Endpoint | Scopo |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/it/management-api/transactions/rules-list) | Elenca le regole con filtri e ordinamento per prestazioni |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/it/management-api/transactions/rules-create) | Crea una regola personalizzata |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/it/management-api/transactions/rules-get) | Leggi una regola con i contatori di esecuzione |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/it/management-api/transactions/rules-update) | Aggiorna una regola personalizzata; cambia la modalità di qualsiasi regola |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/it/management-api/transactions/rules-delete) | Elimina una regola personalizzata (in modo permanente) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/it/management-api/transactions/rules-backtest) | Valuta una regola ipotetica sulla tua cronologia |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/it/management-api/transactions/rules-library) | Sfoglia la libreria di 150+ preset con lo stato di installazione |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/it/management-api/transactions/rules-install) | Installa preset per chiave, bundle o intersezione dei due |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/it/management-api/transactions/rules-uninstall) | Disinstalla preset per chiave, bundle o intersezione dei due |

Gli strumenti MCP corrispondenti sono `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` e `didit_transaction_rule_uninstall` - vedi il [riferimento degli strumenti MCP](https://docs.didit.me/it/integration/mcp/tools.md).

Lo schema completo - il catalogo dei campi, tutti i 19 operatori di condizione, le finestre di velocità, le condizioni raggruppate e i sei tipi di azione - è documentato nella pagina [Rules & Scoring](https://docs.didit.me/it/transaction-monitoring/rules.md) ed è incluso nel riferimento API.

## Creare, testare con backtest, attivare

Il modello di rilascio sicuro per qualsiasi nuova regola:

**1. Crea la regola in modalità 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}]
  }'
```

Leggi il payload in due parti. `scope` e `conditions` descrivono **la transazione valutata**: una transazione finanziaria in entrata in EUR con un `amount` grezzo inferiore a 10.000. Le voci di `aggregation` descrivono **la finestra di 30 giorni per lo stesso soggetto**: almeno 20 transazioni finanziarie in entrata in EUR e nessuna di 10.000 EUR o più. Entrambe le voci di aggregazione devono essere soddisfatte, indipendentemente da ciò che indica `evaluation_mode` - questa impostazione regola solo le condizioni.

Questo esempio usa `amount` grezzo e fissa `currency` a EUR in entrambe le parti, quindi non dipende dalla normalizzazione dei cambi. Per fare il backtest sui fixture della sandbox, invia almeno 20 transazioni finanziarie in entrata in EUR per lo stesso soggetto entro 30 giorni, ciascuna con `amount` inferiore a 10.000. Né `preferred_currency_amount` né `amount_in_default_currency` sono obbligatori. L'acquisizione in sandbox salva queste transazioni; esegui il backtest in modo esplicito.

Una regola `TEST` viene valutata su ogni nuova transazione e registra quali transazioni avrebbe intercettato, ma non modifica mai il punteggio o lo stato della transazione.

> [!NOTE]
>
> **Un filtro di aggregazione non è una condizione.** Una condizione legge solo la transazione valutata; un filtro di aggregazione restringe solo la finestra storica e confronta per uguaglianza o appartenenza a una lista - non esiste un filtro `lt`, quindi non puoi contare *solo i trasferimenti sotto 10.000*.
>
> La voce `max ... lt 10000` è il modo supportato per porre un limite massimo alla finestra: richiede che **ogni** transazione nella finestra sia inferiore a 10.000, il che è più restrittivo che contare solo quelle piccole - un trasferimento da 12.000 tra i venti impedisce alla regola di scattare. Elimina quella voce se preferisci che il conteggio stia da solo, e in tal caso dillo nel titolo: senza di essa la regola conta i trasferimenti in entrata di qualsiasi importo, e diciannove trasferimenti da 50.000 seguiti da uno piccolo la fanno scattare.

**2. Testa con backtest sulla tua cronologia**

```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 conteggio `matched` sorprendente significa che le soglie vanno ottimizzate prima che la regola possa produrre effetti.

> [!WARNING]
>
> Esegui il backtest sulla configurazione **esatta** che stai per attivare: gli stessi `conditions`, `aggregation`, `evaluation_mode` e `scope`. Se ometti `conditions`, `aggregation` e `scope`, questi non aggiungono vincoli propri; eliminare lo scope può includere direzioni o tipi di transazione che la regola salvata ignora. Se ometti `evaluation_mode`, il valore predefinito è `ALL`, quindi ometterlo per una regola `ANY` può ridurre i match. Se ometti `period_days`, il valore predefinito è 90 giorni; non seleziona una cronologia illimitata.

**3. Attiva**

```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 regola si applica immediatamente a tutte le nuove transazioni di un'applicazione di produzione.

> [!WARNING]
>
> Le applicazioni sandbox non valutano mai le regole. Una transazione sandbox viene solo salvata, senza altro effetto, quindi attivare una regola su un'applicazione sandbox non cambia nulla che tu possa osservare. Il backtest è il modo supportato per testare una regola prima che vada in produzione - vedi [Monitoraggio delle transazioni in sandbox](https://docs.didit.me/it/integration/sandbox-testing.md#monitoraggio-delle-transazioni-nella-sandbox).

## Migrazione delle regole da un altro provider

Poiché la creazione di una regola è una semplice chiamata API con uno schema completamente documentato, un assistente AI può tradurre l'esportazione delle regole di un altro provider in regole Didit al posto tuo.

1. **Esporta** le regole dal provider attuale: la maggior parte degli strumenti esporta in CSV o Excel.
2. **Trascina il file** nell'assistente della console Didit (oppure in qualsiasi agente collegato tramite MCP, come Claude con il [Didit MCP](https://docs.didit.me/it/integration/mcp/overview.md) collegato). I fogli di calcolo vengono convertiti automaticamente in testo.
3. L'assistente **associa ogni riga** allo schema Didit (condizioni, finestre di frequenza, azioni) e ti mostra la corrispondenza, segnalando qualsiasi elemento che non ha un equivalente in Didit, prima di creare qualsiasi cosa.
4. Dopo la tua conferma **crea le regole in modalità TEST**, le sottopone a backtest sulla tua cronologia delle transazioni e riporta le righe create correttamente, quelle la cui creazione è fallita e quelle non associabili.
5. **Verifica i numeri e attiva** le regole che ti sembrano corrette, dalla console oppure con un `PATCH {"mode": "ACTIVE"}`.

Un'esportazione del provider come questa:

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

diventa regole come questa:

```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 riga CSV indica una direzione e una valuta, quindi entrambe le parti della regola le riportano: `scope` e `conditions` vincolano la transazione valutata a un trasferimento in uscita in EUR inferiore a 10.000, e i filtri di aggregazione vincolano la finestra di 30 giorni agli stessi trasferimenti in uscita in EUR dello stesso soggetto. L'`amount` grezzo è confrontabile solo all'interno di una stessa valuta, quindi mantieni la valuta vincolata come sopra. Un tetto multivaluta richiede un importo normalizzato per ogni transazione nella finestra. Passare solo a `preferred_currency_amount` non garantisce la disponibilità: gli importi normalizzati storici mancanti possono essere trattati come zero dalle aggregazioni numeriche.

La voce `max` è ciò che mantiene la finestra sotto 10.000 EUR, perché un filtro di aggregazione non può esprimere *inferiore a 10.000*: vedi la nota sul [passaggio di creazione](#creare-testare-con-backtest-attivare) sopra per il compromesso che comporta. Qualsiasi elemento che lo schema non può esprimere in modo esatto va dichiarato esplicitamente nella `description` della regola, anziché approssimato in silenzio.

> [!TIP]
>
> Prima di ricreare come personalizzata una regola di un provider, controlla la [libreria di regole](https://docs.didit.me/it/management-api/transactions/rules-library.md): Didit offre 150+ preset che coprono le tipologie più comuni (frazionamento, frequenza, esposizione a sanzioni, riutilizzo del dispositivo, rischio legato alle criptovalute), e installare un preset richiede una sola chiamata.

## Gli errori di validazione sono volutamente precisi

Gli endpoint di creazione e aggiornamento validano i valori di condizioni, aggregazione e scope in base a ciò che il motore delle regole accetta esattamente: operatori o metriche sconosciuti, finestre malformate (`"30days"` invece di `"30d"`), direzioni di scope non valide, `contains_any` senza una lista, `fuzzy_match` senza un `score`, e `change_status` verso `AWAITING_USER` senza un `workflow_id` restituiscono tutti un `400` che indica l'indice e il problema, invece di salvare una regola che non corrisponde mai senza segnalazioni. Agenti e script devono leggere il corpo dell'errore e correggere il payload. Le chiavi di scope extra oltre a `transaction_types`, `directions` e `action_types` vengono salvate ma ignorate dal motore, come le ha sempre salvate la Business Console.

## Passaggi successivi

> [card] [Regole e punteggio](https://docs.didit.me/it/transaction-monitoring/rules.md)
>
> Lo schema completo delle regole: campi, operatori, finestre di frequenza, azioni.

> [card] [API per la creazione delle regole](https://docs.didit.me/it/management-api/transactions/rules-create.md)
>
> Documentazione di riferimento degli endpoint con gli schemi di richiesta e risposta.

> [card] [Libreria delle regole](https://docs.didit.me/it/transaction-monitoring/rules-library.md)
>
> Il catalogo di 150+ preset e i suoi pacchetti.

> [card] [Panoramica di MCP](https://docs.didit.me/it/integration/mcp/overview.md)
>
> Collega un agente AI al tuo spazio di lavoro Didit.


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