sumsub-supported-id-documents

Sumsub — 支持的证件参考

回答有关 Sumsub 内置支持证件目录（ documentsByCountries）的问题：针对每个国家和证件类型，该类型是否受支持、是否为双面证件，以及默认提取和可选提供的 OCR 字段。

目录规模庞大（约 250 个国家、约 1350 个国家／证件类型组合）。此技能不会将整个目录倾倒到对话中——本地 Python 脚本会在进程内保留完整目录，仅返回相关部分；如果平铺列表过大、不便使用，则会汇总为概览。

端点

方法	路径	使用时机
GET	/resources/api/agent/supportedDocs/documentsByCountries	读取内置支持证件目录（每个国家的默认值）。
GET	/resources/api/agent/globalSettings	读取客户端当前设置，包括其 idDocSettings.countryMappings 覆盖项。
GET	/resources/api/agent/globalSettings/extensionRules	读取 Sumsub 内置的有效期延长规则（只读参考；用于“官方延长证件”的有效期模式）。
PUT	/resources/api/agent/globalSettings/idDocSettings/countryMappings	全量替换——唯一的写入路径。 始终发送由脚本构建的完整映射（编辑时先读取再修改再写入；删除时构建少一项的映射）。

所有端点均使用带有 manageClientSettings 权限的 App Token 进行身份验证。

