sumsub-create-kyt-rules

Sumsub — KYT ルール、申請者のスコアリング、リスクレベル

KYT トランザクション監視スタック全体を設定します。

• ルール — ユーザーの意図を KytTxnRule ペイロードに変換し、1 件ずつ POST します。新しいルールの作成と、既存ルールの変更（新しいリビジョンの POST）に対応しています。新しいルールは必ず testMode（dryRun: true）で開始します。これらは dryScore には表示されますが、ダッシュボードで有効化されるまでは本番の判定結果に影響しません。
• タグと申請者のスコアリング — タグ（名前付きのリスクマーカー）と、タグの重みを総合的な申請者リスクスコアに変換する評価設定を作成・設定します。
• リスクレベル — 数値のリスクスコアを、人が理解しやすいラベル（例：低／中／高）に変換するしきい値を設定します。

ルール、タグ、リスクレベルは、単一のパイプラインを構成します。ルールが発火 → タグを適用 → タグの重み付きスコアが蓄積 → スコアをリスクレベルに変換。

エンドポイント

メソッド	パス	説明	レスポンス
GET	/resources/api/agent/tm/rules/-/installed	既存のルールを一覧表示します。?limit=<n> と ?offset=<n> に対応しています。seeKytRules が必要です。	{ list: { items: [...] } }
POST	/resources/api/agent/tm/rules	新しいルールまたは新しいリビジョンを作成します。新規作成では id と name を省略します。リビジョンでは既存の name スラッグと "id": null を含めます。manageKytRules が必要です。	200 ルールオブジェクト · 400 エラーメッセージ
GET	/resources/api/agent/tm/rules/-/bundle/{bundleName}/{category}	バンドル内のルールを、名前とインストール状態で一覧表示します。category：installed、available、archived。seeKytRules が必要です。	{ list: { items: [...] } }
GET	/resources/api/agent/tm/rules/{id}	ID でルールを 1 件取得します。seeKytRules が必要です。	ルールオブジェクト
GET	/resources/api/agent/tm/settings/tags	すべての KYT タグと、その評価設定および関連付けられたルールを一覧表示します。	{ tags: [...] }
POST	/resources/api/agent/tm/settings/tag	KYT タグを作成または更新します。ボディ：{"tag": {"name": "...", "styleClass": "...", "color": "#RRGGBBAA", "scorable": true, "includeInReporting": true, "scoreWeight": 1.0}}。color は 8 桁の 16 進数である必要があります。manageKytSettings が必要です。	200 空のボディ
GET	/resources/api/agent/tm/settings/applicantAssessment	現在の申請者評価スコアリング設定（タグの重み、階層、企業受益者の重み）を取得します。	評価設定オブジェクト
PATCH	/resources/api/agent/tm/settings/applicantAssessment	申請者評価スコアリング設定を置き換えます。manageKytSettings が必要です。	200 更新された評価設定
GET	/resources/api/agent/tm/settings/riskLevel	現在の申請者リスクレベルのしきい値を取得します。	リスクレベル設定オブジェクト
PATCH	/resources/api/agent/tm/settings/riskLevel	リスクレベルのしきい値を置き換えます。ボディ：2 項目以上。それぞれに label（≤256）、rangeFrom（≥0）、styleClass を指定します。styleClass は次のいずれかです：grey、black、blue、green、cyan、teal、lime、yellow、orange、volcano、red、pink、fuchsia、purple、purpleLight。manageKytSettings が必要です。	200 更新されたリスクレベル設定
GET	/resources/api/agent/tm/clientLists/{listName}	名前でクライアントリストを取得します。見つからない場合は 404 を返します。seeClientLists が必要です。	クライアントリストオブジェクト
POST	/resources/api/agent/tm/clientLists/{listName}	クライアントリストを作成します（冪等）。manageClientLists が必要です。	クライアントリストオブジェクト

ルールの SumScript 式フィールドの完全なリファレンスと型システムについては、references/kyt-rule-schema.md を参照してください。

認証 — アプリトークン＋シークレット（サンドボックス専用）

このスキルは公開 Sumsub API と連携し、認証リファレンスに従って各リクエストに署名します。仕組みの詳細は sumsub-api-auth スキルに記載されています。401 Invalid signature が発生した場合は、そちらをお読みください。

