sumsub-create-questionnaire

Sumsub — アンケートの作成

簡潔な仕様からアンケート定義の JSON ペイロードを構築して Sumsub API に POST し、結果の id（クライアントが指定したスラッグ）と _id（サーバーが割り当てた識別子）を報告します。

エンドポイント

メソッド	パス	タイミング
POST	/resources/api/agent/questionnaires	新しいアンケートを作成します。id がすでに存在する場合は 409 CONFLICT で失敗します。
PATCH	/resources/api/agent/questionnaires	既存のアンケートを更新します（本文内の id で指定）。該当するアンケートが存在しない場合は 404 NOT_FOUND で失敗します。
GET	/resources/api/agent/questionnaires/{id}	1 件のアンケートを読み込みます（登録内容の確認や、既知の id から title を解決する場合に使用）。
GET	/resources/api/questionnaires/list	すべてのアンケートを一覧表示します。（引き続き agent なしのパスを使用します。）
GET	/resources/api/questionnaires/usedByLevels	参照しているレベルとともにアンケートを一覧表示します。（引き続き agent なしのパスを使用します。）

いずれも manageClientSettings 権限が必要です。本文の形式は アンケートのスキーマで定義されています。使用できるのはクライアントが設定可能なフィールドのみです（clientId、createdAt、監査メタデータはサーバーが管理します）。

POST と PATCH の違い — 現在は厳密に動作します。POST は既存の id を拒否し、PATCH は存在しない id を拒否します。INT-4893 以前の「POST での単一 upsert」動作は廃止されました。必ず適切なメソッドを事前に選択してください（アンケートが存在するか不明な場合は、最初に GET /{id} を呼び出してください）。

認証 — アプリトークン + シークレット（サンドボックスのみ）

このスキルは公開 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 です。

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

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

アンケートを作成するには QUESTIONNAIRE エンタイトルメントが必要です。ほかの作業を始める前に、sumsub-check-permissions スキルを呼び出し、allowedChecks マップにキーとして QUESTIONNAIRE が存在することを確認してください。

QUESTIONNAIRE が allowedChecks にない場合は、直ちに処理を停止してください。 アンケートの構築や POST は行わないでください。エンタイトルメントが不足していること、および有効化するには担当の CSM または Sumsub サポートに連絡する必要があることをユーザーに伝えてください。

手順

0. テナントの利用権限を取得します — 上のセクションを参照してください。

1. 仕様をまとめます。 ユーザーの質問を、以下の簡潔な仕様形式に変換します — ローカライズ済みペイロード全体を手書きしてはいけません。

2. 検証します — id が一意のスラッグであること、すべての項目の type がサポートされていること、条件付き参照がすべて実在する <sectionId>.<itemId> を指していることを確認します。

3. ペイロードを生成します — 仕様を標準入力から ${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py に渡して実行します。出力を簡単に確認します。

4. 新規作成か更新かを判断します — POST／PATCH スクリプトは、ペイロードをパス引数または標準入力で受け取ります（1 行のコマンドで済ませるには、build_questionnaire.py からパイプします）。

   • 新規作成 — ${CLAUDE_SKILL_DIR}/scripts/post_questionnaire.sh <payload.json> で POST します（または … | post_questionnaire.sh -）。ユーザーが以前使った id を指定している場合は、409 CONFLICT を避けるため、先に ${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh で GET します。
   • 既存のものを更新 — まず ${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh で GET し、上書きする内容をユーザーに確認してから、${CLAUDE_SKILL_DIR}/scripts/patch_questionnaire.sh <payload.json> で PATCH します。

5. ダッシュボードのリンクを作成します。 レスポンス本文から id と clientId を読み取って（永続化された質問票には両方のフィールドがあります）、次の形式にします。

   https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&sbx=true
   

   sbx=true クエリパラメーターは Sandbox ワークスペースを指定します。これは、すべてのスキルで共通の正式なサンドボックスリンク用パラメーターです。

6. 結果を報告します — 人が読めるタイトルから始めます。

   • title、セクション数／項目数、該当する場合は国／言語の対応範囲。
   • クリック可能な Markdown リンクとしての ダッシュボードリンク。
   • 最終行：Questionnaire ID (for level wiring / future PATCH): <id>。

   4xx エラーがあれば、エラー本文の description フィールドを提示します。POST で 409 CONFLICT が発生した場合は、代わりに PATCH を提案します。

簡潔な仕様形式

標準入力では JSON または YAML を使用できます。英語のタイトルは自動的に localizedTitle／localizedDesc に設定されます。表示／非表示のロジックには condition 文字列を使用します。構文については references/questionnaire-schema.md を参照してください。

{
  "id": "source-of-funds",
  "title": "Source of Funds",
  "desc": "Optional one-liner shown to applicants.",
  "showTitleAsStepName": true,
  "sections": [
    {
      "id": "primary",
      "title": "Primary Source",
      "desc": "Optional section description.",
      "condition": null,
      "items": [
        {"id": "main", "title": "Main source?", "type": "select", "required": true,
         "options": [["salary","Salary"],["business","Business"],["other","Other"]]},
        {"id": "other", "title": "Specify", "type": "text",
         "condition": "primary.main = other"}
      ]
    }
  ]
}

サポートされている項目の種類

text、textArea、date、dateTime、bool、select、phone、selectDropdown、multiSelect、countrySelect、countryMultiSelect、fileAttachment、multiFileAttachments。

select／selectDropdown／multiSelect では options: [[value, title], ...] が必要です。

出力

成功した場合は、人が読める情報から始めます。

• title、セクション数／項目数、createdAt。
• ダッシュボードリンク：https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&sbx=true。エンティティを開けるよう、クリック可能な Markdown リンクとして表示します。id と clientId はどちらも POST レスポンス本文に含まれます。sbx=true は Sandbox ワークスペースを指定します。
• 最後に、独立した行として：Questionnaire ID (slug, for level wiring / future PATCH): <id>。

失敗した場合：HTTP ステータスとエラーエンベロープの description／type を表示します。むやみに再試行しないでください。POST で 409 CONFLICT が発生した場合は、更新に PATCH を使うよう提案します。

ユーザー向けメッセージでは ID ではなく名前を使います

これは、最終報告だけでなく、質問票に関するすべてのメッセージ（POST 前の概要、処理中の進捗状況、診断など）に適用されます。

• 質問票は、説明文では id スラッグではなく title（「Applicant basics」など）で示します。
• スラッグ id を記載するのは、専用の最終行（Questionnaire ID (slug): <id>）のみです。レベルの questionnaireDefId にコピーするため、未加工の ID を記載してよいのはこの行だけです。
• セクションや項目に言及する場合は、id よりも title を優先します。

sumsub-create-level への引き継ぎ

ここで返される id（質問票のスラッグ）は、レベルの QUESTIONNAIRE ドキュメントセットに渡す値です。レベルスキルでは questionnaireDefId（正式名）または questionnaireId（別名）として受け付けられます。

{
  "type": "QUESTIONNAIRE",
  "questionnaireDefId": "<id from this skill>"
}

sumsub-create-level/examples/with-presets.json を参照してください。

関連項目

• references/questionnaire-schema.md — 全フィールドの一覧、条件式、注意点。
• examples/source-of-funds.json — 条件分岐を含む複数セクションの仕様。