目录 GET 返回 { "countryMappings": { "<ISO3>": { "<DOC_TYPE>": { supported, doubleSided, doubleSidedCanBeChanged, shouldBeSigned, acceptDigitalDoc, acceptScreenshots, expirationCheckMode, sidesSelectionMode, defaultFields[], availableFields[] } } }。

⚠️ 两种不同的结构——注意路径。 目录 GET 会将 countryMappings 放在顶层。GET globalSettings 则会将它嵌套一层， 位于 idDocSettings.countryMappings 下（根对象还包含 minAge、 poaCheckSettings、poiCheckSettings——适用于所有证件类型的有效期模式——等）。在内联 python3 -c 中读取 /tmp/current.json（globalSettings）时，请使用 ['idDocSettings']['countryMappings']——使用顶层路径会触发 KeyError: 'countryMappings'。

字段以 NON_NULL 序列化：JSON 中缺失的标志表示它处于默认值（未设置）。对于接受类标志，缺失 ⇒ false（例如，没有 acceptScreenshots 键 ⇒ 不接受截图）。绝不要因为某个标志缺失就报告它已启用；应说明默认值，并指出这是默认设置。

PUT 会全量替换： 后端会将整个 countryMappings 映射替换为你发送的内容——任何省略的项都会被清除（恢复为目录默认值）。 因此，每次写入都必须通过脚本完成：build_country_mappings.py 会将你的更改合并到一份最新获取的当前映射副本中，而 remove_country_mapping.py 会构建少一项的映射。绝不要手动编写部分载荷，也绝不要重用过时的 /tmp/current.json——构建前应立即重新获取，否则并发发生的仪表板编辑会被悄无声息地撤销。

GET globalSettings 中的键级根块（请读取，不要遗漏）

除了 idDocSettings.countryMappings，globalSettings 根级还包含一些会改变证件相关答案的键级块。这些块是此技能的只读上下文（此处的编辑仅通过 PUT countryMappings 进行），但跳过它们会导致答案错误——某个国家/地区的条目看起来“未配置”，实际上可能受根级块控制：

根路径	包含内容	何时会改变答案
poiCheckSettings.expirationCheckMode	键级有效期模式	有效期级联中的回退项（C）
poiCheckSettings.minimumResidualValidityInMonths	证件必须至少再有效 N 个月；0 = 无要求（见 C）	任何有效性相关答案（C）
ongoingMonitoringSettings（enabled、idDocExpireInDays）	审批后进行的有效期监控（受许可证限制）	“证件过期后会发生什么”
minAge / maxAge	键级年龄限制（根据出生日期检查）；仪表板会在保存时自动填入（最小值 16；RUS 许可密钥为 18；最大值 110），因此通常会存在	“为什么证件/申请人因年龄被拒绝”
idDocSettings.ekycSourceMappings	各国家/地区的 eKYC 来源——与 countryMappings 同级，在同一个仪表板“支持的身份证件”页面编辑，但作为单独的负载保存；PUT countryMappings 会在服务器端保留它（此端点只替换 countryMappings）	eKYC 问题；不要与 countryMappings 混淆
enableAutoCompleteShortDates	OCR 会自动补全日期中的两位年份（仪表板：“出生日期”复选框）	识别出的日期值
imageConstraints（minFileSize、maxFileSize）	上传大小限制（仪表板：常规 → 申请人设置）	“为什么文件未被接受”
poaCheckSettings（已弃用）	POA 验收设置（validMonths、acceptIdAsPoa、acceptSameDocAsPoa）	POA 问题——作为只读上下文报告
crossValidatorSettings	证件与个人资料比较（nameComparisonMode、fuzzyThreshold，……）；仅限 API，无仪表板界面	不匹配/交叉检查导致的拒绝

根级的其他所有内容（watchListCheckSettings、cryptoCheckSettings、 bankCardCheckSettings、kybIntegrationSettings、uiSettings、 duplicateSettings、sourceKeysSettings、applicantTags、supportEmail、 disableSumsubId、idDocServiceSettings）均不属于此技能的范围——不要根据这些块回答证件问题，也不要在此处提出编辑它们。

Auth——App Token + secret（仅限沙盒）

与其他写入技能采用相同的模型。请参阅 sumsub-api-auth。

Var	Example
SUMSUB_APP_TOKEN	sbx:...——从控制面板获取的沙盒 App Token。
SUMSUB_SECRET_KEY	创建 Token 时仅显示一次的配套密钥。
SUMSUB_BASE	可选。默认值为 https://api.sumsub.com。

默认使用有效识别状态（A）。 任何关于某个国家 / 文档类型目前识别、收集或提供哪些内容的问题——包括“目前有哪些字段可用 / 可识别 / 可收集”“BRA 有哪些可用字段”“护照会收集哪些内容”等表述——都与客户端的有效状态有关，因此应使用识别状态（A）。单纯的目录仅包含默认值，会给出误导性答案（目录中“可用”≠此客户端已启用）。

只有当用户明确询问抽象层面或跨国家/地区可能支持哪些内容时，才使用目录查询（B），例如“哪些国家支持字段 X”“护照是否可能提取性别”“BRA 有哪些文档类型”。

关于到期 / 有效性检查的问题（“适用哪些有效性检查”“过期文档是否接受”）→ 使用下文的 （C）：报告 expirationCheckMode 以及适用的具体延期规则（60+ / 延期文本），而不只是模式。

关于如何处理文档的宽泛问题（“接受规则”“适用哪些设置”“为 X 配置了什么”）→ 使用下文的 （D）：从 GET globalSettings 中读取整个有效的 (country, docType) 条目，并报告其中的每一项设置，无论开启还是关闭——不要自行筛选、猜测子集，也不要遗漏保持默认值的标志。

如果不确定用户指的是哪种情况，请选择 A（有效状态）——这是诚实的答案，也会告诉你目录允许哪些内容。

⚠️ 务必通过这些脚本获取数据——切勿读取 Paler 源码。 如果你恰好打开了 paler 仓库，切勿根据其中的文件作答（documents-by-countries.json、Java 源文件等）。这些文件只包含内置目录默认值——客户端的有效状态（countryMappings 覆盖项 + ADVANCED_OCR）根本不在代码中，只能通过 API 获取。阅读源码只能得到默认值，会在不知不觉中答错问题。数据必须来自 get_global_settings.sh / get_supported_docs.sh / get_entitlements.sh。

A. 有效识别状态（实际识别内容）

S=${CLAUDE_SKILL_DIR}/scripts
$S/get_supported_docs.sh  > /tmp/catalogue.json
$S/get_global_settings.sh > /tmp/current.json
ADV=$($S/get_entitlements.sh ADVANCED_OCR >/dev/null 2>&1 && echo true || echo false)

$S/recognition_status.py BRA PASSPORT \
    --current-file /tmp/current.json \
    --catalog-file /tmp/catalogue.json \
    --advanced-ocr "$ADV"
# Omit the doc type to report ALL doc types for the country in one go
# (e.g. "fields for documents from Brazil"):
$S/recognition_status.py BRA \
    --current-file /tmp/current.json --catalog-file /tmp/catalogue.json --advanced-ocr "$ADV"

将每个字段报告为 ✅ 已识别（免费 / PAID）或 ⬜ 未识别（并说明原因：默认关闭 / 未启用额外功能 / ADVANCED_OCR 关闭）。请将这些内容呈现给用户——这是诚实回答“实际识别哪些内容”的方式。

B. 目录查询（可能支持的内容）

1. 获取一次目录：get_supported_docs.sh > /tmp/catalogue.json （后续查询时重复使用——目录很大，且在一次会话中保持不变）。
2. 将问题转换为精简的筛选规范（见下文）。
3. 运行查询——规范通过 stdin 输入，目录通过 --data-file 传入：

   echo '{"countries": ["DEU"]}' \
     | ${CLAUDE_SKILL_DIR}/scripts/query_supported_docs.py --data-file /tmp/catalogue.json
   

4. 报告查询结果。如果结果是 summary（见判定规则），请说明覆盖范围 / 分布情况，而不要编造列表。

C. 到期／有效期检查（模式 + 实际延长规则）

对于任何有关文档到期／有效期检查的问题（例如“适用哪些有效期检查”“已过期的 X 是否可接受”“BRA ID 的有效期规则”），都要给出两部分——不要只说明模式：

1. 模式——按完整的优先级链解析，不能只看各国家的条目（参见 references/fields-glossary.md 中的四种模式）： idDocSettings.countryMappings.<country>.<docType>.expirationCheckMode → 如果缺失，则查看 globalSettings 根级别的全局设置键级别配置 poiCheckSettings.expirationCheckMode → 如果仍缺失，则采用该组合的目录默认值。 两个客户端值都来自同一份 get_global_settings.sh 响应——不能只看 (country, docType) 条目：如果各国家的模式缺失，但设置了 poiCheckSettings.expirationCheckMode，那么该键级别模式确实适用于该组合。

2. 实际延长规则——如果该模式接受延长有效期的文档（generallyAcceptedRegulations / localRegulations），请提取并展示适用的具体规则。不要只提出可以提供规则——要直接写出：

   $S/get_extension_rules.sh > /tmp/ext.json
   # then filter to the country/doc type, e.g.:
   python3 -c "import json;[print(r['docType']['idDocType'],'—',r.get('defaultDescription'))
     for r in json.load(open('/tmp/ext.json'))['rules']
     if r['docType']['country']=='BRA' and r['docType']['idDocType']=='ID_CARD']"
   

   例如，对于 BRA/ID_CARD，适用规则为“持有人年满 60 岁 ⇒ 永久有效”。这条规则才是“适用哪些到期检查”问题的真正答案——仅说明模式并不完整。

