> ## 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 des règles KYT et MCP : gestion programmatique

> Didit : créez, ajustez, testez et migrez vos règles KYT par programmation, via l'API de gestion, les outils MCP et le workflow créer - tester - activer.

Toutes les fonctionnalités de règles de la Console Business sont aussi disponibles par programmation : via la **Management API** avec votre clé API d'application, et via le **Didit MCP** pour les agents IA agissant en tant qu'utilisateur connecté à la console. Utilisez-les pour gérer les règles depuis du code, conserver les ensembles de règles dans un système de gestion de versions, ou laisser un assistant IA créer et migrer les règles à votre place.

## Quand utiliser quelle surface

| Surface | Authentification | Idéal pour |
| - | - | - |
| **Console Business** | Connexion à la console | Revue humaine de chaque modification ; création visuelle de règles et backtesting |
| **Management API** | `x-api-key` | Automatisation depuis votre backend, ensembles de règles en code, déploiements de règles gérés par CI |
| **Didit MCP** | Connexion avec Didit (OAuth) | Assistants et agents IA : le Copilot de la console Didit, Claude, Cursor, ou tout client MCP |

## Les endpoints

| Endpoint | Rôle |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/fr/management-api/transactions/rules-list) | Lister les règles avec filtres et tri par performance |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/fr/management-api/transactions/rules-create) | Créer une règle personnalisée |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/fr/management-api/transactions/rules-get) | Lire une règle avec ses compteurs d'exécution |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/fr/management-api/transactions/rules-update) | Modifier une règle personnalisée ; changer le mode de n'importe quelle règle |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/fr/management-api/transactions/rules-delete) | Supprimer une règle personnalisée (suppression définitive) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/fr/management-api/transactions/rules-backtest) | Évaluer une règle hypothétique sur votre historique |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/fr/management-api/transactions/rules-library) | Parcourir la bibliothèque de 150+ préréglages avec leur statut d'installation |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/fr/management-api/transactions/rules-install) | Installer des préréglages par clé, par lot ou par intersection des deux |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/fr/management-api/transactions/rules-uninstall) | Désinstaller des préréglages par clé, par lot ou par intersection des deux |

Les outils MCP correspondants sont `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` et `didit_transaction_rule_uninstall` - voir la [référence des outils MCP](https://docs.didit.me/fr/integration/mcp/tools.md).

Le schéma complet - le catalogue des champs, les 19 opérateurs de condition, les fenêtres de vélocité, les conditions groupées et les six types d'action - est documenté sur la page [Règles et notation](https://docs.didit.me/fr/transaction-monitoring/rules.md) et intégré à la référence de l'API.

## Créer, backtester, activer

Le schéma de déploiement sûr pour toute nouvelle règle :

**1. Créer la règle 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}]
  }'
```

Lisez le payload en deux parties. `scope` et `conditions` décrivent **la transaction évaluée** : une transaction financière entrante en EUR avec un `amount` brut inférieur à 10 000. Les entrées `aggregation` décrivent **la fenêtre de 30 jours pour le même sujet** : au moins 20 transactions financières entrantes en EUR, et dont aucune ne s'élève à 10 000 EUR ou plus. Les deux entrées d'agrégation doivent être satisfaites, quelle que soit la valeur de `evaluation_mode` : ce paramètre ne s'applique qu'aux conditions.

Cet exemple utilise le `amount` brut et fixe `currency` à EUR dans les deux parties, si bien qu'il ne dépend pas de la normalisation des taux de change. Pour backtester des jeux de données de test de la sandbox, soumettez au moins 20 transactions financières entrantes en EUR pour le même sujet dans un délai de 30 jours, chacune avec un `amount` inférieur à 10 000. Ni `preferred_currency_amount` ni `amount_in_default_currency` ne sont requis. L'ingestion en sandbox enregistre ces transactions ; lancez le backtest explicitement.

Une règle `TEST` évalue chaque nouvelle transaction et enregistre les correspondances qu'elle aurait trouvées, mais ne modifie jamais le score ni le statut de la transaction.

> [!NOTE]
>
> **Un filtre d'agrégation n'est pas une condition.** Une condition ne lit que la transaction évaluée ; un filtre d'agrégation ne fait que restreindre la fenêtre historique, et il compare par égalité ou par appartenance à une liste. Il n'existe pas de filtre `lt`, donc vous ne pouvez pas compter *uniquement les virements inférieurs à 10 000*.
>
> L'entrée `max ... lt 10000` est la manière prise en charge de plafonner la fenêtre : elle exige que **chaque** transaction de la fenêtre soit inférieure à 10 000, ce qui est plus strict que de ne compter que les petites. Un seul virement de 12 000 parmi les vingt empêche la règle de se déclencher. Supprimez cette entrée si vous préférez que le comptage se suffise à lui-même, et indiquez-le alors dans le titre : sans elle, la règle compte les virements entrants de toute taille, et dix-neuf virements de 50 000 suivis d'un seul petit virement la satisfont.

**2. Backtester sur votre historique**

```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 nombre `matched` inattendu signifie que les seuils doivent être ajustés avant que la règle puisse agir.

