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

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

> Didit의 Management 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/`](https://docs.didit.me/ko/management-api/transactions/rules-list) | 필터와 성능순 정렬로 규칙 목록 조회 |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/ko/management-api/transactions/rules-create) | 사용자 정의 규칙 생성 |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ko/management-api/transactions/rules-get) | 실행 카운터와 함께 규칙 하나 조회 |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ko/management-api/transactions/rules-update) | 사용자 정의 규칙 업데이트, 모든 규칙 중 원하는 규칙의 모드 전환 |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ko/management-api/transactions/rules-delete) | 사용자 정의 규칙 삭제(영구 삭제) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/ko/management-api/transactions/rules-backtest) | 가상의 규칙을 과거 이력에 대해 평가 |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/ko/management-api/transactions/rules-library) | 설치 상태와 함께 150+ 프리셋 라이브러리 둘러보기 |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/ko/management-api/transactions/rules-install) | 키, 번들 또는 둘의 교집합으로 프리셋 설치 |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/ko/management-api/transactions/rules-uninstall) | 키, 번들 또는 둘의 교집합으로 프리셋 제거 |

이에 해당하는 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 도구 참조](https://docs.didit.me/ko/integration/mcp/tools.md)를 확인하세요.

전체 스키마(필드 카탈로그, 19개 조건 연산자 전체, 벨로시티 윈도우, 그룹 조건, 여섯 가지 작업 유형)는 [규칙 및 점수 산정](https://docs.didit.me/ko/transaction-monitoring/rules.md) 페이지에 문서화되어 있으며 API 참조에도 포함되어 있습니다.

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

새 규칙을 안전하게 배포하는 권장 절차는 다음과 같습니다.

**1. 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}]
  }'
```

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` 규칙은 새 거래마다 평가되고 일치했을 내용을 기록하지만, 거래의 점수나 상태에는 절대 영향을 주지 않습니다.

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

**2. 과거 기록에 대해 백테스트**

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

`matched` 수가 예상과 다르게 나온다면, 규칙이 실제로 작동하기 전에 임계값을 조정해야 합니다.

> [!WARNING]
>
> 활성화할 **정확한** 구성을 백테스트하세요: 같은 `conditions`, `aggregation`, `evaluation_mode`, `scope`를 사용해야 합니다. `conditions`, `aggregation`, `scope`를 생략하면 그 자체로 제약이 추가되지 않습니다. 범위를 빼면 저장된 규칙이 건너뛰는 방향이나 거래 유형을 포함할 수 있습니다. `evaluation_mode`를 생략하면 기본값은 `ALL`이므로, `ANY` 규칙에서 생략하면 일치 건수가 줄어들 수 있습니다. `period_days`를 생략하면 기본값은 90일이며, 이는 무제한 이력을 선택하지 않습니다.

**3. 활성화**

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

규칙은 **라이브** 애플리케이션의 모든 신규 거래에 즉시 적용됩니다.

> [!WARNING]
>
> 샌드박스 애플리케이션은 규칙을 절대 평가하지 않습니다. 샌드박스 거래는 저장만 되며 그 이상은 없으므로, 샌드박스 애플리케이션에서 규칙을 활성화해도 눈에 보이는 변화는 없습니다. 라이브 환경 전에 규칙을 검증하는 방법으로 지원되는 것은 백테스트이며, [샌드박스의 거래 모니터링](https://docs.didit.me/ko/integration/sandbox-testing.md#샌드박스의-거래-모니터링)을 참조하세요.

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

규칙 생성은 스키마가 완전히 문서화된 단순한 API 호출이므로, AI 어시스턴트가 다른 제공업체의 규칙 내보내기 파일을 Didit 규칙으로 변환할 수 있습니다.

1. 현재 제공업체에서 규칙을 **내보내기**합니다. 대부분의 도구는 CSV 또는 Excel로 내보낼 수 있습니다.
2. 파일을 Didit 콘솔 어시스턴트에 **끌어다 놓거나**, [Didit MCP](https://docs.didit.me/ko/integration/mcp/overview.md)가 연결된 MCP 연동 에이전트(예: Claude)에 전달합니다. 스프레드시트는 자동으로 텍스트로 변환됩니다.
3. 어시스턴트가 **각 행을 Didit 스키마에 매핑합니다**. 조건, 속도 윈도우, 작업을 매핑하고, 생성 전에 매핑 결과를 보여 주며 Didit에 대응하는 항목이 없는 부분을 알려 줍니다.
4. 승인하면 어시스턴트가 **규칙을 TEST 모드로 생성하고**, 사용자의 거래 이력을 기준으로 백테스트를 실행한 뒤, 생성됨, 실패, 매핑 불가 행 수를 보고합니다.
5. **수치를 검토하고, 적절해 보이는 규칙을 활성화합니다**. 콘솔에서 하거나 `PATCH {"mode": "ACTIVE"}`를 사용할 수 있습니다.

다음과 같은 제공업체 내보내기 파일이 있다고 합시다.

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

이 파일은 다음과 같은 규칙이 됩니다.

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

CSV 행에는 방향과 통화가 명시되어 있으므로, 규칙의 두 부분 모두 이를 포함합니다. `scope`와 `conditions`는 평가 대상 거래를 10,000 EUR 미만의 EUR 발신 송금으로 한정합니다. 집계 필터는 30일 윈도우를 같은 대상의 EUR 발신 송금으로 한정합니다. 원시 `amount`는 같은 통화 안에서만 비교할 수 있으므로, 위와 같이 통화를 고정해 두어야 합니다. 통화 간 상한을 적용하려면 윈도우 안의 모든 거래에 정규화된 금액이 있어야 합니다. `preferred_currency_amount`만 사용하면 가용성이 보장되지 않습니다. 과거 정규화 금액이 없으면 숫자 집계에서 0으로 처리될 수 있습니다.

`max` 항목은 윈도우 합계를 10,000 EUR 미만으로 유지합니다. 집계 필터는 *10,000 미만*을 표현할 수 없기 때문입니다. 그 절충에 대해서는 위의 [생성 단계](#생성-백테스트-활성화)에 있는 참고 사항을 참조하십시오. 스키마로 정확히 표현할 수 없는 내용은 조용히 근사하지 말고, 규칙의 `description`에 명시적으로 적어 두는 것이 좋습니다.

> [!TIP]
>
> 제공업체의 규칙을 커스텀 규칙으로 다시 만들기 전에 [규칙 라이브러리](https://docs.didit.me/ko/management-api/transactions/rules-library.md)를 확인하십시오. Didit은 일반적인 유형(구조화 거래, 빈도, 제재 노출, 기기 재사용, 암호화폐 위험)을 다루는 150+ 프리셋을 제공하며, 프리셋 설치는 API 호출 한 번이면 됩니다.

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

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

## 다음 단계

> [card] [규칙 및 점수 산정](https://docs.didit.me/ko/transaction-monitoring/rules.md)
>
> 필드, 연산자, 속도 윈도우, 작업을 포함한 전체 규칙 스키마입니다.

> [card] [규칙 생성 API](https://docs.didit.me/ko/management-api/transactions/rules-create.md)
>
> 요청 및 응답 스키마가 포함된 엔드포인트 참조 문서입니다.

> [card] [규칙 라이브러리](https://docs.didit.me/ko/transaction-monitoring/rules-library.md)
>
> 150+ 프리셋 카탈로그와 번들입니다.

> [card] [MCP 개요](https://docs.didit.me/ko/integration/mcp/overview.md)
>
> AI 에이전트를 Didit 워크스페이스에 연결합니다.


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