3. 其他有效期配置项——完整回答有效期问题时，还要报告 globalSettings 根级别已设置的以下配置：

   • poiCheckSettings.minimumResidualValidityInMonths — ⚠️ 0 表示“接受任何有效期”（无要求），这是仪表板默认单选项写入的值——绝不能将其表述为“必须至少有效 ≥ 0 个月”。非零值 N 表示在检查时，文档必须至少在 N 个月后才到期（比“尚未过期”更严格；仪表板自定义选项的默认值为 3）。
   • ongoingMonitoringSettings.idDocExpireInDays（以及 enabled）— 审批后进行到期监控：文档会在到期前 N 天被标记（仪表板默认值为 7）。缺失／为 0 = 不发送到期提醒。整个部分受许可证限制（ONGOING_MONITORING_EXPIRED_DOCS 背景调查目标）。 两者都是键级别配置（没有各国家的变体）——请从同一份 get_global_settings.sh 响应中读取。

   **键级别模式的编辑位置：**仪表板 → 全局设置 → 用户验证 → ID 验证 → “ID 文档到期设置”。此页面仅提供 strict（“遵循有效期”）、generallyAcceptedRegulations，以及通过额外复选框启用的 localRegulations——无法在仪表板中设置键级别的 allowExpired（但仍可通过“支持的文档”抽屉或 API，为各国家的条目设置该值）。

