sumsub-create-cross-check-preset

Sumsub — クロスチェックプリセットの作成／更新

⚠️ このスキルを実行する前にお読みください。

Sumsub のデフォルトのクロスチェックプリセットは、コンバージョン率と承認率のバランスが最適になるよう調整されています。ほとんどのクライアントは変更する必要がありません。 ユーザーが変更したい具体的な比較項目を指定していない場合は、作業を中止し、次のように伝えてください。

「クロスチェックルールは、最適な承認率になるようすでに設定されています。 デフォルトのままにすることを強くおすすめします。必要な変更があれば、具体的に教えてください（例：「住所のあいまい一致を許可する」「ミドルネームを無視する」）。最小限の上書き設定を作成します。」

ユーザーが具体的な変更内容を指定した場合に限り、続行してください。

クロスチェックプリセットとは

クロスチェックプリセットは、**本人確認（POI）**書類に記載された名前と住所を、**住所確認（POA）**書類の同じ項目と Sumsub がどのように比較するかを制御します。プリセットによって、「Jonathan」と「Jon」、「Apt 4」と「Apartment 4」のような小さな違いを許容するか、不一致としてフラグを立てるかが決まります。

POA プリセットの crossValidator と混同しないでください。
sumsub-create-poa-preset スキルには、PoaDocumentSettings の内部ブロックである crossValidator（CrossValidatorSettings）があり、nameMode／addressMode／fuzzyThreshold を指定できます。これは同じ比較に対するPOA プリセットごとの上書き設定です。ワークスペースレベルの CrossCheckPreset（このスキル）は、POA プリセットによる上書きが適用されない場合のデフォルトを設定します。POA プリセットに crossValidator が設定されている場合、そのプリセットで処理される書類にはそちらが優先されます。

プリセットには、次の 2 つのモードがあります。

• basic — このスキルで作成するモードです。小規模な列挙型から nameComparisonMode と addressComparisonMode を選択し、オプションの無視フラグを追加します。ほとんどのユーザーに最適です。
• advanced — ルールごとに手動で設定するモードです。公開 API ではサポートされていません（POST は 403 Forbidden — Advanced cross-check presets cannot be managed via API を返します）。ダッシュボードで設定する必要があります。

エンドポイント

メソッド	パス	用途
POST	/resources/api/agent/crossCheckPresets	新しいプリセットを作成します。リクエスト本文に id を含めてはいけません。
PATCH	/resources/api/agent/crossCheckPresets	既存のプリセットを更新します。リクエスト本文に id を含める必要があります。
GET	/resources/api/agent/crossCheckPresets/{id}	プリセットを 1 件取得します（反映された設定を確認し、既知の id から title を解決します）。

いずれも manageClientSettings 権限が必要です。リクエスト本文の形式は、クロスチェックプリセットのスキーマに従います（クライアントが設定可能なフィールドのみ）。

認証 — App Token とシークレット（サンドボックスのみ）

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

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

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

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

手順

1. 必要性を確認する — ユーザーのリクエストを1文で言い換え、デフォルト設定を維持することを改めて推奨します。具体的な名前付きの変更がある場合は続行します。それ以外の場合は停止します。
2. ユーザーの意図を簡潔な仕様に変換する（以下を参照）。リクエストを nameComparisonMode / addressComparisonMode / ignore-flags にマッピングします。
3. 検証する — title は空でないこと（256文字以下）、mode は basic であること（API経由ではadvancedは禁止）、すべての比較モードが有効な列挙値であることを確認します。
4. ペイロードを生成する — ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py に簡潔な仕様を標準入力で渡して実行し、完全なペイロードを標準出力に出力します。
5. 新規作成か更新かを判断する：
   • 新しいプリセット — ${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh 経由で POST します。ペイロードに id を含めてはいけません。
   • 既存のプリセットを更新 — まず ${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh 経由で GET し、ユーザーに差分を確認してもらってから、${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh 経由で PATCH します。ペイロードに id を含める必要があります。
6. プリセットを GET して内容を確認する — 反映された内容を検証します。
7. 結果を報告する — 人が読める概要から始め、最後にIDを記載します：
   • title と、デフォルトから変更した内容の1行の概要。
   • 注意：「最も高い承認率を得るにはデフォルトのクロスチェックルールが推奨されます。今回、これらの比較ではデフォルトを上書きしました。本番環境に展開する前に、コンバージョンを監視してください。」
   • 最終行：Preset ID (for level wiring / future PATCH): <id>。

簡潔な仕様の形式（標準入力でJSONまたはYAMLを指定）

title: "Strict address, lenient name"
description: "Allow nickname variants but require exact address."

mode: basic                          # ONLY basic — advanced is forbidden via API
basicSettings:
  nameComparisonMode: weakContainment  # one of: strict | weakContainment | def | ai
  addressComparisonMode: strict        # one of: strict | fuzzy
  ignoreMiddleNameMismatch: true
  ignoreProvidedInfoMismatch: false    # if true, don't flag user-typed info that disagrees with the doc

比較モードの意味

nameComparisonMode:

• strict — 完全一致が必要です。
• weakContainment — トークン単位の包含（例：「Jon Smith」 ⊆ 「Jonathan Andrew Smith」）。
• def — Sumsub が推奨するデフォルトです。厳密さとコンバージョンのバランスを取ります。
• ai — MLベースの比較です。一般的な表記ゆれや翻字に対応します。

addressComparisonMode:

• strict — 正規化後に文字単位で一致させます。
• fuzzy — 略語や語順の違いに対応します。

非推奨の値（名前の fuzzy、containment、fuzzyContainment）は、このスキルでは受け付けません。

出力

成功時は、人が読める情報から始めます：

• title と、ワークスペースのデフォルトから変更した内容の1行の概要。
• 注意：「最も高い承認率を得るにはデフォルトのクロスチェックルールが推奨されます。今回、デフォルトを上書きしました。本番環境に展開する前に、コンバージョンを監視してください。」
• 最終行：Preset ID (for level wiring / future PATCH): <id>。

失敗時は、HTTP ステータスと Sumsub の description / errorName を報告します。よくある原因：

• 403 Advanced cross-check presets cannot be managed via API — mode: advanced はダッシュボード専用です。basic モードに切り替えてください。
• 検証メッセージを含む 400 — 比較モードの列挙値のいずれかが誤っています（例：非推奨の名前モード fuzzy / containment / fuzzyContainment）。

使用例

• examples/strict-name-only.json — 名前の照合を厳格化し、住所はデフォルトのままにします。
• examples/lenient-for-emerging-markets.json — 住所はあいまい照合、名前は ai にし、ミドルネームの不一致を無視します。

引き継ぎ — プリセットをレベルに紐付ける

クロスチェックプリセットはワークスペース単位です。デフォルトのプリセットはすべてのレベルに自動適用されます。カスタムプリセットを作成した場合は、レベルの crossCheckPresetId を設定して、特定のレベルに紐付ける必要があります。 これは sumsub-create-level（または sumsub-api-generic 経由でレベルに直接 PATCH）を使用して行います。

関連項目

• references/cross-check-preset-schema.md — 完全なスキーマ、すべての列挙値、注意点。
• Sumsub cross-check docs。