sumsub-api-generic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — generic API fallback

Sumsub — 通用API回退方案

A skill of last resort. The Sumsub API has ~130 endpoints. The OpenAPI 3.0.1 schema is the source of truth — read it before guessing.

这是最后的备选技能。Sumsub API拥有约130个端点。OpenAPI 3.0.1 Schema是权威来源——在猜测之前请先查阅它。

When to invoke

何时调用

The user is asking for something against

api.sumsub.com

but none of the specific skills apply. Examples:

"Get the latest review status for applicant X"
"List all questionnaires in this workspace"
"Generate an SDK access token for user Y at level Z"
"Mark applicant W as approved"
"Pull the AML hits attached to this applicant"
"What endpoint do I call to add a tag?"

If the ask clearly matches one of:

```
sumsub-api-auth
```
— authentication mechanics, signing debug, 401 triage.

sumsub-create-questionnaire

— building a

QuestionnaireDefinition

```
create-sumsub-level
```
— building an
```
ApplicantLevel
```
end-to-end.

…use that instead. This skill exists for everything else.

当用户请求针对

api.sumsub.com

的操作，但没有任何特定技能适用时。例如：

"获取申请人X的最新审核状态"
"列出此工作区中的所有问卷"
"为等级Z下的用户Y生成SDK访问令牌"
"将申请人W标记为已通过"
"提取与该申请人关联的AML命中记录"
"我应该调用哪个端点来添加标签？"

如果请求明确匹配以下任一技能：

```
sumsub-api-auth
```
— 认证机制、签名调试、401问题排查。

sumsub-create-questionnaire

— 构建

QuestionnaireDefinition

。

```
create-sumsub-level
```
— 端到端构建
```
ApplicantLevel
```
。

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

Auth

认证

Same App-Token-+-secret flow as the rest of the repo. Sandbox tokens only. See

sumsub-api-auth

for the deep dive and signing pitfalls. Helper script

