sumsub-check-databases

检查数据库

列出 Sumsub 为某个国家提供的数据库核查来源、每个来源对当前租户的启用状态，以及它如何接入验证级别。调用方可用它在构建级别前，判断是否启用数据库／非证件验证。

范围：目前仅限 KYC（个人）。 此端点仅返回个人核查来源。目前尚未在此处提供公司（KYB）数据库验证；请勿使用此技能配置公司／企业来源。

端点

GET https://api.sumsub.com/resources/api/agent/settings/checkSources?country=<country>

country 是 ISO alpha-3 代码（例如 DEU）。如果用户提到了某个国家，请先将其转换为 alpha-3 代码再调用。省略 country 可返回完整目录。不认识或不支持的代码不会导致错误——它会返回 HTTP 200 和一个空的 checkSources 列表。

尽可能传入 country。 未筛选的响应是完整目录，包含所有国家的数百个条目，可能会使上下文过于臃肿或被截断。如果用户提到了某个国家，请按该国家筛选。如果用户没有提到国家，最好先询问他们需要哪个国家，再进行未筛选调用；只有在确实需要整个目录且能处理大型响应时，才省略 country。

身份验证 — 应用令牌 + 密钥（仅限沙盒）

此技能调用公开的 Sumsub API，并根据 身份验证参考为每个请求签名。 完整的工作原理说明请参阅 sumsub-api-auth 技能——如果遇到 401 Invalid signature，请阅读该技能。

⚠️ 仅限沙盒令牌。 请勿在此处接受或使用生产环境的应用令牌。 如果用户提供了此类令牌，请拒绝并要求他们前往 https://cockpit.sumsub.com/checkus/devSpace/appTokens 生成沙盒令牌对（先将工作区切换到 Sandbox，再点击 Create）。令牌和密钥只会显示一次——关闭对话框前请复制两者。辅助脚本会强制执行此要求——它会拒绝不以 sbx: 开头的令牌。

变量	示例
SUMSUB_APP_TOKEN	sbx:... — 从控制面板获取的沙盒应用令牌。
SUMSUB_SECRET_KEY	创建令牌时显示一次的配对密钥。
SUMSUB_BASE	可选。默认值为 https://api.sumsub.com。

用法

bash ${CLAUDE_SKILL_DIR}/scripts/check_databases.sh <country>

输出：原始 Sumsub 响应正文，后接 HTTP <code>。

成功（HTTP 200）：

{"checkSources": [
  {
    "sourceId": "arg_gov_dni",
    "name": "Argentina DNI Verification",
    "description": "Verifying user's personal, biometric, and residency data against official government sources.",
    "dataSources": [
      "National Registry of Persons (Registro Nacional de las Personas - RENAPER)",
      "Agency of Public Revenues and Control (Agencia de Recaudación y Control Aduanero – ARCA)"
    ],
    "country": "ARG",
    "checkType": "E_KYC_CHECK",
    "confirmationType": "otp",
    "status": "ENABLED",
    "validationReady": false,
    "stepsReady": ["E_KYC", "IDENTITY"],
    "supportedDocuments": ["ID_CARD"],
    "requiredInputFields": ["gender", "number"],
    "optionalInputFields": ["address.postCode"],
    "selfieRequirement": "ADDITIONAL",
    "outputFields": ["firstName", "lastName", "addresses", "gender", "nationality", "dob", "tin"],
    "violations": ["GENDER_MISMATCH", "DEAD", "PERSON_IS_MINOR", "SELFIE_MISMATCH"]
  }
]}
HTTP 200

输入字段值是背景调查输入数据中的机器字段名称——number、dob、address.postCode、bankAccount.bankName——而不是显示标签。带点号的名称表示嵌套对象（address.*、bankAccount.*）。向用户展示时，请将它们转换为易读的名称。

输入字段中绝不会列出自拍照——它有单独的 selfieRequirement 字段。请读取该字段，而不是 optionalInputFields，以判断流程是否需要自拍步骤。

字段参考

字段	含义
sourceId	检查来源的稳定 ID（{country}_{provider}_{subject}）。
name	便于阅读的来源名称（英文），例如 “Argentina DNI Verification”。
description	对该来源验证内容的一行英文描述。可能不存在。
dataSources	该来源所依托的登记库 / 提供方（英文名称）。可能不存在。
country	该来源覆盖的规范 ISO alpha-3 国家代码。
checkType	内部类别（E_KYC_CHECK、PERSON、TIN）——仅供参考，不是筛选条件。不会返回公司（KYB）类型。
confirmationType	申请人确认非证件检查的方式：otp、oAuth（登录银行 / 国家 eID 服务），或 eID（通过 NFC 扫描 eID 卡）。来源无需确认步骤时，该字段不存在。
status	每个租户的启用状态，即是否可用的判定条件：ENABLED（已获许可，可用于生产环境，也可用于沙盒）/ SANDBOX_ONLY（仅获准用于沙盒——可用于测试，不能在生产环境运行）/ DISABLED（未获任何许可）。详见下文。
validationReady	如果该来源可以交叉验证已采集的证件，则为 true（数据库验证）。
stepsReady	该来源可用作非证件检查的级别步骤类型（IdDocSetType，例如 E_KYC、IDENTITY）。如果没有，则为空。
supportedDocuments	该来源可以验证的 IdDocType。
requiredInputFields / optionalInputFields	申请人必须 / 可以提供的机器字段名称（例如 number、dob、address.postCode）——背景调查输入数据键，而非显示标签。不包括自拍照。
selfieRequirement	REQUIRED（来源必须使用自拍照才能运行）/ ADDITIONAL（可选，可提高匹配度）/ 不存在（不需要自拍照）。
outputFields	来源在匹配时返回的字段。
violations	来源可能报告的违规原因（例如 GENDER_MISMATCH、DEAD）。

