mcpField
S
sumsub-api-generic

sumsub-api-generic

github.com/sumsub其他71.2k 次安装4 周前更新
代码仓库

关于 sumsub-api-generic

sumsub-api-generic 是处理其他专用技能未覆盖的 Sumsub API 任务的兜底技能。它要求依据架构查找接口、仅使用沙盒凭据，并在执行状态变更请求前征求确认。

主要功能

  1. 01在 OpenAPI 架构中搜索接口
  2. 02检查请求与响应定义
  3. 03仅使用沙盒凭据
  4. 04发送前审阅写入请求载荷
  5. 05请求后验证状态变更

适用场景

  1. 01查找未明确指定的 Sumsub API 接口
  2. 02获取申请人或问卷信息
  3. 03拟定并确认状态变更请求
  4. 04检查 API 更新是否生效

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sumsub/agent-skills --skill sumsub-api-generic

安装后在 Claude Code 中输入/sumsub-api-generic确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
_schema_cache.py
find_endpoint.py
refresh_schema.py
show_endpoint.py
sumsub_curl.sh

详细介绍

Sumsub — 通用 API 回退方案

最后手段技能。Sumsub API 有约 130 个端点。 OpenAPI 3.0.1 架构 是事实依据——猜测之前先阅读。

何时调用

用户要对 api.sumsub.com 执行某项操作，但没有任何特定技能适用。示例：

  • “获取申请人 X 的最新审核状态”
  • “列出此工作区中的所有问卷”
  • “为用户 Y 生成级别为 Z 的 SDK 访问令牌”
  • “将申请人 W 标记为已批准”
  • “提取关联到此申请人的 AML 命中记录”
  • “要添加标签，我应该调用哪个端点？”

如果请求明确符合以下任一项：

  • sumsub-api-auth — 身份验证机制、签名调试、401 问题排查。
  • sumsub-create-questionnaire — 构建 QuestionnaireDefinition。
  • create-sumsub-level — 从头到尾构建 ApplicantLevel。

……请改用对应技能。此技能适用于其他所有情况。

身份验证

与代码库中其他部分使用相同的 App-Token-+-secret 流程。仅限沙盒令牌。 有关深入说明和签名注意事项，请参阅 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，……架构中有约 1800 条路径——搜索总是比猜测更快、更简洁。如果 find_endpoint.py 没有返回匹配项，请尝试其他关键词，或直接检查架构。只有架构明确指出路径存在，才可以手动输入该路径。

操作步骤

0. 自动获取架构

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

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

可选设置：

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

架构约 750 KB，包含约 120 条路径——你可以按需通读，也可以使用辅助工具为你搜索或解析。不要试图凭记忆编造端点结构或路径。

1. 搜索架构——必做

开始任何其他操作前，先运行：

${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

这是查找端点的唯一正确方式。在从架构中找到匹配项之前，不要继续执行第 2 步。

2. 选择正确的匹配项

输出格式：METHOD path — summary (operationId)。从 find_endpoint.py 返回的列表中选择最匹配的项。如果仍有歧义，先向用户展示候选列表，再确定最终选项。

3. 完整检查操作定义

输出请求参数、请求体架构和响应结构：

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

阅读架构，不要猜测。尤其注意：

  • 路径参数 — 签名前先替换。
  • 查询参数 — 必须包含在签名所用的请求 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 或空请求体；辅助脚本不会这样做，但如果改用其他客户端，请留意这一点——空请求体意味着签名字符串中不追加任何内容。
  • 分页。 许多列表端点使用游标或偏移分页，请检查架构。不要仅凭单页结果就声称“没有结果”。

另请参阅

  • sumsub-api-auth — 完整的身份验证参考，以及 401 Invalid signature 问题排查。
  • Sumsub API 参考 — 面向用户的文档，内容往往滞后于架构；请交叉核对。

评论

支持 Markdown