${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh

(mirror of the auth skill's) refuses any token that doesn't start with

sbx:

If the user has not supplied

SUMSUB_APP_TOKEN

SUMSUB_SECRET_KEY

, stop and ask. Refuse production credentials on sight.

与仓库中其他技能使用相同的App-Token+密钥流程。仅允许使用沙箱令牌。如需深入了解认证流程和签名陷阱，请查看

sumsub-api-auth

。辅助脚本

${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh

（与认证技能中的脚本一致）会拒绝所有不以

sbx:

开头的令牌。

如果用户未提供

SUMSUB_APP_TOKEN

和

SUMSUB_SECRET_KEY

，请停止操作并询问用户。直接拒绝生产环境凭据。

Hard rule: no shotgun debugging

硬性规则：禁止盲目调试

Never guess endpoint paths. Do not try

/resources/kyt/vasps

, then

/resources/kyt/travelRule/vasps

, then

/resources/vasps

, … The schema has ~1800 paths — guessing is always slower and noisier than searching. If

find_endpoint.py

returns no matches, try a different keyword or check the schema directly. The only valid reason to type a path is because the schema told you it exists.

切勿猜测端点路径。不要尝试先调用

/resources/kyt/vasps

，再试

/resources/kyt/travelRule/vasps

，然后是

/resources/vasps

……Schema包含约1800个路径——猜测永远比搜索更慢、更混乱。如果

find_endpoint.py

未返回匹配结果，请尝试使用其他关键词或直接查看Schema。输入路径的唯一合理理由是Schema明确说明该路径存在。

Procedure

流程步骤

0. The schema is auto-fetched

0. Schema会自动获取

The helper scripts below pull the OpenAPI schema from https://api.sumsub.com/openapi.json on first use and cache it for 24 hours at

~/.cache/sumsub/openapi.json

(or

$XDG_CACHE_HOME/sumsub/

). Stale caches refresh transparently on the next invocation. No App Token or secret is required for the schema fetch itself — only for the endpoints you'll call later.

Force a refresh with

SUMSUB_SCHEMA_REFRESH=1

or by running

${CLAUDE_SKILL_DIR}/scripts/refresh_schema.py

Override knobs:

```
SUMSUB_OPENAPI=/abs/path.json
```
— skip cache + network, use a local file.
```
SUMSUB_OPENAPI_URL=https://…
```
— pull from a different host (e.g. a private mirror).

The schema is ~750 KB / ~120 paths — if you want you can read it as whole, but you can use the helpers grep/parse it for you. Do not try to fabricate endpoint shapes from memory, or invent paths.

以下辅助脚本在首次使用时会从https://api.sumsub.com/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个路径——你可以完整阅读它，也可以使用辅助工具进行搜索/解析。切勿凭记忆编造端点结构或路径。

1. Search the schema — always

1. 始终先搜索Schema

Before anything else, run:

bash

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

Examples:

bash

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

This is the only correct way to find an endpoint. Do not proceed to step 2 until you have a match from the schema.

在执行任何操作之前，运行：

bash

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

示例：

bash

${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. Pick the right match

2. 选择正确的匹配项

Output:

METHOD path  — summary  (operationId)

. Pick the best match from the list

find_endpoint.py

returned. Show the candidate list to the user before committing if any ambiguity remains.

输出格式为：

METHOD path  — summary  (operationId)

。从

find_endpoint.py

返回的列表中选择最匹配的项。如果存在歧义，请先向用户展示候选列表，再确定最终选择。

3. Inspect the operation in full

3. 完整查看操作详情

Dump request params, body schema, and response shape:

bash

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

Read the schema; do not guess. Note in particular:

Path params — substitute before signing.
Query params — must be in the request URI you sign.
Required fields in the request body.
Auth requirements — virtually all endpoints use
```
app-token
```
auth; flag if you see something different.

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

bash

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

阅读Schema，切勿猜测。特别注意：

路径参数 — 签名前需替换为实际值。
查询参数 — 必须包含在签名的请求URI中。
请求体中的必填字段。
认证要求 — 几乎所有端点都使用
```
app-token
```
认证；如果发现不同的认证方式，请标记出来。

4. Build the payload

4. 构建请求体

For writes, draft the JSON body and show it to the user before sending. Spell out what each field means and any assumed defaults. Ask for confirmation on anything irreversible (status changes, deletions, blacklisting).

对于写入操作，草拟JSON请求体并在发送前展示给用户。说明每个字段的含义以及任何默认假设。对于不可逆操作（如状态变更、删除、拉黑），请请求用户确认。

5. Sign and send

5. 签名并发送请求

bash

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

The wrapper signs

ts + METHOD + path?query + body

with HMAC-SHA256 and sends it to

https://api.sumsub.com

. Final line of output is

HTTP <code>

bash

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

6. 验证结果

For state-changing calls, fetch the entity back and verify the change actually landed. Sumsub occasionally accepts a field at the API edge and then silently drops it (tenant entitlement gates). Report any mismatch.

For reads, surface the relevant fields to the user — don't just dump the whole response. Most Sumsub responses are big.

对于会改变状态的调用，重新获取实体并验证变更是否已生效。Sumsub偶尔会在API边缘接受某个字段，但随后静默丢弃它（受租户权限限制）。如果发现任何不匹配，请报告。

对于读取操作，向用户展示相关字段——不要直接输出整个响应。大多数Sumsub响应内容都很大。

Common pitfalls

常见陷阱

Path-parameter expansion in the signature. You must sign the resolved path (
```
/resources/applicants/abc123/one
```
), not the template (
```
/resources/applicants/{applicantId}/one
```
). The helper script signs whatever string you pass — so resolve first.
Query-string encoding.
```
+
```
vs
```
%20
```
, ordering, repeated keys — the signing string must match the wire exactly. Build the URL once and reuse.
GET/DELETE with an accidental body. Some HTTP clients add
```
Content-Length: 0
```
or an empty body; the helper does not, but if you switch to another client, watch for it — empty body means append nothing to the signing string.
Pagination. Many list endpoints use cursor or offset paging — check the schema. Don't claim "no results" from a single page.

签名中的路径参数展开。你必须对解析后的路径（如
```
/resources/applicants/abc123/one
```
）进行签名，而不是模板路径（如
```
/resources/applicants/{applicantId}/one
```
）。辅助脚本会对传入的任何字符串进行签名——因此请先解析路径。
查询字符串编码。
```
+
```
与
```
%20
```
、参数顺序、重复键——签名字符串必须与实际传输的内容完全一致。请构建一次URL并重复使用。
GET/DELETE请求附带意外请求体。某些HTTP客户端会添加
```
Content-Length: 0
```
或空请求体；本辅助脚本不会这样做，但如果你切换到其他客户端，请留意——空请求体意味着签名字符串末尾不需要追加任何内容。
分页。许多列表端点使用游标或偏移量分页——请查看Schema。不要仅凭一页结果就断言“无结果”。

另请参阅

```
sumsub-api-auth
```
— full auth reference and
```
401 Invalid signature
```
triage.
Sumsub API reference — human-readable docs that often lag the schema; cross-check.

```
sumsub-api-auth
```
— 完整的认证参考和
```
401 Invalid signature
```
问题排查。
Sumsub API参考文档 — 人类可读的文档，但通常滞后于Schema；请交叉核对。

sumsub-api-generic

Original

Translation

Sumsub — generic API fallback

Sumsub — 通用API回退方案

When to invoke

何时调用

Auth

认证

Hard rule: no shotgun debugging

硬性规则：禁止盲目调试

Procedure

流程步骤

0. The schema is auto-fetched

0. Schema会自动获取

1. Search the schema — always

1. 始终先搜索Schema

2. Pick the right match

2. 选择正确的匹配项

3. Inspect the operation in full

3. 完整查看操作详情

4. Build the payload

4. 构建请求体

5. Sign and send

5. 签名并发送请求

6. Validate

6. 验证结果

Common pitfalls

常见陷阱

See also

另请参阅