⚠️ サンドボックストークン専用です。 ここでは本番用のアプリトークンを受け取ったり、使用したりしないでください。ユーザーが提示した場合は、受け取りを断り、https://cockpit.sumsub.com/checkus/home?sbx=true でサンドボックス用のペアを生成するよう案内してください（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。 トークンとシークレットは一度だけ表示されます。ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトがこのルールを強制し、sbx: で始まらないトークンを拒否します。

変数	例
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで発行したサンドボックス用アプリトークン。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

ユーザーが会話ですでに認証情報を提示している場合は、それを再利用してください。提示されていない場合は、実行前に一度だけ確認してください。シークレットをそのまま返答に含めないでください。

テナントのエンタイトルメント

エンタイトルメントは全体ではなく、トランザクションタイプごとに設定されます。各 types 値には、そこに記載されたキーのうちいずれか1つが必要であり、すべてが必要なわけではありません。すべてのルールに必要な基本エンタイトルメントはありません。KYT は finance タイプのエンタイトルメントであり、それ以上の意味はありません。

ルールの types 値	有効化に必要なキー（いずれか1つ）
finance	KYT
travelRule	TRAVEL_RULE
kyc	TM_INDIVIDUAL_APPLICANT_SCORING · TM_COMPANY_APPLICANT_SCORING · KYT_ANTI_FRAUD · KYT · DEVICE_INTELLIGENCE
userPlatformEvent	KYT_ANTI_FRAUD · KYT
scheduledEvent	TM_SCHEDULED_EVENTS · KYT

TRAVEL_RULE のみを持つテナントは、travelRule ルールを作成できます。DEVICE_INTELLIGENCE のみを持つテナントは、kyc ルールを作成できます。どちらも KYT は必要ありません。その行に KYT が記載されていないタイプに、KYT を要求しないでください。

ルールを作成または変更する前に、sumsub-check-permissions スキルのディレクトリから bash scripts/check_permissions.sh を実行してください。レスポンスボディは {"allowedChecks": {"<KEY>": "<description>", ...}} です。allowedChecks のキーが有効なエンタイトルメントです。allowed 配列はありません。

要求されたタイプが有効でない場合に限り停止してください。つまり、そのタイプの行にあるキーが allowedChecks に1つも含まれていない場合です。そのルールを構築したり、POST したりしないでください。タイプ名はユーザーに表示される名称で示してください（トランザクションタイプを参照。kyc は「Verification session events」であり、「kyc」ではありません）。そのタイプを有効にするキーを「or」でつないで列挙し、CSM または Sumsub サポートに問い合わせるようユーザーに伝えてください。回避策として別のトランザクションタイプを提案しないでください。ユーザーが travelRule ルールを希望している場合、finance ルールで代用することはできません。

エンタイトルメントの確認自体に失敗した場合（200 以外のレスポンス、タイムアウト）は、エンタイトルメントを確認できなかったことをユーザーに警告し、そのまま続行してください。バックエンドが判定の主体であり、POST 時に同じ制限を適用します。ステップ6の No allowed transaction types found の行を参照してください。

スケジュールルールについての注意。 スケジュールのトリガーモードは特に TM_SCHEDULED_EVENTS によってライセンスされますが、scheduledEvent タイプは KYT によっても有効になります。そのため、KYT のみを持つテナントはこの確認を通過しても、バックエンドから noEventTrigger により拒否される場合があります。その場合は通常どおりルールを構築し、バックエンドのエラーをそのままユーザーに提示してください。

手順

0. テナントのエンタイトルメントを取得します。ルールの作成または変更時に限ります。 sumsub-check-permissions を実行し、allowedChecks のキーを保持します。ルールの types が分かったら、テナントのエンタイトルメントで該当する行を確認し、そのキーが1つも含まれていない場合は中止してください。 ルールではない作業では、この手順を完全にスキップしてください。タグ、申請者の評価、リスクレベルに権限付与は不要です。/tm/clientLists エンドポイント（手順 2a）には WATCHLISTS または WATCHLISTS_FOR_TM が必要です。どちらもない場合は、権限が不要な sumsub-manage-client-lists を使ってリストを作成してください。ただし、Sumsub 管理のリストはインストールできません（必要な権限を参照）。sumsub-check-permissions が呼び出すもの以外のエンタイトルメントエンドポイントを探さないでください。他にエンドポイントはありません。

