SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sumsub-create-questionnaire

sumsub-create-questionnaire

智能体与模型

查看项目

更新于 10-16 09:40

技能介绍

Sumsub — Create Questionnaire 技能用于构建、创建和更新 Sumsub 的 KYC 问卷定义。它从用户提供的紧凑规格（spec）生成完整的问卷定义 JSON 载荷，提交至 Sumsub API，并报告生成的 id（客户端提供的 slug）和 _id（服务端分配的标识符）。

用途与主要能力

该技能主要用于管理 Sumsub 平台上的 KYC 问卷。问卷可用于收集申请人的信息，如资金来源等。技能支持以下端点：

  • POST /resources/api/agent/questionnaires：创建新的问卷。如果 id 已存在，则返回 409 CONFLICT。
  • PATCH /resources/api/agent/questionnaires：更新已有问卷（根据请求体中的 id）。如果问卷不存在，则返回 404 NOT_FOUND。
  • GET /resources/api/agent/questionnaires/{id}：读取单个问卷（用于验证结果或根据已知 id 解析标题）。
  • GET /resources/api/questionnaires/list：列出所有问卷（使用非 agent 路径）。
  • GET /resources/api/questionnaires/usedByLevels：列出问卷及其被引用的层级（使用非 agent 路径）。

所有端点都需要 manageClientSettings 权限。请求体符合问卷模式，仅包含客户端可设置的字段（clientId、createdAt、审计元数据由服务端管理）。

POST 与 PATCH 行为严格区分：POST 拒绝已存在的 id，PATCH 拒绝不存在的 id。不再支持旧的单个 POST upsert 行为，因此需要先确定使用哪个动词。如果不确定问卷是否存在，可先调用 GET /{id} 检查。

认证方式

该技能访问公开的 Sumsub API，并按照认证参考对每个请求进行签名。详细工作原理参见 sumsub-api-auth 技能（如遇 401 Invalid signature 错误可查阅）。仅支持沙箱 App Token，不接受或使用生产环境的 App Token。如果用户提供生产 token，应拒绝并要求其生成沙箱 token。沙箱 token 可在 Sumsub 控制台生成。辅助脚本会强制检查 token 是否以 sbx: 开头。

可用的环境变量包括：

  • SUMSUB_APP_TOKEN：沙箱 App Token，格式如 sbx:...
  • SUMSUB_SECRET_KEY：与 token 配对的密钥，创建时仅显示一次。
  • SUMSUB_BASE：可选，默认为 https://api.sumsub.com。

如果用户已在对话中提供凭证，则重用；否则在运行前询问一次。不要回显密钥。

租户权限

创建问卷需要 QUESTIONNAIRE 权限。在执行任何操作前，需调用 sumsub-check-permissions 技能，并验证 allowedChecks 映射中包含 QUESTIONNAIRE 键。如果不存在，则立即停止，不要构建或提交问卷，告知用户缺少权限并联系 CSM 或 Sumsub 支持以启用。

操作步骤

  1. 获取租户权限（见上）。
  2. 收集规格。将用户的问题映射为紧凑规格格式，不要手写完整的本地化载荷。
  3. 验证：确认 id 是唯一的 slug，每个条目具有支持的类型，每个条件引用指向真实的 <sectionId>.<itemId>。
  4. 生成载荷：运行 ${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py，将规格通过标准输入传入，并检查输出。
  5. 创建或更新：POST/PATCH 脚本接受载荷路径或标准输入。对于新问卷，使用 post_questionnaire.sh；如果用户提供的 id 已存在，先通过 get_questionnaire.sh 获取以避免 409。对于更新，先 GET 查看当前内容，再 PATCH。
  6. 构建仪表板链接：从响应体读取 id 和 clientId，格式为 https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&sbx=true。sbx=true 参数指向沙箱工作区。
  7. 报告：以人类可读的标题开头，然后列出标题、章节/条目数量、国家/语言覆盖情况（如相关），提供仪表板链接，最后一行给出 Questionnaire ID（用于层级关联或未来 PATCH）。

错误处理：对于 4xx 错误，显示 HTTP 状态和错误体中的 description/type 字段。对于 POST 返回的 409 CONFLICT，建议改用 PATCH。

紧凑规格格式

接受 JSON 或 YAML 格式的标准输入。英文标题会自动包装为 localizedTitle / localizedDesc。使用条件字符串控制显示/隐藏逻辑。

示例：

{ "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], ...]。

输出

成功时，首先提供人类可读信息：标题、章节/条目数量、createdAt。然后提供仪表板链接（可点击），最后单独一行给出 Questionnaire ID（slug）用于层级关联或未来 PATCH。

失败时：打印 HTTP 状态和错误信封中的 description/type；不要盲目重试。对于 POST 返回的 409 CONFLICT，建议改用 PATCH。

用户消息中使用名称而非 ID

在所有关于问卷的消息中（POST 前摘要、流程状态更新、诊断），用标题指代问卷，而非 id slug。slug id 仅出现在最后专门一行（Questionnaire ID (slug): <id>），因为用户需要将其复制到层级的 questionnaireDefId 中。提到章节或条目时，优先使用标题而非 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：多章节规格，包含条件分支。