sumsub-manage-applicant-tags

Sumsub — 管理申请人标签

为申请人资料添加、替换和移除标签，之后始终读取一次以确认结果。标签是用于在申请人列表中筛选和分类的自由格式标签；在工作流路由和 TM 规则表达式中，也可以通过 applicant.tags 读取这些标签。

端点

Verb	Path	Purpose
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 控制面板 UI（Applicant tags 页面）管理；公共 API 不提供相关接口。

身份验证 — 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: 开头的令牌。

Var	Example
SUMSUB_APP_TOKEN	sbx:... — 从控制面板获取的沙盒 App Token。
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"
   

4. 将读取确认结果与请求内容进行比较。 如果标签集为空，GET /one 返回的结果中会省略 tags 字段 — 这是正常的“无标签”状态，并非错误。如果不匹配，请报告情况 — 不要自动重试。按原样呈现 4xx 错误。

5. 报告结果，先写姓名。 先写申请人姓名和最终标签列表，再提供控制面板链接 （https://cockpit.sumsub.com/checkus/applicant/<applicantId> — 渲染为可点击的 Markdown 链接），并将申请人 id 单独放在最后一行。

注意事项

• 每位申请人最多 30 个标签。 超出限制（现有标签 + 新标签）会导致整个请求失败，并返回 HTTP 400 "Too many applicant tags" — 操作具有原子性，不会应用任何更改。请告知用户 30 个标签的限制，然后到此为止：不要缩减列表后重试，也绝不要在同一次运行中删除或覆盖现有标签来腾出空间 — 释放名额属于破坏性决策，必须由用户在新的请求中明确作出。
• 标签名称区分大小写 — "High Risk" 和 "high risk" 是两个不同的标签。移除标签时，请使用与用户现有标签一致的大小写。
• 覆盖会替换全部标签。 使用任何请求体调用 POST .../tags 都会清除未列出的标签。用户说“添加”时，绝不要使用覆盖端点。
• 空值 = 不存在。 清除标签后，GET /one 响应中完全不会包含 tags 字段。读取回传数据时，必须将缺失字段视为空集合。
• 申请人不存在 → HTTP 404 "Applicant with id ... not found (anf)"（不是 400）。请让用户重新检查 ID。
• 标签变更会触发 applicantTagsChanged webhook — 如果租户订阅了此 webhook，则需留意（参见 sumsub-manage-webhooks）。

另请参阅

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