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

sumsub-api-generic

安全与审计

查看项目

更新于 10-16 09:40

技能介绍

用途

该技能是 Sumsub API 的通用兜底方案（a skill of last resort），适用于用户需要对 api.sumsub.com 发起请求，但不匹配任何更具体技能的场合。Sumsub API 约有 130 个端点，OpenAPI 3.0.1 schema 是权威来源，使用前应先阅读 schema，而非凭记忆猜测端点。

何时调用

当用户提出的需求无法由以下更具体的技能覆盖时使用本技能：

  • sumsub-api-auth —— 认证机制、签名调试、401 排查。
  • sumsub-create-questionnaire —— 构建 QuestionnaireDefinition。
  • create-sumsub-level —— 端到端构建 ApplicantLevel。

资料中给出的示例场景包括：

  • "Get the latest review status for applicant X"（获取申请人 X 的最新审核状态）
  • "List all questionnaires in this workspace"（列出该工作区中的所有问卷）
  • "Generate an SDK access token for user Y at level Z"（为用户 Y 在级别 Z 生成 SDK 访问令牌）
  • "Mark applicant W as approved"（将申请人 W 标记为已通过）
  • "Pull the AML hits attached to this applicant"（拉取该申请人关联的 AML 命中记录）
  • "What endpoint do I call to add a tag?"（添加标签应调用哪个端点？）

认证

采用与仓库其余部分相同的 App Token 加密钥流程，仅使用沙箱令牌。详见 sumsub-api-auth 的认证与签名注意事项。辅助脚本 ${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh（与认证技能中的脚本一致）会拒绝任何不以 sbx: 开头的令牌。如果用户未提供 SUMSUB_APP_TOKEN + SUMSUB_SECRET_KEY，应停止并询问。一经发现生产凭证应拒绝。

硬性规则：禁止盲目试错

不要猜测端点路径。不应依次尝试 /resources/kyt/vasps、/resources/kyt/travelRule/vasps、/resources/vasps 等。schema 中约有 1800 条路径，猜测总是比搜索更慢、更嘈杂。如果 find_endpoint.py 无匹配，应换关键词或直接查阅 schema。唯一合理的输入路径理由，是 schema 确认其存在。

操作流程

0. schema 自动获取

辅助脚本会在首次使用时从 https://api.sumsub.com/agents-openapi.json 拉取 OpenAPI schema，并缓存 24 小时于 ~/.cache/sumsub/openapi.json（或 $XDG_CACHE_HOME/sumsub/）。过期缓存在下次调用时自动刷新。schema 获取本身无需 App Token 或密钥，只有后续调用的端点需要。

可用 SUMSUB_SCHEMA_REFRESH=1 强制刷新，或运行 ${CLAUDE_SKILL_DIR}/scripts/refresh_schema.py。

覆盖参数：

  • SUMSUB_OPENAPI=/abs/path.json —— 跳过缓存与网络，使用本地文件。
  • SUMSUB_OPENAPI_URL=https://… —— 从其他主机拉取（例如私有镜像）。

schema 约 750 KB / 约 120 条路径，可整体阅读，也可用辅助脚本 grep/解析。不要凭记忆伪造端点结构或路径。

1. 始终先搜索 schema

在一切操作之前运行：

${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py <keyword>

示例：

${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py vasp ${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py applicants tags ${CLAUDE_SKILL_DIR}/scripts/find_endpoint.py accessTokens

这是查找端点的唯一正确方式。在从 schema 获得匹配之前，不要进入第 2 步。

2. 选择正确匹配

输出格式为：METHOD path — summary （operationId）。从 find_endpoint.py 返回的列表中选取最佳匹配。若仍有歧义，在确定前向用户展示候选列表。

3. 完整检查该操作

导出请求参数、请求体 schema 和响应结构：

${CLAUDE_SKILL_DIR}/scripts/show_endpoint.py GET /resources/applicants/{applicantId}/one

阅读 schema，不要猜测。特别注意：

  • 路径参数 —— 签名前需替换。
  • 查询参数 —— 必须存在于你签名的请求 URI 中。
  • 请求体中的必填字段。
  • 认证要求 —— 几乎所有端点使用 app-token 认证；若发现不同，应标记。

4. 构造载荷

对于写操作，先起草 JSON 请求体并向用户展示后再发送。说明每个字段含义及任何假定的默认值。对于不可逆操作（状态变更、删除、加入黑名单）须请求确认。

5. 签名并发送

${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh GET /resources/applicants/{applicantId}/one ${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh POST /resources/applicants/{applicantId}/tags tags.json

包装脚本使用 HMAC-SHA256 对 ts + METHOD + path?query + body 签名，并发送至 https://api.sumsub.com。输出的最后一行是 HTTP <code>。

6. 校验

对于改变状态的调用，应重新获取该实体并验证变更确实生效。Sumsub 偶尔会在 API 边缘接受某字段后静默丢弃（租户权限门控）。报告任何不一致。

对于读操作，向用户呈现相关字段，不要直接倾倒整个响应。多数 Sumsub 响应体积很大。

常见陷阱

  • 签名中的路径参数展开。必须签名已解析的路径（/resources/applicants/abc123/one），而非模板（/resources/applicants/{applicantId}/one）。辅助脚本会对你传入的任意字符串签名，因此需先解析。
  • 查询字符串编码。+ 与 %20、顺序、重复键 —— 签名字符串必须与线上请求完全一致。构建一次 URL 并复用。
  • GET/DELETE 意外携带请求体。部分 HTTP 客户端会添加 Content-Length: 0 或空请求体；本辅助脚本不会，但若换用其他客户端需留意 —— 空请求体意味着签名字符串中不追加任何内容。
  • 分页。许多列表端点使用游标或偏移分页 —— 查阅 schema。不要仅凭单页就断言"无结果"。

参见

  • sumsub-api-auth —— 完整认证参考与 401 Invalid signature 排查。
  • Sumsub API 参考文档 —— 面向人类的文档，常滞后于 schema，需交叉核对。