API правил KYT и MCP: программное управление правилами мониторинга транзакций

Все возможности правил Бизнес-консоли также доступны программно: через Management API с API-ключом вашего приложения и через Didit MCP для AI-агентов, которые действуют от имени вошедшего в консоль пользователя. Используйте их, чтобы управлять правилами из кода, хранить наборы правил в системе контроля версий или поручить AI-ассистенту создавать правила и переносить их за вас.

Когда использовать каждую поверхность

Поверхность	Аутентификация	Лучше всего подходит для
Бизнес-консоль	Вход в консоль	Ручная проверка каждого изменения; визуальное построение правил и бэктест
Management API	`x-api-key`	Автоматизация из вашего бэкенда, наборы правил в коде, развертывание правил через CI
Didit MCP	Вход через Didit (OAuth)	AI-ассистенты и агенты: Copilot консоли Didit, Claude, Cursor или любой MCP-клиент

Эндпоинты

Эндпоинт	Назначение
`GET /v3/transactions/rules/`	Список правил с фильтрами и сортировкой по эффективности
`POST /v3/transactions/rules/`	Создание пользовательского правила
`GET /v3/transactions/rules/{rule_uuid}/`	Чтение одного правила со счетчиками выполнения
`PATCH /v3/transactions/rules/{rule_uuid}/`	Обновление пользовательского правила; смена режима любого правила
`DELETE /v3/transactions/rules/{rule_uuid}/`	Удаление пользовательского правила (безвозвратное)
`POST /v3/transactions/rules/backtest/`	Проверка гипотетического правила на вашей истории
`GET /v3/transactions/rules/library/`	Просмотр библиотеки из 150+ пресетов со статусом установки
`POST /v3/transactions/rules/install/`	Установка пресетов по ключу, набору или их пересечению
`DELETE /v3/transactions/rules/install/`	Удаление пресетов по ключу, набору или их пересечению

Соответствующие инструменты MCP: 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 и didit_transaction_rule_uninstall; см. справочник инструментов MCP. Полная схема, включая каталог полей, все 19 операторов условий, окна частотности, группированные условия и шесть типов действий, описана на странице Rules & Scoring и встроена в справочник API.

Создание, бэктест, активация

Безопасная схема выкатки для любого нового правила:

Создайте правило в режиме 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}]
  }'

Прочитайте payload, разделив его на две части. scope и conditions описывают оцениваемую транзакцию: входящую финансовую транзакцию в EUR с сырой amount меньше 10 000. Записи aggregation описывают 30-дневное окно для того же субъекта: не менее 20 входящих финансовых транзакций в EUR, ни одна из которых не составляет 10 000 EUR или больше. Обе записи агрегации должны выполняться независимо от значения evaluation_mode: эта настройка управляет только условиями.В этом примере используется сырая amount, а currency зафиксирована как EUR в обеих частях, поэтому пример не зависит от нормализации курса валют. Чтобы выполнить бэктест на тестовых данных песочницы, отправьте не менее 20 входящих финансовых транзакций в EUR для того же субъекта за 30 дней, каждая с amount меньше 10 000. Ни preferred_currency_amount, ни amount_in_default_currency не обязательны. Приём в песочнице сохраняет эти транзакции; бэктест нужно запустить явно.Правило в режиме TEST оценивает каждую новую транзакцию и фиксирует, с какими транзакциями оно совпало бы, но никогда не меняет оценку или статус транзакции.

Фильтр агрегации не является условием. Условие всегда читает только оцениваемую транзакцию, а фильтр агрегации всегда лишь сужает историческое окно и сравнивает по равенству или по принадлежности к списку. Оператора lt для фильтров нет, поэтому нельзя посчитать только переводы меньше 10 000.Запись max ... lt 10000 является поддерживаемым способом задать верхнюю границу окна: она требует, чтобы каждая транзакция в окне была меньше 10 000, что строже, чем подсчет только мелких транзакций: один перевод на 12 000 среди двадцати не даст правилу сработать. Если вы хотите, чтобы подсчет работал сам по себе, удалите эту запись и укажите это в заголовке: без нее правило считает входящие переводы любого размера, и девятнадцать переводов по 50 000 с одним небольшим в конце дадут совпадение.

Проверьте на своей истории (бэктест)

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 }

Неожиданное значение matched означает, что пороги нужно настроить, прежде чем правило сможет на что-либо влиять.

Проводите бэктест для точной конфигурации, которую собираетесь активировать: те же conditions, aggregation, evaluation_mode и scope. Отсутствующие conditions, aggregation и scope не добавляют собственных ограничений; если убрать scope, могут попасть направления или типы транзакций, которые сохраненное правило пропускает. Отсутствующий evaluation_mode по умолчанию равен ALL, поэтому его отсутствие у правила с ANY может уменьшить число совпадений. Отсутствующий period_days по умолчанию равен 90 дням; это не означает неограниченную историю.

