Rules API 및 MCP - 프로그래밍 방식 KYT 규칙 관리

모든 규칙 기능은 비즈니스 콘솔에서 사용할 수 있으며, 프로그래밍 방식으로도 제공됩니다. 애플리케이션 API 키와 함께 Management API를 사용하거나, 콘솔에 로그인한 사용자를 대신해 작동하는 AI 에이전트를 위해 Didit MCP를 사용할 수 있습니다. 이를 통해 코드에서 규칙을 관리하고, 규칙 세트를 버전 관리 시스템에 보관하거나, AI 어시스턴트가 규칙을 직접 만들고 마이그레이션하도록 할 수 있습니다.

어떤 인터페이스를 사용할지

방식	인증	적합한 용도
비즈니스 콘솔	콘솔 로그인	모든 변경 사항을 사람이 직접 검토할 때, 시각적 규칙 구성 및 백테스트
Management API	`x-api-key`	백엔드에서의 자동화, 코드로 관리하는 규칙 세트, CI로 관리하는 규칙 배포
Didit MCP	Didit으로 로그인(OAuth)	AI 어시스턴트 및 에이전트: Didit 콘솔 Copilot, Claude, Cursor 또는 모든 MCP 클라이언트

endpoint

endpoint	용도
`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개 조건 연산자 전체, 벨로시티 윈도우, 그룹 조건, 여섯 가지 작업 유형)는 규칙 및 점수 산정 페이지에 문서화되어 있으며 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는 평가 대상 거래를 설명합니다: 원시 amount가 10,000 미만인 EUR 기준 인바운드 금융 거래입니다. aggregation 항목은 같은 대상에 대한 30일 기간을 설명합니다: 인바운드 EUR 금융 거래가 20건 이상이며, 그중 어느 것도 10,000 EUR 이상이 아니어야 합니다. evaluation_mode 값에 관계없이 두 집계 항목은 모두 충족되어야 합니다. 이 설정은 조건에만 적용됩니다.이 예시는 원시 amount를 사용하고 두 부분 모두에서 currency를 EUR로 고정하므로 FX 정규화에 의존하지 않습니다. 샌드박스 픽스처로 백테스트하려면 같은 대상에 대해 30일 이내에 인바운드 EUR 금융 거래를 20건 이상 제출하고, 각 거래의 amount는 10,000 미만이어야 합니다. preferred_currency_amount와 amount_in_default_currency 모두 필수가 아닙니다. 샌드박스 수집 과정에서 이 거래들이 저장되며, 백테스트는 명시적으로 실행해야 합니다.TEST 규칙은 새 거래마다 평가되고 일치했을 내용을 기록하지만, 거래의 점수나 상태에는 절대 영향을 주지 않습니다.

집계 필터는 조건이 아닙니다. 조건은 평가 대상 거래만 읽습니다. 집계 필터는 과거 기간을 좁히기만 하며, 동등 비교나 목록 포함 여부로만 비교합니다. lt 필터는 없으므로 10,000 미만 송금만 셀 수는 없습니다.max ... lt 10000 항목은 기간에 상한을 두는 지원되는 방법입니다. 이 항목은 기간 내 모든 거래가 10,000 미만이어야 한다고 요구하며, 이는 작은 거래만 세는 것보다 엄격합니다. 20건 중 12,000 송금이 하나라도 있으면 규칙은 실행되지 않습니다. 개수를 독립적으로 세기를 원한다면 해당 항목을 제거하고 제목에 그 사실을 명시하세요. 이 항목이 없으면 규칙은 크기와 상관없이 인바운드 송금을 셈하며, 50,000 송금 19건 뒤에 작은 송금 1건이 오면 규칙이 일치하게 됩니다.

과거 기록에 대해 백테스트

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를 생략하면 그 자체로 제약이 추가되지 않습니다. 범위를 빼면 저장된 규칙이 건너뛰는 방향이나 거래 유형을 포함할 수 있습니다. 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 호출이므로, AI 어시스턴트가 다른 제공업체의 규칙 내보내기 파일을 Didit 규칙으로 변환할 수 있습니다.

현재 제공업체에서 규칙을 내보내기합니다. 대부분의 도구는 CSV 또는 Excel로 내보낼 수 있습니다.
파일을 Didit 콘솔 어시스턴트에 끌어다 놓거나, Didit MCP가 연결된 MCP 연동 에이전트(예: Claude)에 전달합니다. 스프레드시트는 자동으로 텍스트로 변환됩니다.
어시스턴트가 각 행을 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는 평가 대상 거래를 10,000 EUR 미만의 EUR 발신 송금으로 한정합니다. 집계 필터는 30일 윈도우를 같은 대상의 EUR 발신 송금으로 한정합니다. 원시 amount는 같은 통화 안에서만 비교할 수 있으므로, 위와 같이 통화를 고정해 두어야 합니다. 통화 간 상한을 적용하려면 윈도우 안의 모든 거래에 정규화된 금액이 있어야 합니다. preferred_currency_amount만 사용하면 가용성이 보장되지 않습니다. 과거 정규화 금액이 없으면 숫자 집계에서 0으로 처리될 수 있습니다. max 항목은 윈도우 합계를 10,000 EUR 미만으로 유지합니다. 집계 필터는 10,000 미만을 표현할 수 없기 때문입니다. 그 절충에 대해서는 위의 생성 단계에 있는 참고 사항을 참조하십시오. 스키마로 정확히 표현할 수 없는 내용은 조용히 근사하지 말고, 규칙의 description에 명시적으로 적어 두는 것이 좋습니다.

제공업체의 규칙을 커스텀 규칙으로 다시 만들기 전에 규칙 라이브러리를 확인하십시오. Didit은 일반적인 유형(구조화 거래, 빈도, 제재 노출, 기기 재사용, 암호화폐 위험)을 다루는 150+ 프리셋을 제공하며, 프리셋 설치는 API 호출 한 번이면 됩니다.

검증 오류는 의도적으로 정확합니다

생성 및 수정 엔드포인트는 조건, 집계, 범위 값을 규칙 엔진이 허용하는 값과 정확히 대조하여 검증합니다. 알 수 없는 연산자나 지표, 잘못된 윈도우("30days" 대신 "30d"), 잘못된 범위 방향, 목록 없이 쓰인 contains_any, score 없이 쓰인 fuzzy_match, workflow_id 없이 AWAITING_USER로 바꾸는 change_status는 모두 인덱스와 문제를 명시한 400 응답을 반환합니다. 결코 일치하지 않는 규칙을 조용히 저장하는 대신 오류를 반환합니다. 에이전트와 스크립트는 오류 본문을 읽고 페이로드를 수정해야 합니다. transaction_types, directions, action_types 이외의 추가 범위 키는 저장되지만 엔진이 무시합니다. Business Console이 이를 저장해 온 방식과 같습니다.

다음 단계

규칙 및 점수 산정

필드, 연산자, 속도 윈도우, 작업을 포함한 전체 규칙 스키마입니다.

규칙 생성 API

요청 및 응답 스키마가 포함된 엔드포인트 참조 문서입니다.

규칙 라이브러리

150+ 프리셋 카탈로그와 번들입니다.

MCP 개요

AI 에이전트를 Didit 워크스페이스에 연결합니다.

시작하기

기능

레퍼런스

콘솔

Rules API 및 MCP - 프로그래밍 방식 KYT 규칙 관리

어떤 인터페이스를 사용할지

endpoint

생성, 백테스트, 활성화

다른 제공업체에서 규칙 마이그레이션

검증 오류는 의도적으로 정확합니다

다음 단계

규칙 및 점수 산정

규칙 생성 API

규칙 라이브러리

MCP 개요

​어떤 인터페이스를 사용할지

​endpoint

​생성, 백테스트, 활성화

​다른 제공업체에서 규칙 마이그레이션

​검증 오류는 의도적으로 정확합니다

​다음 단계

규칙 및 점수 산정

규칙 생성 API

규칙 라이브러리

MCP 개요

어떤 인터페이스를 사용할지

endpoint

생성, 백테스트, 활성화

다른 제공업체에서 규칙 마이그레이션

검증 오류는 의도적으로 정확합니다

다음 단계