API de regles i MCP - Gestió programàtica de regles KYT

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/`	Llista les regles amb filtres i ordenació per rendiment
`POST /v3/transactions/rules/`	Crea una regla personalitzada
`GET /v3/transactions/rules/{rule_uuid}/`	Llegeix una regla amb els comptadors d’execució
`PATCH /v3/transactions/rules/{rule_uuid}/`	Actualitza una regla personalitzada; canvia el mode de qualsevol regla
`DELETE /v3/transactions/rules/{rule_uuid}/`	Elimina una regla personalitzada (permanentment)
`POST /v3/transactions/rules/backtest/`	Avalua una regla hipotètica amb el teu historial
`GET /v3/transactions/rules/library/`	Explora la biblioteca de 150+ regles predefinides amb l’estat d’instal·lació
`POST /v3/transactions/rules/install/`	Instal·la regles predefinides per clau, per paquet o per la intersecció de tots dos
`DELETE /v3/transactions/rules/install/`	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. 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ó 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:

Crea la regla en mode TEST

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

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.

Fes backtest contra el teu historial

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
  }'

{ "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ó.

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.

Activa

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

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.

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.

Exporta les regles del proveïdor actual. La majoria d’eines exporten a CSV o Excel.
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 afegit). Els fulls de càlcul es converteixen automàticament a text.
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.
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.
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:

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:

{
  "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ó 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.

Abans de recrear una regla d’un proveïdor com a personalitzada, consulta la biblioteca de regles. 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

Regles i puntuació

L’esquema complet de regles: camps, operadors, finestres de velocitat i accions.

API de creació de regles

Referència de l’endpoint amb els esquemes de sol·licitud i resposta.

Biblioteca de regles

El catàleg de 150+ preconfiguracions i els seus paquets.

Visió general de MCP

Connecta un agent d’IA al teu espai de treball de Didit.

Primers passos

Funcionalitats

Referència

Consola

API de regles i MCP - Gestió programàtica de regles KYT

Quina superfície cal utilitzar en cada cas

Els endpoints

Crear, fer backtest i activar

Migrar regles d’un altre proveïdor

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

Següents passos

Regles i puntuació

API de creació de regles

Biblioteca de regles

Visió general de MCP

​Quina superfície cal utilitzar en cada cas

​Els endpoints

​Crear, fer backtest i activar

​Migrar regles d’un altre proveïdor

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

​Següents passos

Regles i puntuació

API de creació de regles

Biblioteca de regles

Visió general de MCP

Quina superfície cal utilitzar en cada cas

Els endpoints

Crear, fer backtest i activar

Migrar regles d’un altre proveïdor

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

Següents passos