sumsub-api-generic

Sumsub — 汎用 API フォールバック

最後の手段として使うスキルです。Sumsub API には約 130 個のエンドポイントがあります。 OpenAPI 3.0.1 スキーマ が信頼できる唯一の情報源です。推測する前に読み込んでください。

呼び出すタイミング

ユーザーが api.sumsub.com に対する何らかの操作を求めているものの、該当する専用スキルがない場合に使います。例：

• 「申請者 X の最新の審査ステータスを取得して」
• 「このワークスペースにあるすべての質問票を一覧表示して」
• 「レベル Z のユーザー Y 用に SDK アクセストークンを生成して」
• 「申請者 W を承認済みにして」
• 「この申請者に紐付く AML ヒットを取得して」
• 「タグを追加するには、どのエンドポイントを呼び出せばいいですか？」

依頼が次のいずれかに明らかに該当する場合：

• sumsub-api-auth — 認証の仕組み、署名のデバッグ、401 のトリアージ。
• sumsub-create-questionnaire — QuestionnaireDefinition の作成。
• create-sumsub-level — ApplicantLevel のエンドツーエンドの作成。

…代わりにそのスキルを使ってください。このスキルは、それ以外のすべてを対象としています。

認証

リポジトリ内のほかのスキルと同じ App-Token-+-secret フローです。サンドボックストークンのみ使用してください。 詳しい説明と署名に関する注意点は、sumsub-api-auth を参照してください。ヘルパースクリプト ${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh（認証スキルのものと同等）は、sbx: で始まらないトークンを拒否します。

ユーザーから SUMSUB_APP_TOKEN と SUMSUB_SECRET_KEY が提供されていない場合は、作業を中止して尋ねてください。本番環境の認証情報は、見つけ次第拒否してください。

厳守事項：手当たり次第のデバッグは禁止

エンドポイントのパスを決して推測しないでください。 /resources/kyt/vasps、次に /resources/kyt/travelRule/vasps、さらに /resources/vasps、…と試してはいけません。スキーマには約 1800 個のパスがあります。推測するより検索するほうが、常に速く、無駄もありません。find_endpoint.py で一致する結果がない場合は、別のキーワードを試すか、スキーマを直接確認してください。パスを入力してよいのは、スキーマにそのパスが存在すると示されている場合だけです。

手順

0. スキーマは自動取得されます

以下のヘルパースクリプトは、初回使用時に https://api.sumsub.com/agents-openapi.json から OpenAPI スキーマを取得し、 24 時間キャッシュします。保存先は ~/.cache/sumsub/openapi.json（または $XDG_CACHE_HOME/sumsub/）です。 古くなったキャッシュは、次回の実行時に自動的に更新されます。スキーマの取得自体に App Token や secret は必要ありません。必要になるのは、その後に呼び出すエンドポイントだけです。

SUMSUB_SCHEMA_REFRESH=1 を設定するか、 ${CLAUDE_SKILL_DIR}/scripts/refresh_schema.py を実行すると、強制的に更新できます。

上書き用の設定：

• SUMSUB_OPENAPI=/abs/path.json — キャッシュとネットワークを使わず、ローカルファイルを使用します。
• SUMSUB_OPENAPI_URL=https://… — 別のホストから取得します（プライベートミラーなど）。

スキーマは約 750 KB／約 120 パスです。必要であれば全体を読み込めますが、ヘルパーを使って検索・解析することもできます。記憶を頼りにエンドポイントの形式を作り上げたり、パスをでっち上げたりしないでください。

1. 必ずスキーマを検索する

何よりも先に、次を実行してください：

${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py <keyword>

例：

${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py vasp
${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py applicants tags
${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py accessTokens

エンドポイントを見つける正しい方法はこれだけです。スキーマから一致する結果が得られるまで、ステップ 2 に進まないでください。

2. 適切な一致を選ぶ

出力形式：METHOD path — summary (operationId)。find_endpoint.py が返した一覧から、最適なものを選んでください。曖昧さが残る場合は、決定する前に候補一覧をユーザーに提示してください。

3. オペレーションの全容を確認する

リクエストパラメーター、ボディスキーマ、レスポンスの形式を出力します：

${CLAUDE_SKILL_DIR}/scripts/show_endpoint.py GET /resources/applicants/{applicantId}/one

スキーマを読み、推測しないでください。特に次の点に注意してください：

• パスパラメーター — 署名する前に置き換えます。
• クエリパラメーター — 署名するリクエスト URI に含める必要があります。
• リクエストボディの必須フィールド。
• 認証要件 — ほぼすべてのエンドポイントで app-token 認証が使われます。異なる認証方式があれば明示してください。

4. ペイロードを作成する

書き込み操作では、JSON ボディの案を作成し、送信前にユーザーに提示してください。 各フィールドの意味と、仮定したデフォルト値を明示してください。取り消せない操作（ステータス変更、削除、ブラックリスト登録）については、確認を求めてください。

5. 署名して送信する

${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh GET  /resources/applicants/{applicantId}/one
${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh POST /resources/applicants/{applicantId}/tags tags.json

ラッパーは ts + METHOD + path?query + body に HMAC-SHA256 で署名し、 https://api.sumsub.com に送信します。出力の最終行は HTTP <code> です。

6. 検証する

状態を変更する呼び出しでは、エンティティを再取得し、変更が実際に反映されたことを確認します。Sumsub では、API の入口でフィールドが受け付けられた後、テナントの権限設定により、何も通知されないまま破棄されることがあります。不一致があれば報告してください。

読み取りでは、レスポンス全体をそのまま出力するのではなく、関連するフィールドをユーザーに提示してください。Sumsub のレスポンスの大半はサイズが大きいためです。

よくある落とし穴

• 署名でのパスパラメーターの展開。 テンプレート（/resources/applicants/{applicantId}/one）ではなく、解決済みのパス（/resources/applicants/abc123/one）に署名する必要があります。ヘルパースクリプトは渡された文字列をそのまま署名するため、先に解決してください。
• クエリ文字列のエンコード。 + と %20 の違い、順序、同じキーの繰り返しなど、署名文字列は実際に送信する内容と完全に一致させる必要があります。URL を一度だけ組み立て、再利用してください。
• 意図せずボディが付く GET／DELETE。 HTTP クライアントによっては Content-Length: 0 や空のボディが追加されます。ヘルパーでは追加されませんが、別のクライアントに切り替える場合は注意してください。空のボディの場合、署名文字列には何も追加しません。
• ページネーション。 多くの一覧エンドポイントはカーソルまたはオフセット方式でページングするため、スキーマを確認してください。1 ページだけを見て「結果なし」と判断しないでください。

関連項目

• sumsub-api-auth — 認証の詳細と 401 Invalid signature のトラブルシューティング。
• Sumsub API リファレンス — 人が読みやすい形式のドキュメントです。スキーマより更新が遅れていることが多いため、照合してください。