1. モードを決定します — 作成または変更。

   • 変更モード： ユーザーがルールの name（変更できないスラッグ。例：fin-ben-pep-ter-list-abo-thr-WoGD）を指定するか、ルールを特定するのに十分な情報を提供します。bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh を実行し、name または title でルールを見つけて、現在のドキュメント全体を保存します。既存の conditionEl、score、action、types をユーザーに提示し、変更したいフィールドのみを確認します。手順 2a に進みます。
   • 作成モード： ユーザーが新しいルールの内容を説明します。bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh を実行し、タイトルが重複しないか確認します。サーバーは重複排除を行わず、POST のたびに重複するルールを作成します。一致するタイトルのルールがすでに存在する場合は、作成をスキップして既存のルールを変更する方法を提案します。

2. ユーザーの意図を簡潔な仕様にまとめます。 ユーザーが作成を希望するルールごとに、以下を確認します。

   • title（128 文字以下、必須）
   • types — 1 つ以上の取引タイプ（下の表を参照）
   • 条件の平易な説明（手順 3 で conditionEl を生成するために使用）
   • score（整数、デフォルトは 0）、action（score | onHold | awaitUser | reject）
   • 任意：desc、tags、bundleName、priority、stopOnMatch、sourceKeys

2a. クライアントリストが存在することを確認します — ルールの conditionEl が clientLists.<name> を参照する場合は、式を生成または検証する前に、各リストの存在を確認します。 bash bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh <listName> - HTTP 200 → リストが存在します。続行します。 - HTTP 404 → リストが存在しません。作成します。 bash bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh <listName> POST は冪等です。リストがその間に作成されていても成功します。 それ以外の名前の場合、作成されるのは key エントリーの空の custom リストです。リストのタイプとエントリーのタイプは、作成後に変更できません。そのため、ルールでメールアドレス、電話番号、申請者 ID、デバイス ID、IP 範囲のリスト、または blocklist／whitelist が必要な場合や、リストへの値の追加が必要な場合は、ここでは作成せず、型付きリストを作成して値を追加する sumsub-manage-client-lists に引き継いでください。Sumsub 管理の名前 （fatf_black_flag_countries、eu_high_risk_third_countries、… — 該当スキルの表を参照）の場合、POST によって Sumsub 独自の読み取り専用リストがインストールされます。これは正しい動作です。カスタムの国リストを作成するのではなく、このリストを使用してください。 参照するすべてのクライアントリストが確認されるまで、検証やルール作成に進まないでください。 3. conditionEl を生成します。 条件が必要なルールごとに、次の手順を行います。

• references/kyt-rule-schema.md の型定義を使って、SumScript のブール式を構築します。
• フィールドパスを推測してはいけません。 スキーマで確認できたフィールドのみを使用し、式を記述する前にルートからリーフまでのパスを検証してください。
• デフォルト通貨で金額をチェックする場合は、data.info.amount（元通貨の金額）ではなく、data.info.amountInDefaultCurrency（正規化された金額）を使用してください。ただし、ユーザーが明示的に元通貨でのフィルタリングを求めている場合を除きます。
• スケジュールルール（types: ["scheduledEvent"]）のトリガーには conditionEl を使用しません。代わりに noEventTrigger を使用してください（references/kyt-rule-schema.md を参照）。
• 複数の分岐でスコアを付与する場合（サブ条件ごとに異なるスコアを付与）、conditionEl 内で addScoreIf を使用し、ペイロードレベルの score: 0、action: "score" を設定してください（Scoring セクションを参照）。

3a. 検証は POST に組み込まれています。サーバーは作成呼び出し（手順 6）の際に conditionEl の構文を検証します。事前検証の手順は不要です。検証に失敗すると、問題の内容を示すエラーメッセージとともに、サーバーは HTTP 400 を返します。式を修正して再度 POST してください。