完整类型、枚举值和含义：references/checksources-schema.md。

调用方应如何使用

1. 如果 HTTP 状态码不是 200，立即停止——向用户显示错误正文，不要继续。
2. checkSources 列表为空并不表示出错。 这意味着 Sumsub 没有提供适用于该国家/地区的 KYC 数据库来源，或者 country 值不是可识别的 ISO alpha-3 代码。告知用户该国家/地区没有可用的数据库核查来源；如果他们提供的是国家/地区名称，请确认它是否映射到了正确的 alpha-3 代码（例如，Germany → DEU），并询问是否重试。绝不要捏造来源。数据库层是可选的，因此请改用基于证件的验证（参见下方的分支处理方式）。
3. 检查 status——该值按租户区分，且与环境无关（无论从沙盒还是生产环境查询，返回的值都相同）。ENABLED：已获得生产环境许可，因此沙盒环境也可用——可以使用，继续操作。SANDBOX_ONLY：仅获得沙盒环境许可——可用于沙盒测试，但该级别在生产环境中不会运行此来源，因此请明确说明，并告知用户上线前需要启用。DISABLED：未获得任何环境的许可——不可用。对于任何非 ENABLED 状态，请参见下方的启用来源。
4. 如果用户需要的来源不可用，不要悄悄将其移除，也不要一概直接停止。 缺少核查来源（与缺少授权不同）仍可使用有效的基于证件的级别——因此应说明这一缺口，而不是阻止操作。然后根据该来源的用途选择处理方式：

用户的需求	来源不可用时 → 处理方式
数据库验证（证件 + 数据库交叉核查）	软性处理：证件验证仍然有效。确认后，继续操作，但不使用数据库层。
身份步骤中的非证件来源（来源嵌套在 IDENTITY 中）	提供备用方案：将该身份步骤切回证件上传。用户选择后继续。
独立的非证件来源（数据库专属步骤是全部目的）	最接近停止操作的情况：没有来源就无法执行此步骤。提供基于证件的替代方案；仅在用户明确确认后继续。

绝不要悄悄降级，也不要单方面直接停止——说明缺口及其影响，并让用户（通过调用方）决定。仍然适用的一项硬性限制：非证件身份验证还需要 E_KYC_TARGET 授权，该授权由 sumsub-check-permissions 独立控制。

启用来源

Agent 无法启用来源：没有用于启用核查来源的公共 API。这既适用于 DISABLED（完全无法使用），也适用于 SANDBOX_ONLY（沙盒环境可用，生产环境不可用）。告知用户缺少哪项数据库核查，以及它在哪个环境中不可用——指出该来源的具体 name，并注明其 sourceId——同时说明因此会缺少哪些验证。然后引导用户前往：

• Sumsub 控制面板中的 Databases → Available products——大多数来源可在此自行启用。
• 如果该来源无法在此自行启用，用户应联系其客户成功经理 / Sumsub 支持团队提出申请。

每个 source 在 level 中的放置位置

所选 source 会配置到 level 的 checkSourceSettings.countrySettings[] 中——每个 country 对应一个条目（放在 level 顶层时还需包含 checkType），并在 executionConfigurations 下列出 sourceId。validationReady 和 stepsReady 会告诉你适用哪些放置位置。sumsub-create-level 会构建完整的 payload——本技能负责决定放置位置。

一个 source 可以同时满足 validationReady，和／或在 stepsReady 中有条目——请同时检查两者，它们是相互独立的信号。如果 stepsReady 列出了多个步骤类型，这表示同一个 source 有多个有效的放置位置可选，并不要求同时使用所有位置——请选择与用户意图相符的一个位置。

放置位置（工单）	信号	在 level 中的含义
数据库验证	validationReady: true	保留 document docSet（例如 IDENTITY）——申请人仍需提交文档。将 source 添加到level 顶层的 checkSourceSettings 中（与 requiredIdDocs 同级，而不是嵌套在其中）。
非文档、独立步骤	stepsReady 单独包含该步骤类型（例如 E_KYC）	专用的非文档 docSet，无需上传——身份验证使用 E_KYC（需要 E_KYC_TARGET，请通过 sumsub-check-permissions 验证）。申请人提供 requiredInputFields，系统会与数据库进行比对。将 source 添加到该 docSet 自身的 checkSourceSettings 内部。
现有步骤中的非文档验证	stepsReady 包含该步骤类型（例如 IDENTITY），且同时存在一个已要求的文档步骤	保留文档 docSet 的 types（文档上传仍为可选项），并将 source 的 checkSourceSettings 嵌套在同一个 docSet 中——申请人可在一个步骤中选择上传或进行数据库验证。还需要 E_KYC_TARGET。

在所有情况下，都会通过 country、checkType（仅限顶层放置）和 executionConfigurations[].sourceId 引用 source。如果验证无法确认，可选的 fallbackReasons（NO_DATA、NAME_MISMATCH、DOB_MISMATCH、INVALID_DOC_NUMBER、FAILED、DEAD）可让流程回退到另一个 source 或文档。请参阅 sumsub-create-level/examples/ 中的示例：identity-selfie-with-database-validation.json（顶层，validationReady）、identity-with-non-doc-selfie.json（嵌套在 IDENTITY 中）、non-doc.json（独立的 E_KYC）。

概念参考：无文档验证、数据库验证。

另请参阅

• sumsub-create-level — 构建这些 sources 所接入的 level。
• sumsub-check-permissions — 检查非文档身份验证所需的 E_KYC_TARGET 权限。
• sumsub-api-auth — 请求签名详情。
• references/checksources-schema.md — 完整的响应架构、字段类型和枚举值。