D. 完整设置转储（所有开启／关闭的设置）

对于“如何处理此文档／配置了什么”这类宽泛问题，不要只挑选部分设置——读取整个生效的 (country, docType) 条目，并报告其中的每一项设置。

$S/get_global_settings.sh > /tmp/current.json   # client's effective settings
$S/get_supported_docs.sh  > /tmp/catalogue.json  # catalogue, for the default baseline
# Pull the entry the client actually has (override), e.g. BRA/ID_CARD:
# NOTE: in GET globalSettings the map is nested under idDocSettings.countryMappings
# (NOT top-level — that's only the catalogue GET). Using the wrong path → KeyError.
python3 -c "import json;print(json.dumps(
  json.load(open('/tmp/current.json'))['idDocSettings']['countryMappings'].get('BRA',{}).get('ID_CARD',{}),
  indent=2, ensure_ascii=False))"

然后将该条目中的每个键都作为一项设置呈现——supported、 sidesSelectionMode / doubleSided、shouldBeSigned、acceptDigitalDoc、 acceptScreenshots、expirationCheckMode、ocrSettings、子类型标志、 defaultFields / availableFields，以及其他任何存在的键——并根据 references/fields-glossary.md 将每项转换为对应的 UI 含义。

如实转储的规则：

• 不要筛选。 遍历条目中实际存在的键；不要自行判断某些键“无关”。跳过某项设置会让人以为“未配置”。
• 默认值不会出现（NON_NULL）。 缺失的键表示其使用默认值，而不是未开启。如果客户端完全没有覆盖该组合，则整个条目都不存在——回退到目录条目（/tmp/catalogue.json），作为基准，并说明这些是 Sumsub 默认值，而非客户端设置。
• 独立标志要分别报告。 特别是 acceptDigitalDoc（上传的文件／扫描件／PDF）和 acceptScreenshots（截图）是独立的检查——分别说明各自的状态；绝不能将二者合并，也不要说“只接受实时摄像头照片”。
• 有效期： 条目中缺少 expirationCheckMode 并不意味着使用目录默认值——应先检查根级别 globalSettings 中按键作用域的 poiCheckSettings.expirationCheckMode（按 C 中的级联规则）。当生效模式接受延期证件时，还要说明具体的延期规则（参见 C）——仅说明模式并不完整。

流程（编辑客户端支持的文档）——读取-修改-写入 + PUT

该端点会替换全部内容，因此编辑采用读取-修改-写入：获取当前映射，让构建脚本在本地合并你的更改，然后 PUT 完整结果。构建脚本需要两个输入文件。