4. ペイロードを構築します。 次の制約に従って、各ルールの JSON を組み立てます。

   作成モード：

   • 必須フィールドのみ： title、types（1 つ以上の値）。
   • eval ルールの場合：該当する場合は conditionEl、score、action を含めます。
   • id や name は絶対に送信しないでください。これらはサーバーによって割り当てられます。

   変更モード（新しいリビジョン）：

   • "name": "<existing-slug>" を含めます。これは既存ルールの不変のスラッグです。
   • "id": null を明示的に含めます。これにより、サーバーは新しいルールではなく新しいリビジョンを作成します。"id": ""（空文字列）は使用しないでください。Jackson はこれを無効な ObjectId として拒否し、HTTP 400 を返します。
   • 既存のルールドキュメントから、変更しないフィールドをすべて引き継ぎます。ユーザーが変更を依頼したフィールドのみを変更してください。
   • title と types は必須のままです。

   両モードで常に適用：

   • サーバーが割り当てるフィールドおよび監査フィールドは絶対に送信しないでください。対象は clientId、actual、revision、タイムスタンプ（createdAt、modifiedAt、archivedAt）、作成者フィールドです。
   • scope や bgCheckTargets は絶対に送信しないでください。これらはサーバーが管理するライセンス制御フィールドです。
   • 作成モード： dryRun や disabled は絶対に送信しないでください。サーバーはそれぞれ true と false に初期化します。
   • 変更モード： 既存のルールドキュメントから dryRun と disabled を引き継ぎます。サーバーは送信された値を使用して、リビジョン作成後もルールの現在の有効化状態とテストモード状態を維持します。
   • 空のオプションコンテナーは省略します：sourceKeys: []、caseAction: {}、 applicantChange: {}、applicantActions: {"actions": {}}、 varDefinitions: {"definitions": []}、varValues: {"values": {}}。
   • scheduledEvent を他のトランザクションタイプと混在させないでください。

5. 各ペイロードをユーザーに提示し、POST する前に明示的な確認を求めてください。

6. 各ルールを POST します。bash ${CLAUDE_SKILL_DIR}/scripts/post_kyt_rule.sh < payload.json を使用してください。 ルールは 1 つずつ作成されます。終了コードを確認してください。

   • 終了コード 0 → HTTP 200。レスポンス本文は作成された KytTxnRuleView です。手順 7 に進んでください。
   • 終了コード 1 → HTTP 4xx/5xx。レスポンス本文にエラーメッセージが含まれています。そのままユーザーに伝え、式を修正して再度 POST してください。 バックエンドでも権限によるゲートが適用されます。次の2つのエラーメッセージは、ペイロードに問題はなく、変更せずに再試行しても成功しないことを意味します。そのルールの再試行を停止し、報告してください。
   • No allowed transaction types found → テナントは送信した types のライセンスを持っていません。ユーザーに、allowedChecks で有効になっているタイプを伝え、CSM に問い合わせるよう案内してください。別のタイプに無断で切り替えないでください。
   • Unable to enable a rule without a specified condition → ルールには conditionEl（または scheduledEvent の場合は noEventTrigger）が必要です。

   再試行の上限： ルールごとの POST 試行は最大10回までとします。10回目の試行でも失敗した場合、そのルールを失敗として記録し、最後のエラーメッセージを記録してから次のルールに進んでください。バッチ全体を中止してはいけません。失敗したルールはステップ9で報告してください。

7. bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rule.sh {id} を使って、作成したルールをそれぞれ GET で取得します。 conditionEl と主要なフィールドを送信した内容と比較してください。相違があれば報告してください。

8. ルールごとにダッシュボードへのリンクを作成します。

   https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&sbx=true
   

   name と clientId は POST レスポンスの本文から取得します。クリック可能な Markdown リンクとして表示します。

9. 報告 — 各ルールについて、人が読めるタイトルを先頭に記載してください。

   • タイトルと自動生成された name（短く変更不可のスラッグ）
   • ステータス： testMode — 運用を開始するにはダッシュボードで有効化する必要があります
   • types、action、score
   • クリック可能な Markdown リンクとしてのダッシュボードリンク
   • ルールの id を最後の行に単独で記載

   10回の試行をすべて使い切ったルールは、タイトルと最後の HTTP 400 エラーメッセージを記載した 失敗したルール セクションで報告してください。

   4xx エラーはそのまま提示してください。

⚠️ testMode のデフォルト。 新しいルールはすべて dryRun: true で始まります。トランザクションに対して評価され、その結果は dryScore に表示されますが、実際のスコアやアクションには影響しません。ルールを有効にするには、ダッシュボードでルールを開き、「Active」に設定してください。

コンパクトな仕様形式

完全なペイロードを生成する前に、各ルールを JSON オブジェクトとして表現します。

