sumsub-create-questionnaire

Sumsub — 创建问卷

根据精简规范构建问卷定义 JSON 负载，将其 POST 到 Sumsub API，并报告生成的 id（客户端提供的 slug）和 _id（服务器分配的标识符）。

端点

方法	路径	适用情况
POST	/resources/api/agent/questionnaires	创建新问卷。如果 id 已存在，则返回 409 CONFLICT。
PATCH	/resources/api/agent/questionnaires	更新现有问卷（通过请求体中的 id 指定）。如果问卷不存在，则返回 404 NOT_FOUND。
GET	/resources/api/agent/questionnaires/{id}	读取单个问卷（核实实际创建的内容；通过已知的 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}）。

身份验证 — 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。

如果用户已在对话中提供凭据，请重复使用；否则，请在运行前询问一次。切勿回显密钥。

租户权益

创建问卷需要 QUESTIONNAIRE 权益。在执行其他操作之前，先调用 sumsub-check-permissions 技能，并确认 allowedChecks 映射中包含 QUESTIONNAIRE 键。

如果 allowedChecks 中没有 QUESTIONNAIRE，请立即停止。 不要构建或 POST 问卷。告知用户缺少该权益，并说明他们需要联系自己的 CSM 或 Sumsub 支持团队以启用该权益。

操作流程

0. 获取租户权限 — 参见上文。

1. 收集规格。 将用户的问题映射为下方的紧凑规格格式 — 切勿手动编写完整的本地化负载。

2. 验证 — 确认 id 是唯一的 slug，每个条目都有受支持的 type，每个条件引用都指向真实的 <sectionId>.<itemId>。

3. 生成负载：将规格通过标准输入传给 ${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py 运行。简要检查输出。

4. 创建或更新 — POST/PATCH 脚本接受作为路径参数的负载，或从标准输入读取（可将 build_questionnaire.py 的输出通过管道传入，以便一行完成）：

   • 新建 — 通过 ${CLAUDE_SKILL_DIR}/scripts/post_questionnaire.sh <payload.json> 执行 POST（或使用 … | post_questionnaire.sh -）。如果用户提供的 id 是之前用过的，先通过 ${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh 执行 GET，以避免出现 409 CONFLICT。
   • 更新现有项 — 先通过 ${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 工作区 — 这是所有技能共用的标准 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 前摘要、流程中的状态更新、诊断信息 — 不仅限于最终报告：

• 在文字中使用 title（“申请人基本信息”）而非 id slug 来指代问卷。
• slug id 仅用于最后专门的一行（Questionnaire ID (slug): <id>）— 这是唯一可以直接显示原始 ID 的地方，因为用户需要将其复制到关卡的 questionnaireDefId 中。
• 提及分区或条目时，优先使用其 title 而非 id。

移交给 sumsub-create-level

此处返回的 id（问卷 slug）是传入关卡 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 — 包含条件分支的多部分规范。