SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sumsub-manage-applicant-tags

sumsub-manage-applicant-tags

安全与审计

查看项目

更新于 10-15 18:10

技能介绍

用途

该技能用于管理 Sumsub 申请人档案上的标签（tags）。标签是自由文本形式的标签，用于申请人列表中的筛选与分类，同时可在工作流路由和交易监控（TM）规则表达式中通过 applicant.tags 读取。技能覆盖标签的追加、整体覆盖替换和删除，并在每次写入后执行回读校验。

主要能力与接口

  • POST /resources/applicants/{applicantId}/tags/add：在现有标签集合之上追加标签，属增量操作；重复添加已存在的标签会在服务端去重。请求体为纯 JSON 字符串数组。
  • POST /resources/applicants/{applicantId}/tags：覆盖写入，用请求体替换整个标签集合；传 [] 会清空所有标签。属破坏性操作，需要先执行确认步骤。
  • DELETE /resources/applicants/{applicantId}/tags：仅删除请求体中列出的标签，其余保留。
  • GET /resources/applicants/{applicantId}/one：回读接口。标签在申请人的 tags 字段中返回，没有专门的标签 GET 接口。

所有写入成功时返回 {"ok": 1}。未出现过的标签名在追加和覆盖接口上都会自动创建（沙箱已验证；文档中关于覆盖需要预先存在标签的说法已过时）。

标签定义（重命名标签、选择颜色、是否将标签纳入申请人摘要报告）只能在 Sumsub 控制台的 Applicant tags 页面设置，没有公共 API 接口。

认证方式

该技能调用 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：沙箱 App Token，形如 sbx:...
  • SUMSUB_SECRET_KEY：创建令牌时一次性显示的配对密钥
  • SUMSUB_BASE：可选，默认 https://api.sumsub.com

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

使用方式

  1. 选择操作。默认使用增量的 add，安全且会去重。仅当用户明确要替换整个集合（或清空）时才用 overwrite；用 remove 移除特定标签。add 或 remove 之前不要预先 GET，因为这两个接口是定向且幂等的，第 3 步的回读即为验证。
  2. 仅覆盖操作需先确认。GET 申请人，向用户展示将被丢失的当前标签，获得明确确认后再 POST 替换集合。清空所有标签（以 [] 覆盖）同样适用此确认门槛。
  3. 通过编排脚本执行写入（脚本会自动附加回读）：
bash scripts/manage_applicant_tags.sh list      <applicantId>
bash scripts/manage_applicant_tags.sh add       <applicantId> "High Risk" "VIP"
bash scripts/manage_applicant_tags.sh overwrite <applicantId> "Compliance Reviewed"   # after the confirm step!
bash scripts/manage_applicant_tags.sh remove    <applicantId> "Legacy KYC"
  1. 将回读结果与请求内容比对。空集合在 GET /one 中表现为 tags 字段缺失，这是正常的“无标签”状态，不是错误。若不一致，报告即可，不要自动重试。4xx 错误需原样呈现。
  2. 报告时名称优先。先给出申请人姓名和结果标签列表，然后是控制台链接（https://cockpit.sumsub.com/checkus/applicant/<applicantId>，渲染为可点击的 markdown 链接），最后单独一行放申请人 id。

适用场景

适用于需要对 Sumsub 申请人进行筛选、分类、流程路由或交易监控规则判断的场景，例如为高风险申请人打标、标记 VIP、记录合规审核状态等。

限制与注意事项

  • 每个申请人最多 30 个标签。超出（已有 + 新增）会导致整个请求失败并返回 HTTP 400 "Too many applicant tags"，且为原子操作，不会应用任何更改。应报告 30 标签上限并停止：不要裁剪列表后重试，也不要在同一次运行中删除或覆盖现有标签来腾出空间——释放槽位是破坏性决定，必须由用户在全新请求中明确做出。
  • 标签名区分大小写，"High Risk" 与 "high risk" 是两个不同标签。删除时需匹配用户已有的大小写。
  • 覆盖会替换一切。POST .../tags 带任何请求体都会清除未列出的标签。当用户说“add”时，绝不要使用覆盖接口。
  • 空即缺失。清空标签后，GET /one 完全没有 tags 字段。回读逻辑必须将缺失字段视为空集合。
  • 未知申请人返回 HTTP 404 "Applicant with id ... not found (anf)"（不是 400）。请用户重新核对 id。
  • 标签变更会触发 applicantTagsChanged webhook，若租户订阅了该事件则相关（见 sumsub-manage-webhooks）。

相关技能

  • sumsub-create-kyt-rules：交易标签、带评分权重（scoreWeight）的标签定义、申请人风险评估。
  • sumsub-create-workflow：作为工作流动作节点自动添加/移除标签；基于 applicant.tags 的路由。
  • sumsub-manage-webhooks：订阅 applicantTagsChanged。

Sumsub 文档：Applicant tags、Add and overwrite applicant tags、Add applicant tags、Remove applicant tags。