{
  "title": "Hold large outgoing transfers",         // required, ≤128 chars
  "desc": "Holds outgoing transactions over 50 000 in default currency",
  "types": ["finance"],                             // required
  "condition": "outgoing AND amount > 50 000 default currency",  // natural language → conditionEl
  "score": 100,                                     // 0 if using addScoreIf
  "action": "onHold",                              // score | onHold | awaitUser | reject
  "tags": ["HighAmount"],                           // optional; auto-created if new
  "bundleName": "AML Compliance",                   // optional group
  "priority": 10,                                   // optional; higher = evaluated first
  "stopOnMatch": false,                             // optional
  "sourceKeys": ["payment-gateway-1"]               // optional top-level filter
}

トランザクションタイプ

タイプ（API 値）	ユーザーに使う名称	使用する場面	conditionEl が必要か	備考
finance	finance transactions	支払いの送金、入金、出金	はい	最も一般的なタイプ
travelRule	Travel Rule transactions	Travel Rule トランザクション	はい
kyc	Verification session events	申請者の検証セッションイベント	はい	ユーザー向けの文面では「kyc」と書かないでください
userPlatformEvent	User platform events	ログイン、パスワードのリセット、2FA イベント	はい
scheduledEvent	Scheduled events	申請者の定期的な再チェック	いいえ（noEventTrigger を使用）	types に単独で指定する必要があります

scheduledEvent を除き、複数のタイプを1つのルールに組み合わせることができます。scheduledEvent は唯一のタイプとして指定する必要があります。

1列目は API 値、2列目はユーザーに表示する名称です。 API 値は types にのみ指定し、レポート、拒否の説明、確認の質問では、2列目の名称、つまりダッシュボードに表示される名称を使ってください。実際に誤解を招くのは kyc です。ダッシュボードには「kyc」というラベルがどこにもないため、その名称を使うと、ユーザーは存在しない項目を探すことになります。ほかの4つは表示上の名称にすぎませんが、それでもダッシュボードの表記を使ってください。

このテナントで使用できるタイプは、タイプごとに制限されています。その対応関係の唯一の情報源であるテナントの権限を参照してください。

ルールのアクション

アクション	優先度	効果
score	0	スコアのみを加算します（デフォルト）
onHold	5	トランザクションを保留し、レビューに回します
awaitUser	7	処理を進める前にユーザーの操作を待ちます
reject	10	トランザクションをただちに拒否します

一致したすべてのルールの中で、最も強いアクションが適用され、スコアは累積されます。

スコアリングと conditionEl

シンプルなルール（しきい値1つ、スコア1つ）： スコアを score に入れ、conditionEl は純粋な真偽値のままにします。

{
  "title": "Hold high outgoing finance",
  "types": ["finance"],
  "conditionEl": "data.info.direction == 'out' AND data.info.amountInDefaultCurrency > 50000",
  "score": 100,
  "action": "onHold"
}

複数分岐のスコアリング（条件ごとに異なるスコア）： conditionEl 内で addScoreIf を使用します。 ペイロードの score: 0 と action: "score" を設定してください。そうしないと、ペイロードのスコアが二重に加算されます。

• EOR（先行評価 OR）： すべての分岐を評価し、一致した分岐のスコアをすべて累積します。独立したフラグに使用します。
• OR（短絡評価）： 最初に一致した分岐で停止します。相互に排他的な段階（最も厳しいものを先に）に使用します。

addScoreIf(data.info.amountInDefaultCurrency > 100000, 50) EOR
addScoreIf(applicant.country IN clientLists.sanctioned_countries, 100) EOR
addScoreIf("pep" IN applicant.riskLabels.aml, 75)

conditionEl の一般的なパターン

# Finance: outgoing transfer over threshold
data.info.direction == 'out' AND data.info.amountInDefaultCurrency > 50000

# Finance: applicant in a client list
applicant.country IN clientLists.high_risk_countries

# Finance: incoming from specific payment type
data.info.direction == 'in' AND data.info.type == 'transfer'

# Finance: crypto transaction
data.info.currencyType == 'crypto'

# KYC: applicant review rejected
applicant.review.decision == 'rejected'

# Travel Rule: counterparty VASP not found
txn.travelRuleInfo.status == 'counterpartyVaspNotFound'

# Aggregation: applicant sent > 3 transactions in last 24 hours
txns.finance.byApplicant.out.lastHours(24).count() > 3

# Aggregation: total outgoing amount in last 30 days
txns.finance.byApplicant.out.lastDays(30).sum(it.data.info.amountInDefaultCurrency) > 100000

