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

sumsub-create-poa-preset

安全与审计

查看项目

更新于 10-16 12:53

技能介绍

用途

本技能用于创建或更新 Sumsub 的 Proof-of-Address（POA，地址证明）预设。它从一份紧凑规格构建 POA 预设 JSON 载荷，通过 Sumsub API 提交，并报告生成的预设 id，以便将其通过 level.requiredIdDocs.docSets[].poaStepSettingsId 挂载到一个或多个验证等级上。

前提

目标等级必须包含 PROOF_OF_RESIDENCE 步骤。POA 预设只有在至少一个等级中的 PROOF_OF_RESIDENCE（或 PROOF_OF_RESIDENCE2/3/4）文档集上被挂载后才会生效。若用户尚未创建（或描述）包含 POA 步骤的等级，应先提出这一点——孤立创建预设没有意义。

接口

  • POST /resources/api/agent/poaStepSettings：创建新预设。请求体不得包含 id，由服务端分配。
  • PATCH /resources/api/agent/poaStepSettings：更新已有预设。请求体必须包含 id（作为字段，而非 URL 中）。
  • GET /resources/api/agent/poaStepSettings/{id}：读取单个预设，用于校验落库结果或从已知 id 解析名称。

三者均需要 manageClientSettings 权限。请求体形状为 POA 预设 schema，仅含客户端可设置字段（clientId、createdAt、createdBy、modifiedAt、审计轨迹由服务端管理，并在响应中回显）。

创建后，通过编辑等级进行挂载：在任意 PROOF_OF_RESIDENCE 文档集上设置 requiredIdDocs.docSets[].poaStepSettingsId = "<新 id>"。

鉴权（App Token + secret，仅沙箱）

本技能访问 Sumsub 公开 API，并按鉴权参考对每个请求签名。完整说明见 sumsub-api-auth 技能——若遇到 401 Invalid signature 可参考。

⚠️ 仅限沙箱 token。不要接受或使用生产环境 App Token。若用户提供生产 token，应拒绝并请其在 https://cockpit.sumsub.com/checkus/home?sbx=true 生成沙箱密钥对（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。Token 与 secret 只显示一次——关闭对话框前请复制两者。辅助脚本会强制此限制——拒绝不以 sbx: 开头的 token。

变量示例：

  • SUMSUB_APP_TOKEN：sbx:...（仪表盘中的沙箱 App Token）
  • SUMSUB_SECRET_KEY：创建 token 时一次性显示的配对密钥
  • SUMSUB_BASE：可选，默认 https://api.sumsub.com

若用户已在对话中提供凭据，则复用；否则在运行前询问一次。切勿回显 secret。

租户权益

POA 预设创建历史上受 POA 权益限制，但实践中 API 对大多数租户都会接受写入——该权益通常为基础项、被其他 key 覆盖，或未在 allowedChecks 中体现。不要将其缺失视为阻塞。可调用 sumsub-check-permissions 检查 allowedChecks 作为诊断信息。若存在 POA，正常进行；若缺失，仍应进行，但以一行用户可见提示说明文档所述权益未列出（以便用户知晓 POST 失败时向支持提及什么）。不要为此中断确认——若租户确实无权限，Sumsub 自身会拒绝写入。若 POST 返回提及权益的 4xx，应原样呈现错误体并建议联系 CSM / Sumsub 支持。

流程

  1. 获取租户权益（见上）。
  2. 将用户意图翻译为紧凑规格：多数用户以“我们接受什么”（银行对账单、水电账单）和“有效多久”（月数）描述预设——映射到 providers keys、subTypes 和 validMonths。
  3. 校验：name 非空；includedCountries 与 excludedCountries 不可同时设置；每个 provider key 须为 PoaCompanyContactType；每个 subTypes 条目须为 PoaSubType；每个国家代码须为 ISO-3166-1 alpha-3 大写；crossValidator.fuzzyThreshold 在 [0, 1] 区间内。
  4. 通过 ${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py 生成载荷（stdin 输入紧凑规格 → stdout 输出完整载荷）。
  5. 创建或更新：新建——通过 ${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh POST，载荷不得带 id；更新——先通过 ${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh GET 当前状态以展示差异，再通过 ${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh PATCH，载荷须包含预设 id。
  6. 构建仪表盘链接：从响应体读取 id 与 clientId，格式为 https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&sbx=true（sbx=true 指向 Sandbox 工作区）。
  7. 报告：先给人类可读名称；id 仅在末尾作为传入后续 API 调用的值出现。

紧凑规格格式（stdin 输入 JSON 或 YAML）

包含 name、desc；国家范围（includedCountries 允许列表与 excludedCountries 屏蔽列表，至多选一）；settings 全局默认（acceptMultiplePages、acceptDocScreenshot、requireCountryMatch、useIssueDateForExpiry、validMonths、addressTypes、acceptableLanguages）；providers（bank、utilityProvider、governmentOrganization、mobileOperator、other），每个含 validMonths、acceptUnconventional、subTypes、allowedOrgs、forbidden* 字段；poiAsPoa（enabled、sameDoc、validMonths、allowedTypes）；crossValidator（nameMode、addressMode、fuzzyThreshold、ignoreMiddleName、ignoreFixedInfo）；byCountry 按国家覆盖（形状同 settings，仅覆盖所设键）。

枚举值：

  • provider 类型：bank、utilityProvider、governmentOrganization、mobileOperator、other
  • subTypes：statement、voterRegistration、taxBill、telecom、utilityBill、bankStatement、bankLetter、lease、universityLetter、employmentLetter、other
  • addressTypes：dwelling、poBox、poBoxSpecialCountries
  • POI-as-POA allowedTypes：PASSPORT、ID_CARD、RESIDENCE_PERMIT、DRIVERS 等标准 IdDocType
  • nameMode：strict、weakContainment、def、ai、fuzzy、containment、fuzzyContainment
  • addressMode：strict、fuzzy

输出

成功时：名称、国家范围、按国家覆盖的国家清单；简要摘要（覆盖的 provider 类型、默认有效期）；仪表盘链接（可点击 markdown 链接，id 与 clientId 来自 POST 响应体）；最后单独一行：Preset ID (for level wiring / future PATCH): <id>。失败时：HTTP 状态 + Sumsub 的 description/errorName。构建器会对无效枚举/不可能组合给出精确错误的预检拒绝。

面向用户的消息使用名称而非 id

此规则适用于每条关于预设的消息。散文中以名称指代预设（如“POA — 60 days”），而非 id。id 仅出现在最后专用的那一行。当调用方是等级技能链将此预设接入 PROOF_OF_RESIDENCE 步骤时，等级技能在其预 POST 摘要中也应以此预设的名称指代它。

交接给 sumsub-create-level

返回的 id 需传入等级的 PROOF_OF_RESIDENCE 文档集。等级技能将其暴露为友好的 poaPresetId 快捷方式（或规范的 poaStepSettingsId）：

{
  "type": "PROOF_OF_RESIDENCE",
  "docTypes": ["UTILITY_BILL", "BANK_STATEMENT"],
  "poaPresetId": "<id from this skill>"
}

参见 sumsub-create-level/examples/with-presets.json。

示例

  • examples/minimal.json——最小预设：6 个月银行/公用事业/政府默认，POI-as-POA 关闭。
  • examples/eu-bank-friendly.json——仅欧盟预设，宽松的银行对账单有效期，POI-as-POA 允许 3 个月。
  • examples/per-country-tight.json——全局默认加更严格的巴西覆盖。

参见

references/poa-preset-schema.md——完整的 PoaStepSettings schema、所有枚举与注意事项。