sumsub-create-level

用途

Sumsub Create Level 是一个用于在 Sumsub 平台创建或更新“申请人等级（Applicant Level）”的 Agent 技能。等级是 Sumsub 验证流程的配置单元，定义了申请人在 WebSDK 流程中需要完成的文档集（docSet）步骤及其顺序。该技能把用户提供的紧凑规格转换为完整的 ApplicantLevel JSON 载荷，并调用 Sumsub API 完成写入。

主要能力

创建等级：使用 POST /resources/applicants/-/levels 创建新等级。请求体不得包含 id 或 key——由服务端分配。
更新等级：使用 PATCH /resources/applicants/-/levels 按请求体中的 id 更新已有等级。
读取单个等级：使用 GET /resources/applicants/-/levels/{id} 核验写入结果（某些字段可能被租户门控静默丢弃），或从已知 id 解析名称。
列出全部等级：使用 GET /resources/applicants/-/levels 在创建前复用已有等级，避免重复。
构建载荷：根据紧凑规格（JSON 或 YAML）构建完整载荷，并为各 docSet 类型填入默认值。
校验：确认每个 type 是真实存在的 IdDocSetType；QUESTIONNAIRE 步骤必须有指向已有问卷的 questionnaireDefId；PROOF_OF_RESIDENCE 步骤必须有 poaPresetId / poaStepSettingsId；COMPANY 步骤至少有一个命名子步骤。
生成仪表盘链接：从响应体读取 id、applicantType、clientId，拼出可点击的沙箱仪表盘链接。

使用方式

鉴权：使用 App Token + secret（仅沙箱）。环境变量包括 SUMSUB_APP_TOKEN（沙箱 App Token，以 sbx: 开头）、SUMSUB_SECRET_KEY（配套密钥，仅在创建时展示一次）、SUMSUB_BASE（可选，默认 https://api.sumsub.com）。沙箱 Token 可在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。若用户提供生产 Token，应拒绝并要求改用沙箱 Token。辅助脚本会拒绝不以 sbx: 开头的 Token。不要回显密钥。

流程：

先获取租户权益：调用 sumsub-check-permissions 技能，解析 JSON 结果，保存 allowedChecks（其键即已启用的权益），用于后续功能门控检查。
检查已有实体：先列出已有等级、POA 预设和问卷。若已有匹配实体，建议复用其 id 并跳过 POST——服务端每次 POST 都会创建重复项，不做名称去重。
将用户请求翻译成紧凑规格：名称、申请人类型，以及按顺序排列的 docSet 步骤列表。若涉及数据库/非文档验证，先通过 sumsub-check-databases 解析来源。
校验字段合法性（见上文）。使用 step 0 的 allowedChecks 键拒绝任何未具备权益的门控功能。
生成载荷：运行 ${CLAUDE_SKILL_DIR}/scripts/build_level.py，规格从 stdin 传入，完整载荷从 stdout 输出。
向用户展示解析后的载荷，并在首次 POST 前请求明确确认。
创建或更新：新等级用 ${CLAUDE_SKILL_DIR}/scripts/post_level.sh POST；更新用 get_level.sh 先 GET 当前状态展示差异，再用 patch_level.sh PATCH。PATCH 时规格必须包含 id。注意 PATCH 会整体替换 requiredIdDocs.docSets 数组，每个发送的 docSet 都必须携带完整目标状态，被省略的字段会被清除。
回读比对：用 get_level.sh GET 回来，与发送内容比对，报告差异。
构建仪表盘链接：格式为 https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&sbx=true。
报告：先给出可读名称，再列 applicantType、docSets 有序列表、可点击仪表盘链接，最后一行给出 Level ID。4xx 错误应原样呈现。

紧凑规格示例：

{
  "name": "Basic KYC",
  "applicantType": "individual",
  "type": "standalone",
  "docSets": [
    {"type": "IDENTITY", "docTypes": ["PASSPORT","ID_CARD","DRIVERS"]},
    {"type": "SELFIE", "videoRequired": "passiveLiveness"},
    {"type": "PROOF_OF_RESIDENCE", "docTypes": ["UTILITY_BILL"]},
    {"type": "QUESTIONNAIRE", "questionnaireDefId": "source-of-funds"}
  ]
}

新等级必须为 WebSDK 2.0（websdkNext: true）。创建时构建器会自动设置；更新已有等级时构建器不改动该字段，也不应作为无关 PATCH 的副作用翻转它。

支持的 docSets[].type：APPLICANT_DATA、EMAIL_VERIFICATION、PHONE_VERIFICATION、IDENTITY、IDENTITY2/3/4、SELFIE、SELFIE2、PROOF_OF_RESIDENCE、PROOF_OF_RESIDENCE2、PROOF_OF_PAYMENT、PAYMENT_METHODS、INVESTABILITY、COMPANY、COMPANY_DATA、COMPANY_DOCUMENTS、COMPANY_BENEFICIARIES、ACCREDITED_INVESTOR、E_SIGN、QUESTIONNAIRE/2/3/4、E_KYC、OTHER_DOCS、TR_RECIPIENT_INFORMATION、DEVICE_CHECK。

适用场景

为客户或租户配置新的 KYC / KYB 验证等级。
调整已有等级的文档集步骤、采集方式、NFC 验证等设置。
在创建前复用已有等级、POA 预设或问卷，避免重复。
验证支付方式（银行卡、银行账户、加密钱包、电子钱包），既可作为一个普通等级中的步骤，也可作为 actions 类型等级上的 action（设置 type: "actions" 与 actionType）。

限制与注意事项

仅沙箱：创建等级是工作区可见的写操作，不接受生产 App Token。
权益门控：许多等级设置受租户权益（allowedChecks）门控。若请求的功能需要租户不具备的权益，应立即停止，不构建也不 POST，并告知用户缺失的权益及需联系 CSM 或 Sumsub 支持启用。POA 是例外——POA / ADVANCED_POA_TYPE_DETECTION 键即使 API 实际接受 PROOF_OF_RESIDENCE 等级也常缺失，此时可带一行警告继续。
AML / 名单筛查有两个独立门控：租户级 WATCHLISTS 权益（缺则该租户整体关闭，等级设置无法开启）；等级级 disableWatchlists（仅在租户有 WATCHLISTS 时有效，发送 true 关闭筛查）。watchListCheckSettings.amlCaseType 仅选择提供商（受租户门控），useCustomWatchListCheckSettings 仅选择自定义还是继承配置，二者均非开关。
PATCH 语义：requiredIdDocs.docSets 整体替换，只有顶层 Level 字段做合并。省略的子字段会被清除，需先 GET 并复制要保留的值。
安全实践：首次 POST 前必须展示载荷；每次成功 POST 后回读比对（静默覆盖很常见）；会话中已成功的依赖项（PoA 预设、问卷）不要重复 POST，复用返回 id；除非用户明确指名，不要删除或修改非本会话创建的等级。
用户消息用名称而非 id：面向用户的消息中应使用名称/标题（如 POA 预设«POA — 60 days»、问卷«Applicant basics»），不粘贴原始 id；唯一适合放原始 id 的位置是最终报告的最后一行 Level ID。4xx 响应引用依赖 id 时，先翻译成名称再展示。
文档中未提供的信息：具体收费、价格、平台覆盖范围、实际效果等资料未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项