# KYC: questionnaire answer — nested questionnaire.section.item, dot notation only
questionnaires.myQuestionnaireId.mySectionId.myItemId == 'salary'

# KYC: same, when a segment contains a dash — backtick-quote that segment
questionnaires.`my-quest-id`.mySectionId.myItemId == 'salary'

アンケートの回答に対する条件には、ルールは正常に保存されるのに一度も一致しない原因となる落とし穴が2つあります。角括弧形式はコンパイルされず、比較対象の値は申請者に表示されるラベルではなく、選択肢に保存された値です。ルールを作成する前に、3つの ID の調べ方を含め、references/kyt-rule-schema.md → questionnaires を確認してください。

型システム全体と利用可能なすべてのフィールドについては、references/kyt-rule-schema.md を参照してください。

クライアントリスト

クライアントリストは、conditionEl で clientLists.<listName> として参照される値（国、通貨、ピア ID など）の名前付きセットです。リストを参照するルールは、検証または作成する前にリストが存在している必要があります。

リストの確認と作成

# Check if a list exists
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh high_risk_countries

# Create a list (idempotent)
bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh high_risk_countries

POST はリストが存在しない場合に空のリストを作成し、いずれの場合もリストドキュメントを返します。

必要な権限

操作	権限
GET（読み取り）	seeClientLists
POST（作成）	manageClientLists

GET が 403 を返す場合は、seeClientLists が不足しています。POST が 403 を返す場合は、manageClientLists が不足しています。どちらの場合も、不足している権限をユーザーに伝えて終了してください。

両方のエンドポイントには WATCHLISTS または WATCHLISTS_FOR_TM のエンタイトルメントも必要です。テナントがどちらも持っていない場合は、代わりに sumsub-manage-client-lists を使ってリストを作成してください。そのエンドポイントにはエンタイトルメントが不要です。ただし、Sumsub が管理する名前（fatf_black_flag_countries など）は例外です。 これを登録できるのはこのエンドポイントのみで、このスキルでは予約名を拒否します。そのリストにはテナントで WATCHLISTS または WATCHLISTS_FOR_TM が必要であることをユーザーに伝えて終了してください。引き継ぎはせず、別の名前で複製を作成しないでください。

conditionEl での使用方法

clientLists. プレフィックスの後に、正確な名前でリストを参照します。

# Country in a named list
applicant.country IN clientLists.high_risk_countries

# Peer wallet not in an allowlist
NOT (txn.counterparty.wallet IN clientLists.approved_wallets)

# Combined
applicant.country IN clientLists.sanctioned_countries AND data.info.amountInDefaultCurrency > 1000

上記のエンドポイントで取得または作成されるのは、key エントリを持つ空の custom リストのみです。ステップ 2a にあるとおり、値（国、ウォレット、ピア ID など）や型付きエントリが必要なリストは、ここでは作成されません。sumsub-manage-client-lists が同じ clientLists エンティティ（共有の seeClientLists／manageClientLists 権限）を通じてリストを作成し、値を追加します。リストへの値の追加が完了したという報告を受けたら、ステップ 3 から再開してください。

タグ

タグはルールへの一致を申請者レベルのリスク評価に結び付けます。

• ルールに tags: ["TagName"] を追加します。新しいタグ名は KYT 設定で自動的に作成されます。
• ルールが一致すると、各タグに申請者のルールスコアが累積されます。
• スコアリング後の applicantAssessment ランナーがタグのスコアを申請者のリスクプロファイルに集計します。

スケジュールルール（scheduledEvent）

スケジュールルールは、受信トランザクションがなくても発動します。トリガー条件に基づいて申請者を特定し、合成イベントを生成します。noEventTrigger の構造の全容については、references/kyt-rule-schema.md を参照してください。

主な制約：

• types は ["scheduledEvent"] のみを指定する必要があります。他のタイプと組み合わせることはできません。
• applicantChange または applicantActions（少なくとも一方）を含める必要があります。
• conditionEl は省略可能です（副次的なフィルタリングに使用し、主要なトリガーとしては使用しないでください）。
• noEventTrigger.type は byLevelName（審査後 N 日経過した、指定レベルの承認済み申請者）または byCustomExpression（自由形式の申請者フィルター式）のいずれかです。

最小限のスケジュールルール：