1. 读取目录和当前设置（重新获取 current.json——过时的快照会还原期间所做的编辑）：

   ${CLAUDE_SKILL_DIR}/scripts/get_supported_docs.sh  > /tmp/catalogue.json
   ${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json
   

2. 将请求转换为精简的更改规范（见下文）——仅列出你要更改的字段，按 (country, docType) 区分。

3. 构建完整负载（当前映射 + 合并后的更改）：

   echo '<change spec>' | ${CLAUDE_SKILL_DIR}/scripts/build_country_mappings.py \
       --current-file /tmp/current.json --catalog-file /tmp/catalogue.json > /tmp/payload.json
   

   脚本会验证枚举值以及每个字段是否位于正确的列中，并打印 Field changes: 摘要。脚本不会自动将字段移到另一列（那会悄无声息地替换另一列的列表）——如果报错，请修正规范。对于全新的 (country, docType) 覆盖项，会使用目录中的默认值填充 supported、doubleSided、doubleSidedCanBeChanged 和 shouldBeSigned（规范中的值优先；目录值为 null 时则保持缺省），因此新条目会保留其所覆盖默认值的行为——例如，doubleSided 为 null 时原本会被理解为“任意一面”，从而丢失目录要求的双面证件规则。此外，每当规范设置 sidesSelectionMode 时，都会将已弃用的 supported/doubleSided 组合同步为对应的旧版值（与控制面板执行相同的双写），这样不支持 sidesSelectionMode 的读取方也能看到相同的行为。这两项都会在摘要中报告。

4. 如果更改设置了任何 extraFields，请验证是否具有 ADVANCED_OCR 权益（付费附加项；没有该权益时，后端会悄无声息地丢弃这些字段）：

   ${CLAUDE_SKILL_DIR}/scripts/get_entitlements.sh ADVANCED_OCR
   

   如果未启用，请告知用户并且不要继续添加额外字段。Default Fields 不受此限制。

4b. 关键防欺诈设置需要明确警告。 如果更改设置了 acceptScreenshots: true（禁用截图保护）或 acceptDigitalDoc: true（接受易于修改的上传文件），构建脚本会打印 warning:——请原样转告用户，并在应用更改前取得明确的“是”。尤其是启用截图功能，可能会批准虚假申请，并使客户端面临罚款/拒付。（关闭这些选项是安全的，无需特别警告。）

5. 展示差异并等待明确确认。 将负载与构建时使用的同一份 current.json 进行比较（不要手写内联的 python3 -c 差异命令）：

   ${CLAUDE_SKILL_DIR}/scripts/diff_country_mappings.py \
       --current-file /tmp/current.json --payload-file /tmp/payload.json
   

   构建脚本原样保留的条目不会显示，因此差异只会展示你的更改。任何非预期显示为 REMOVED 的内容都意味着负载基于错误或过时的快照构建——请重新构建，不要 PUT。这是影响整个工作区的更改——未经明确的“是”绝不应用。

6. PUT 已确认的负载：

   ${CLAUDE_SKILL_DIR}/scripts/put_country_mappings.sh /tmp/payload.json
   

7. 报告 HTTP 状态和更改内容。如果状态为 4xx，请原样提供响应正文。如果设置了 extraFields 但没有 ADVANCED_OCR，请重新读取设置，并说明额外字段已在服务端被丢弃。

**更改列中的一个字段，同时保留其他字段：**规范中的列列表会整体替换该列。若要在保留现有额外字段的同时再启用一个字段，请先读取当前启用的集合（recognition_status.py），并传入完整的目标 extraFields 列表。

流程（移除 / 恢复默认值）——PUT

若要将 (country, docType) 恢复为目录默认值，请从完整映射中移除其覆盖项，然后 PUT 结果：

${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json
${CLAUDE_SKILL_DIR}/scripts/remove_country_mapping.py \
    --current-file /tmp/current.json BRA:ID_CARD > /tmp/payload.json   # full map MINUS the entry
# show the diff (the removal shows as REMOVED), confirm, then PUT:
${CLAUDE_SKILL_DIR}/scripts/diff_country_mappings.py \
    --current-file /tmp/current.json --payload-file /tmp/payload.json
${CLAUDE_SKILL_DIR}/scripts/put_country_mappings.sh /tmp/payload.json   # PUT (replace-all)

更改规范

稀疏规范——按 (country, docType) 仅列出你要更改的字段。字段键与控制面板“Fields management”界面中的键一致（包含两个复选框列：Default Fields / Extra Fields）。

changes:
  - country: DEU                   # ISO-3
    docType: ID_CARD               # IdDocType
    expirationCheckMode: strict    # scalar settings — merged locally, others preserved
    ocrSettings: {ocrRuleMode: MRZ_DOC}
  - country: BRA
    docType: PASSPORT
    extraFields: [placeOfBirth, gender]   # REPLACES the Extra Fields column (PAID)

这涵盖了主“Supported ID Documents”屏幕上的按钮：

• 管理证件 — 设置字段／模式／子类型（键见下文）
• 更改证件面数 — 设置 sidesSelectionMode （oneSide/twoSides/smartMode；disabled =“不接受”选项）
• 恢复默认设置 — 不在此处执行；这是移除操作 → 使用上文单独的移除流程（remove_country_mapping.py）；构建器会拒绝 remove。

它与识别和费用的对应关系如下（脚本会报告这些信息）：

• 默认字段 — 免费；勾选的字段会被识别。省略某个字段即可取消勾选（停止识别）。默认字段默认处于勾选状态。
• 额外字段 — 仅在勾选时才会识别，而且需要 ADVANCED_OCR 权益（步骤 4）。这些是付费字段。
• 字段所属的列由目录固定 — 不能把字段列在错误的列下。如果这样做，脚本会报错（不会自动移动字段，因为这会悄无声息地替换另一列的列表），并告知正确的列 — 修正规格。查看目录（{country, docType} 查询），了解哪些字段属于哪一列。
• 脚本会为每种证件打印一份 Field recognition result: 摘要，列出免费识别和付费识别的内容。在确认步骤中向用户展示此摘要 — 它使用了与 UI 相同的表述（“Default Fields”／“Extra Fields”）。

在传输过程中，extraFields 会变成 API 的 availableFields — 脚本会为你完成映射；你只需使用 UI 中的术语。

“Fields management”屏幕上的所有其他控件也都可以设置 — 在变更规格中设置对应的键。完整的 UI 控件 → 规格键对照表（含枚举值和映射）见 references/fields-glossary.md。重点如下：

用户请求	规格键	值
接受以图像／文件形式提交的证件（扫描件、PDF）— 不仅限于实时相机拍摄的照片	acceptDigitalDoc	true
接受屏幕截图	acceptScreenshots	true
MRZ 模式	ocrSettings: {ocrRuleMode: MRZ_DOC}
优先进行非拉丁文字识别	ocrSettings: {preferNonLatinFromOcr: true}
有效期策略	expirationCheckMode	allowExpired/strict/generallyAcceptedRegulations/localRegulations
仅接受／拒绝某些子类型	allowedOcrDocumentTypes / forbiddenOcrDocumentTypes	子类型 ID 列表
在 WebSDK 中隐藏子类型	disableDocumentReferences	true
是否接受此证件类型	sidesSelectionMode	使用正向模式表示接受；使用 disabled 表示停止接受
需要几面	sidesSelectionMode	smartMode/oneSide/twoSides/disabled

脚本会验证枚举值（expirationCheckMode、ocrRuleMode），拼写错误时会失败。词汇表中未列出的真正内部键（shouldBeMaskedSettings、documentReferences 等）会原样沿用基线值 — 不要为它们编造值。

已弃用的键不可设置 — supported、doubleSided、doubleSidedCanBeChanged、acceptedAsPoa、acceptSameDocAsPoa 在后端已弃用；build_country_mappings.py 会拒绝这些键，并告知应使用的替代项（面数／接受设置 → sidesSelectionMode；POA 标志没有替代项 — 应拒绝此编辑）。你仍会在 GET 响应中看到这些键 — 可以读取以了解上下文，但绝不要将它们放入变更规格。唯一仍会写入这些键的地方，是构建器在为全新覆盖项初始化数据时：它会从 GET /supportedDocs/documentsByCountries 复制这些键的默认值，确保新条目对旧版读取方仍保持与目录默认值一致的行为 — 这是自动完成的，不通过规格设置。 门控键也不可设置——shouldBeSigned（仅在启用 showRejectByMissingSignatureSetting 功能标志后，才能在仪表板中编辑；开启后会自动拒绝未签名的文档）和 shouldBeMasked（遮蔽受法律保护的国家身份证件号码——JPN/KOR/NLD/NGA/SGP；对于 NGA ID_CARD，甚至只有 Sumsub 员工才能在仪表板中操作）。build_country_mappings.py 会拒绝这两个键。如果用户要求更改，请说明门控限制，并引导用户前往仪表板（启用该标志后）或联系 Sumsub 支持。读取或报告这些键没有问题。

defaultFields / availableFields 的有效条目因国家和文档类型而异——并非固定的全局列表。构建更改规格前，请先读取目录（查询 field 级别或 {country, docType}），了解有效字段名称。

筛选规格

所有键都是可选的。不同的键之间采用 AND 组合；同一键中的列表采用 OR 组合。

countries: [DEU, FRA]            # ISO-3 codes
docTypes:  [ID_CARD, DRIVERS]    # document types
field:     placeOfBirth          # find where this OCR field exists (inverse query)
fieldKind: available | default | any   # which list to search field in (default: any)
flags:                           # match per-doc boolean flags
  supported: true                # IMPLICIT DEFAULT — unsupported docs are excluded
  doubleSided: false             #   unless you set supported:false explicitly
output:    auto | list | summary # default: auto
limit:     100                   # max items in a list before truncation

示例

问题	规格
德国身份证可以收集哪些信息？	{"countries":["DEU"],"docTypes":["ID_CARD"]}
哪些国家/类型提供 category 字段？	{"field":"category","fieldKind":"available"}
哪些证件可以收集 parentName1？	{"field":"parentName1"}
法国有哪些证件是双面的？	{"countries":["FRA"],"flags":{"doubleSided":true}}
也包括不受支持的证件	{"countries":["DEU"],"flags":{"supported":false}}

列表与摘要（自动模式）

对于精简结果，脚本会返回 mode: "list"；如果扁平列表没有实用价值，则返回 mode: "summary"：

• 近乎通用的字段（在 ≥ 80% 的匹配项中存在，例如 dob、 firstName）：返回覆盖率和 byDocType；如果只有少数项目缺少该字段，则将这些项目作为 absentIn 返回。
• 匹配项过多（字段存在性结果超过 200 项）：返回覆盖率、byDocType 和 topCountries 分布，而不是截断后的列表。

如需强制返回扁平列表，请设置 output: list 并提高 limit。

注意事项

• 默认隐藏不受支持的证件。 supported: false 的证件无法配置，因此除非传入 flags.supported: false，否则会将其排除。 这样可以确保覆盖率计算准确（否则，不受支持且字段为空的项目会拉低所有百分比）。
• 这是内置目录，不是客户端的覆盖设置。 特定 客户端实际启用的内容位于其全局设置 (idDocSettings.countryMappings) 中——这是另一个端点。使用此技能了解哪些内容可配置， 而不是某个账户已配置的内容。
• PROFILE_SCREENSHOT 和大量非 POI 类型（OTHER、VISA、 UTILITY_BILL 等）也在此目录中。如果用户只关心护照 / 身份证 / 驾照，请使用 docTypes 筛选。
• Verification Level 设置优先于 Global Settings。 此技能会编辑客户端的全局受支持证件配置。特定 Verification Level 可以 有自己的受支持证件覆盖设置，这些设置对该级别的申请人具有更高优先级。该级别通过 useCustomIdDocSettings: true 启用此功能——启用后，该级别自己的 idDocSettings.countryMappings 会完全替代该级别的 全局设置（该级别中未指定的标志会使用默认值，而非全局设置）。因此，全局更改可能不会对启用了覆盖设置的级别生效——如果用户 报告“我的更改没有生效”，请读取该级别并检查 useCustomIdDocSettings 和其 idDocSettings。如需实际编辑某个级别的证件设置，请使用 sumsub-create-level 技能（GET 该级别， 更改其 idDocSettings 中的标志，然后将完整级别 PATCH 回去）。