Активируйте

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

Правило сразу применяется ко всем новым транзакциям приложения в продакшн-среде.

В приложениях песочницы правила никогда не оцениваются. Транзакция в песочнице только сохраняется, и больше ничего не происходит, поэтому активация правила в приложении песочницы не меняет ничего, что можно наблюдать. Бэктест является поддерживаемым способом проверить правило до запуска в продакшн; см. Мониторинг транзакций в песочнице.

Миграция правил от другого провайдера

Создание правил представляет собой обычный вызов API с полностью описанной схемой, поэтому ИИ-ассистент может перевести экспорт правил другого провайдера в правила Didit.

Экспортируйте правила у текущего провайдера. Большинство инструментов экспортируют в CSV или Excel.
Перетащите файл в ассистент в консоли Didit или в любой ИИ-агент, подключённый через MCP, например Claude с подключённым Didit MCP. Таблицы автоматически преобразуются в текст.
Ассистент сопоставляет каждую строку со схемой Didit: условия, окна частотности, действия. Он показывает вам это сопоставление и отмечает всё, что не имеет аналога в Didit, прежде чем что-либо создать.
После вашего подтверждения он создаёт правила в режиме TEST, проверяет их на вашей истории транзакций и сообщает, сколько строк создано, сколько не удалось обработать и сколько не удалось сопоставить.
Проверьте показатели и активируйте подходящие правила в консоли или через PATCH {"mode": "ACTIVE"}.

Экспорт от провайдера выглядит так:

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

Он превращается в такие правила:

{
  "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"}
  ]
}

В строке CSV указаны направление и валюта, поэтому обе части правила содержат их: scope и conditions ограничивают оцениваемую транзакцию исходящим переводом в EUR на сумму менее 10,000, а фильтры агрегации ограничивают 30-дневное окно исходящими переводами в EUR того же субъекта. Исходное значение amount можно сравнивать только в пределах одной валюты, поэтому оставляйте валюту зафиксированной, как показано выше. Ограничение в разных валютах требует нормализованной суммы для каждой транзакции в окне. Использование одного только preferred_currency_amount не гарантирует доступность: отсутствующие исторические нормализованные суммы могут считаться нулём в числовых агрегациях. Элемент max удерживает окно ниже 10,000 EUR, поскольку фильтр агрегации не может выразить условие «меньше 10,000». Компромисс описан в примечании к шагу создания выше. Всё, что схема не может выразить точно, лучше явно указать в description правила, чем тихо заменять приближением.

Прежде чем воссоздавать правило провайдера как пользовательское, проверьте библиотеку правил. В Didit есть 150+ пресетов для типовых схем: структурирование, частотность операций, риск санкционных связей, повторное использование устройств, крипториски. Установка пресета выполняется одним вызовом.

Ошибки валидации намеренно точны

Эндпоинты создания и обновления проверяют значения условий, агрегации и области действия строго в соответствии с тем, что принимает движок правил. Неизвестные операторы или метрики, некорректные окна ("30days" вместо "30d"), недопустимые направления в scope, contains_any без списка, fuzzy_match без score, а также change_status на AWAITING_USER без workflow_id возвращают 400 с указанием индекса и проблемы, вместо сохранения правила, которое молча никогда не сработает. Агенты и скрипты должны читать тело ошибки и исправлять payload. Дополнительные ключи в scope, кроме transaction_types, directions и action_types, сохраняются, но движок их игнорирует, так же как Business Console всегда сохраняла их раньше.

Следующие шаги

Правила и скоринг

Полная схема правил: поля, операторы, временные окна, действия.

API создания правил

Справочник эндпоинта со схемами запроса и ответа.

Библиотека правил

Каталог из 150+ пресетов и их наборы.

Обзор MCP

Подключите ИИ-агента к вашему рабочему пространству Didit.

Начало работы

Функции

Справочник

Консоль

API правил KYT и MCP: программное управление правилами мониторинга транзакций

Когда использовать каждую поверхность

Эндпоинты

Создание, бэктест, активация

Миграция правил от другого провайдера

Ошибки валидации намеренно точны

Следующие шаги

Правила и скоринг

API создания правил

Библиотека правил

Обзор MCP

​Когда использовать каждую поверхность

​Эндпоинты

​Создание, бэктест, активация

​Миграция правил от другого провайдера

​Ошибки валидации намеренно точны

​Следующие шаги

Правила и скоринг

API создания правил

Библиотека правил

Обзор MCP

Когда использовать каждую поверхность

Эндпоинты

Создание, бэктест, активация

Миграция правил от другого провайдера

Ошибки валидации намеренно точны

Следующие шаги