{
  "title": "Annual KYC refresh",
  "types": ["scheduledEvent"],
  "noEventTrigger": {
    "type": "byLevelName",
    "levelParams": {
      "levelName": "basic-kyc-level",
      "days": 365
    }
  },
  "applicantChange": {
    "type": "applicantLevel",
    "applicantLevel": {
      "levelName": "re-verification-level"
    }
  }
}

一致時のケース作成

ルールが一致したときにコンプライアンスケースを自動作成するには、caseAction を追加します。

{
  "caseAction": {
    "createCase": true,
    "groupByType": "byApplicant",
    "blueprintId": "<case-blueprint-id>",
    "priority": "high",
    "deadlineHours": 24
  }
}

groupByType：byRule（ルールごとに 1 件のケース）または byApplicant（申請者ごとに 1 件のケース。トランザクションはグループ化されます）。 blueprintId は省略可能です。省略すると、デフォルトのケーステンプレートが使用されます。

既存のルールの変更

ルールを更新するには、作成時と同じエンドポイントに新しいリビジョンを POST します。サーバーは現在のリビジョンをアトミックに置き換え、revision をインクリメントします。

ルールの特定

ユーザーは、ルールの name（変更不可のスラッグ）を指定するか、タイトルから特定するための十分な情報を指定する必要があります。すべてのルールを一覧表示し、一致するものを見つけます。

bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh | python3 -c "
import json, sys
items = json.load(sys.stdin).get('list', {}).get('items', [])
for r in items:
    if r.get('name') == 'fin-ben-pep-ter-list-abo-thr-WoGD':
        print(json.dumps(r, indent=2))
"

または、タイトルの部分文字列で検索します。

bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh | python3 -c "
import json, sys
items = json.load(sys.stdin).get('list', {}).get('items', [])
for r in items:
    if 'PEP' in r.get('title', '').upper():
        print(json.dumps(r, indent=2))
"

続行する前に、一致したルールの現在の conditionEl、score、action、types をユーザーに表示します。

ペイロードの形式

既存のルールドキュメントにユーザーが要求した変更のみを適用し、その後、以下を行います。

• "id": null を設定します。明示的な null は、新しいルールではなく新しいリビジョンであることを示します。"" は使用しないでください。Jackson の ObjectId デシリアライズで失敗し、HTTP 400 が返されます。
• "name": "<slug>" を維持します。これは既存の変更不可のスラッグです。
• サーバー管理フィールドを削除します。対象は clientId、actual、revision、scope、bgCheckTargets、タイムスタンプ、作成者フィールドです。
• 既存のドキュメントにある dryRun と disabled は維持します。これにより、リビジョン後も現在のルールの有効化状態とテストモードの状態が保たれます。

{
  "id": null,
  "name": "fin-ben-pep-ter-list-abo-thr-WoGD",
  "title": "Finance — Beneficiary in PEP and terror list above threshold",
  "types": ["finance"],
  "conditionEl": "beneficiary.fullName IN clientLists.pep_and_terror AND data.info.amountInDefaultCurrency > 5000",
  "score": 100,
  "action": "onHold",
  "dryRun": true,
  "disabled": false
}

POST 前の検証

conditionEl が変更された場合、POST 時に自動検証されます。サーバーから HTTP 400 が返された場合は、式を修正して再度 POST します（作成モードと同じく、試行回数の上限は 10 回です）。

POST 後

• レスポンスには、新しい id（最新のリビジョンには新しい ID が付与されます）、以前の name、revision 番号、およびすべてのルールフィールドが含まれます。
• 新しい id でルールを GET し、確認します。
• ダッシュボードへのリンクには以前の name を使用します。

  https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&sbx=true
  

• 新しい revision 番号を、タイトルおよび更新されたフィールドとともに報告します。

申請者のリスクスコアリング

申請者のリスクスコアリングでは、一致したトランザクション監視ルールに基づいて、各申請者の複合リスクスコアを算出します。スコアは、個別に設定する次の 3 つのレイヤーから構成されます。

Rules (produce tags on match)
  └─ Tags (each carries a score weight)
       └─ Assessment (maps tags → weighted score)
            └─ Risk Levels (score thresholds → Low / Med / High label)

仕組み