> [!WARNING]
>
> Backtestez la configuration **exacte** que vous allez activer : les mêmes `conditions`, `aggregation`, `evaluation_mode` et `scope`. Les `conditions`, `aggregation` et `scope` omis n'ajoutent aucune contrainte propre ; supprimer le scope peut inclure des directions ou des types de transaction que la règle enregistrée ignore. Un `evaluation_mode` omis prend la valeur `ALL` par défaut, donc l'omettre pour une règle `ANY` peut réduire le nombre de correspondances. Un `period_days` omis vaut 90 jours par défaut ; cela ne sélectionne pas un historique illimité.

**3. Activer**

```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 règle s'applique immédiatement à toutes les nouvelles transactions d'une application **en production**.

> [!WARNING]
>
> Les applications sandbox n'évaluent jamais de règles. Une transaction sandbox est simplement enregistrée, sans plus, donc activer une règle sur une application sandbox ne change rien que vous puissiez observer. Le backtest est la manière prise en charge de tester une règle avant sa mise en production - voir [Surveillance des transactions en sandbox](https://docs.didit.me/fr/integration/sandbox-testing.md#transaction-monitoring-in-sandbox).

## Migrer les règles depuis un autre fournisseur

Comme la création de règles est un simple appel d'API dont le schéma est entièrement documenté, un assistant IA peut traduire pour vous un export des règles d'un autre fournisseur en règles Didit.

1. **Exporter** vos règles auprès de votre fournisseur actuel : la plupart des outils exportent au format CSV ou Excel.
2. **Déposez le fichier** dans l'assistant de la console Didit (ou dans n'importe quel agent connecté à MCP, comme Claude, avec le [Didit MCP](https://docs.didit.me/fr/integration/mcp/overview.md) activé). Les feuilles de calcul sont converties automatiquement en texte.
3. L'assistant **associe chaque ligne** au schéma Didit (conditions, fenêtres de vélocité, actions) et vous présente la correspondance, en signalant tout élément sans équivalent Didit, avant de créer quoi que ce soit.
4. Après votre accord, il **crée les règles en mode TEST**, les soumet à un backtest sur votre propre historique de transactions, et indique les lignes créées, en échec et non convertibles.
5. **Vérifiez les chiffres et activez** les règles qui semblent correctes, depuis la console ou avec un `PATCH {"mode": "ACTIVE"}`.

Un export de fournisseur de ce type :

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

devient des règles de ce type :

```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 ligne CSV indique une direction et une devise, donc les deux parties de la règle les portent : `scope` et `conditions` limitent la transaction évaluée à un virement sortant en EUR inférieur à 10 000, et les filtres d'agrégation limitent la fenêtre de 30 jours aux virements sortants en EUR du même sujet. Le `amount` brut n'est comparable qu'au sein d'une même devise : conservez la devise figée comme ci-dessus. Un plafond multidevise exige un montant normalisé pour chaque transaction de la fenêtre. Passer à `preferred_currency_amount` seul ne garantit pas la disponibilité : les montants normalisés historiques manquants peuvent être traités comme zéro par les agrégations numériques.

L'entrée `max` est ce qui maintient la fenêtre sous 10 000 EUR, car un filtre d'agrégation ne peut pas exprimer *inférieur à 10 000* : voir la note sur l'[étape de création](#créer-backtester-activer) ci-dessus pour le compromis qu'elle implique. Tout ce que le schéma ne peut pas exprimer exactement mérite d'être signalé explicitement dans la `description` de la règle plutôt que d'être approximé en silence.

> [!TIP]
>
> Avant de recréer la règle d'un fournisseur sous forme personnalisée, consultez la [bibliothèque de règles](https://docs.didit.me/fr/management-api/transactions/rules-library.md) : Didit fournit 150+ préréglages couvrant les typologies courantes (structuration, vélocité, exposition aux sanctions, réutilisation d'appareils, risque crypto), et installer un préréglage ne demande qu'un seul appel.

## Les erreurs de validation sont volontairement précises

Les endpoints de création et de mise à jour valident les valeurs des conditions, de l'agrégation et du scope par rapport à ce que le moteur de règles accepte exactement : opérateurs ou métriques inconnus, fenêtres mal formées (`"30days"` au lieu de `"30d"`), directions de scope invalides, `contains_any` sans liste, `fuzzy_match` sans `score`, et `change_status` vers `AWAITING_USER` sans `workflow_id` renvoient tous un `400` qui indique l'index et le problème, au lieu d'enregistrer une règle qui ne correspondrait silencieusement jamais. Les agents et les scripts doivent lire le corps de l'erreur et corriger le payload. Les clés de scope supplémentaires au-delà de `transaction_types`, `directions` et `action_types` sont enregistrées mais ignorées par le moteur, comme la Business Console les a toujours enregistrées.

## Prochaines étapes

> [card] [Règles et notation](https://docs.didit.me/fr/transaction-monitoring/rules.md)
>
> Le schéma complet des règles : champs, opérateurs, fenêtres de vélocité, actions.

> [card] [API de création de règles](https://docs.didit.me/fr/management-api/transactions/rules-create.md)
>
> Référence de l'endpoint avec les schémas de requête et de réponse.

> [card] [Bibliothèque de règles](https://docs.didit.me/fr/transaction-monitoring/rules-library.md)
>
> Le catalogue des 150+ préréglages et ses ensembles.

> [card] [Vue d'ensemble de MCP](https://docs.didit.me/fr/integration/mcp/overview.md)
>
> Connectez un agent IA à votre espace de travail Didit.


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