1. ルールの発動 — TM ルールがトランザクションに一致すると、申請者に tags が適用されます。
2. タグの蓄積 — 各タグには scoreWeight が設定されています。複数のルールが一致すると、タグのスコアが合算されます。
3. 評価の集計 — 評価設定で、合計スコアに含めるタグ（includeInTotalScore）、相対的な重み（scoreWeight）、および任意の階層構造（items）を制御します。
4. リスクレベルの割り当て — 合計スコアを riskLevelThresholds と照合し、人が読み取れるリスクラベル（例：低／中／高）を生成します。

企業の場合、評価に含まれる companyBeneficiarySettings により、役割に基づく重み付け（UBO、取締役、株主など）が適用され、関連当事者のリスクが申請者のスコアに反映されます。

申請者スコアリングの設定 — ステップごと

ステップ 1 — タグを作成／更新する

echo '{"tag": {"name": "HighValue", "styleClass": "red", "color": "#FF000080", "scorable": true, "scoreWeight": 1.0}}' \
  | bash scripts/post_kyt_tag.sh

すべてのタグを読み戻して確認します：

bash scripts/get_kyt_tags.sh

ステップ 2 — 評価を設定する

タグを重み付きスコアに対応付けます。id は、エントリーに対してクライアントが割り当てる固定識別子です。

{
  "scores": [
    {
      "id": "high-value-score",
      "tag": "HighValue",
      "includeInTotalScore": true,
      "scoreWeight": 1.0
    }
  ],
  "companyBeneficiarySettings": [
    { "beneficiaryType": "ubo",      "weight": 1.0 },
    { "beneficiaryType": "director", "weight": 0.5 }
  ]
}

有効な beneficiaryType の値：shareholder、representative、director、ubo、companyOfficer、secretary、founder、investor、legalAdvisor、authorizedSignatory、trustee、trustBeneficiary、trustSettlor、trustProtector、payer。

# Read current
bash scripts/get_kyt_applicant_assessment.sh

# Apply new config
echo '<payload>' | bash scripts/patch_kyt_applicant_assessment.sh

ステップ 3 — リスクレベルのしきい値を設定する

# Read current
bash scripts/get_kyt_risk_level_settings.sh

# Apply new thresholds (min 2 required)
echo '{"riskLevelThresholds": [
  {"label": "Low",  "rangeFrom": 0,   "styleClass": "green"},
  {"label": "High", "rangeFrom": 75,  "styleClass": "red"}
]}' | bash scripts/patch_kyt_risk_level_settings.sh

ルール内のタグ

ルールのペイロードに tags を追加して、ルールの一致結果を評価に関連付けます：

{
  "title": "Flag high-value transfers",
  "types": ["finance"],
  "conditionEl": "data.info.amountInDefaultCurrency > 10000",
  "score": 50,
  "action": "score",
  "tags": ["HighValue"]
}

このルールが一致すると、申請者に HighValue タグが適用され、その重みがリスクスコアに加算されます。

関連項目

• references/kyt-rule-schema.md — 全フィールドのリファレンスと SumScript 型システム
• examples/minimal.json — 最小限の動作するペイロード
• examples/eval-finance-hold.json — 完全な金融取引保留ルール
• scripts/get_kyt_bundle.sh — バンドル内のルールを名前とカテゴリ（installed | available | archived）で一覧表示
• scripts/get_kyt_tags.sh — 評価設定と関連ルールを含むすべての KYT タグを一覧表示
• scripts/post_kyt_tag.sh — KYT タグを作成または更新（manageKytSettings が必要）
• scripts/get_kyt_applicant_assessment.sh — 申請者の評価スコアリング設定を取得
• scripts/patch_kyt_applicant_assessment.sh — 申請者の評価スコアリング設定を置換（manageKytSettings が必要）
• scripts/get_kyt_risk_level_settings.sh — 現在の申請者リスクレベルのしきい値を取得
• scripts/patch_kyt_risk_level_settings.sh — 申請者リスクレベルのしきい値を置換（最小 2 件、manageKytSettings が必要）
• scripts/get_kyt_client_list.sh — 名前を指定してクライアントリストが存在するか確認
• scripts/create_kyt_client_list.sh — クライアントリストを作成（冪等）
• sumsub-manage-client-lists — 型付きクライアントリストの作成、値の登録、メンバーシップの確認
• sumsub-create-transaction — ルールを検証するテスト取引を送信
• sumsub-check-permissions — テナントの権限を確認
• sumsub-api-auth — 認証リファレンス