> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份证件验证警告与错误代码

> Didit 身份证件验证模块输出的全部警告详解，包含自动拒绝触发器、可配置风险组、不匹配与篡改代码及其产生原因与补救措施。

## 概述

身份证件验证报告上的警告会标记 Didit 在读取和验证证件时观察到的每种情况。它们会出现在 `id_verifications[]` 中各项的 `warnings[]` 数组中（参见[身份证件验证报告](https://docs.didit.me/zh/core-technology/id-verification/report-id-verification.md)），其结构如[数据模型 — 警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)中所述：`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`。

每个警告都包含三个层面：

1. **`risk` 代码** — 可以在您的代码中进行匹配的稳定标识符。
2. **`log_type`** — 由您的配置在评估时分配给该风险的操作衍生而来：**拒绝 → `error`**，**审核 → `warning`**，其他任何操作 → `information`。
3. **决策影响** — 由工作流的可配置风险组决定。根据您应用的配置方式，相同的 `risk` 代码可以被路由至**已通过**、**审核**或**已拒绝**。

## 自动拒绝条件

在工作流中，以下风险始终会强制将身份证件报告（以及会话）置为 `Declined`。它们不可配置：

| 风险 | 触发条件 |
| - | - |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 提交的证件类型不在您应用的允许证件列表中。`additional_data` 包含 `issuing_state`、`document_type`、`document_subtype`、`document_region` 和 `document_region_with_subtype`，以便您在工作流中启用该具体证件。 |
| `DOCUMENT_EXPIRED` | 采集时证件的到期日期已过。 |
| `PORTRAIT_IMAGE_NOT_DETECTED` | 无法在证件上定位到肖像照片。 |
| `ID_DOCUMENT_IN_BLOCKLIST` | 该证件与您应用的黑名单中的某项相匹配。 |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | 前置摄像头在证件采集期间拍摄的自拍照与人脸黑名单中的人脸匹配。 |
| `AGE_BELOW_MINIMUM` | 仅限自适应年龄验证工作流：提取出的年龄低于最低要求。 |
| `AGE_NOT_DETECTED` | 仅限自适应年龄验证工作流：无法从证件中提取年龄。 |

对于**独立 OCR API**，无条件拒绝的风险集合包括 `DOCUMENT_EXPIRED`、`MINIMUM_AGE_NOT_MET`、`PORTRAIT_IMAGE_NOT_DETECTED`、`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED` 和 `PUBLIC_DOCUMENT_IMAGE_DETECTED`。在工作流中，最低年龄是可配置的（默认为拒绝），而三个证件活体检测风险由阈值驱动（见下文）。

该 API 的可配置风险通过请求参数接受 `DECLINE` 或 `NO_ACTION`，而不是审核结论。它唯一可能返回的审核结果是不可配置的：当请求的证件活体检测未能生成可用评分时，响应为 `In Review` 并带有 `DOCUMENT_LIVENESS_NOT_COMPUTED` 警告（参见[证件活体检测](#证件真实性-防篡改)）。

| 请求参数 | 风险 | 默认值 |
| - | - | - |
| `invalid_mrz_action` | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | `DECLINE` |
| `inconsistent_data_action` | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | `DECLINE` |
| `expiration_date_not_detected_action` | `EXPIRATION_DATE_NOT_DETECTED` | `NO_ACTION` |
| `critical_field_occlusion_action` | `CRITICAL_FIELD_OCCLUSION_DETECTED` | `DECLINE` |
| `document_or_personal_number_format_mismatch_action` | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` | `NO_ACTION` |

## 可配置的验证设置

在 Didit 控制台中，其余证件风险被归类到各项设置中，您可以将其路由为**批准**、**审核**或**拒绝**（按工作流以及图谱工作流中的每个节点）：

| 分组 | 风险 | 默认操作 |
| - | - | - |
| **最小年龄** | `MINIMUM_AGE_NOT_MET` | 拒绝 |
| **最大年龄** | `MAXIMUM_AGE_EXCEEDED` | 拒绝 |
| **重复用户** | `POSSIBLE_DUPLICATED_USER`（当证件号码位于您的证件白名单中时跳过） | 批准（信息） |
| **代码无效** | `QR_NOT_DETECTED`, `BARCODE_NOT_DETECTED`, `QR_VALIDATION_FAILED`, `BARCODE_VALIDATION_FAILED` | 批准（信息） |
| **MRZ 无效** | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | 批准（信息） |
| **数据不一致** | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`, `DOCUMENT_SIDES_MISMATCH`, `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | 批准（信息） |
| **验证无效** | `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT`, `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED` | 审核 |
| **预期详细信息不匹配** | `FULL_NAME_MISMATCH_WITH_PROVIDED`, `GENDER_MISMATCH_WITH_PROVIDED`, `DOB_MISMATCH_WITH_PROVIDED`, `COUNTRY_MISMATCH_WITH_PROVIDED`, `NATIONALITY_MISMATCH_WITH_PROVIDED`, `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | 审核 |
| **未检测到到期日期** | `EXPIRATION_DATE_NOT_DETECTED` | 批准（信息） |
| **证件号码或个人号码格式不匹配** | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`（共享同一操作） | 审核 |
| **关键字段被遮挡** | `CRITICAL_FIELD_OCCLUSION_DETECTED` | 审核 |
| **未解析的地址** | `UNPARSED_ADDRESS` | 批准（信息） |
| **图像质量** | `IMAGE_TOO_BLURRY`, `IMAGE_TOO_DARK`, `IMAGE_TOO_BRIGHT`（每个风险一项操作） | 批准（信息） |
| **无肖像的证件** | `DOCUMENT_HAS_NO_PORTRAIT` | 审核 |
| **静默采集中的重复人脸** | `FRONT_CAMERA_DUPLICATED_FACE`, `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`（共享同一操作） | 批准（信息） |
| **静默采集中的重复人脸（姓名不同）** | `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`（仅能使重复人脸的处理结果更加严格） | 审核 |
| **静默采集中的重复人脸（出生日期不同）** | `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`（仅能使重复人脸的处理结果更加严格） | 审核 |

静默采集重复项及黑名单风险来源于[在证件采集期间拍摄的自拍照上进行的人脸搜索](https://docs.didit.me/zh/core-technology/face-search/overview.md#证件采集期间拍摄的自拍照)。该搜索在**静默采集人脸搜索**（`document_selfie_face_search_enabled`）处于开启状态（默认开启）且活体检测步骤未关闭人脸搜索时运行；否则这六项风险均不会触发。

有两类证件风险属于**阈值驱动**，而非批准/审核/拒绝切换开关：

* **证件活体检测**：`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED`。每种欺诈类型都有独立的拒绝和审核阈值：分数低于拒绝阈值 → `error` + 已拒绝；低于审核阈值 → `warning` + 审核中；否则为 `information`。
* **跨摄像头人脸比对**：`LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`，由 `document_selfie_portrait_match_decline_threshold` / `document_selfie_portrait_match_review_threshold` 控制。

### 配置证件活体检测阈值

在工作流编辑器中，这些阈值位于身份证件验证步骤的**伪造**选项卡上，每种欺诈类型对应一张卡片：**肖像替换**、**打印件**和**屏幕截图**。

每项检查都会根据证件的真实程度给出一个从 `0` 到 `100` 的分数。**分数越高，表示证件越可能是真实的。**卡片上的两个数值将该评分范围划分为三个区间：

| 分数 | 结果 |
| - | - |
| 低于**拒绝**值 | `error`，会话状态为已拒绝 |
| 等于或高于**拒绝**值且低于**审核**值 | `warning`，会话进入审核中 |
| 等于或高于**审核**值 | `information`，检查通过 |

调高任一数值都会使检查更加严格：更多会话会落入其上方的区间。调低数值则会让更多会话通过。在编辑器中，拒绝数值不能超过审核数值。通过 API 设置时，若拒绝数值高于审核数值，则会移除审核中区间。

平台默认值（当工作流未设置值时使用）：

| 欺诈类型 | 低于此值拒绝 | 低于此值进入审核 | 工作流配置键 |
| - | - | - | - |
| 肖像替换 | `35` | `70` | `document_liveness_portrait_replace_decline_threshold`, `document_liveness_portrait_replace_review_threshold` |
| 打印件 | `35` | `77` | `document_liveness_printed_copy_decline_threshold`, `document_liveness_printed_copy_review_threshold` |
| 屏幕截图 | `30` | `70` | `document_liveness_screen_replay_decline_threshold`, `document_liveness_screen_replay_review_threshold` |

建议从默认值开始调整，每次只修改一个数值。每张卡片都会显示其默认值以及**恢复默认值**按钮，以便您随时恢复。编辑器还会针对以下配置发出警告：

* **审核设为 `100`。** 只有满分才能通过，因此几乎所有会话都会进入审核中或被拒绝。
* **拒绝设为 `100`。** 只有满分才能免于被拒绝，因此几乎所有会话都会被拒绝。
* **两个数值均设为 `0`。** 任何分数都不会被标记，检查实际上处于关闭状态。

将两个数值设置为相同的数字会移除审核中区间：分数低于该数值的会话会被拒绝，分数达到或超过该数值的会话则会通过。

当**打印件**和**屏幕截图**同时标记同一份证件时，仅会报告 `SCREEN_CAPTURE_DETECTED`。

跨摄像头人脸比对采用相同的逻辑，但边界处有一处区别：与审核阈值相等的分数仍会进入审核中。

有四项证件风险既不可配置，也不受阈值驱动。`POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` 始终流转至**审核**：与黑名单中的人脸相似但未确认完全匹配的自拍照，须由人工进行评判，绝不会自动拒绝，也绝不会被忽略。`BARCODE_SIGNATURE_INVALID` 始终流转至**审核**。它仅在条形码带有签发机构签名且未能通过加密签名验证时触发，因此在任何配置下都不会忽略已证实的伪造行为。`DOCUMENT_BACK_SIDE_NOT_AVAILABLE` 始终为**信息**且绝不影响决策：它反映的是 Didit 证件目录的局限性，而非所出示证件本身的属性，因此在任何配置下都不会对真实持有人作出拒绝或审核决定。
`FRONT_CAMERA_CAPTURED_DOCUMENT` 始终流转至**审核**。
它仅在扫描证件时前置摄像头拍摄的帧画面显示身份证件而没有人时触发，因此对于完全无法体现是谁持有证件的采集画面，始终会交由人工处理。
只要启用了证件采集自拍比对（`is_document_selfie_portrait_match_enabled`），就会执行此项检查。

## 生成的警告

已对照 `collect_ocr_logs`、证件采集流程以及 `process_ocr_logs_and_get_status` 进行核验。下方的简短描述为 API 返回的精确 `short_description` 字符串。

### 证件识别与质量

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `COULD_NOT_RECOGNIZE_DOCUMENT` | Could not validate Document | 系统无法确认提交证件的真实性或有效性 — 通常是由于图像质量较差或属于不支持的证件类型。该项也用作未识别处理失败的兜底项。 | 可配置 — 无效验证，默认人工审核 |
| `COULD_NOT_DETECT_DOCUMENT_TYPE` | Could not detect document type | 证件正面未能以高置信度与已知的官方证件设计匹配，或者 OCR 引擎无法对证件族（护照、身份证、驾照）进行分类。携带有效数据但版面不符合任何官方设计的证件（经过篡改或计算机生成的证件，或是尚未支持的新版设计）会归入此类。触发此项时，`DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 会被抑制（由于类型未知，因此提示“不支持”会产生矛盾）。 | 可配置 — 无效验证，默认人工审核 |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Document not supported for your application | 识别出的证件类型不在应用的允许名单内。`additional_data` 包含国家/地区、证件类型、子类型以及区域相关的子类型。 | `error` — **自动拒绝** |
| `DOCUMENT_EXPIRED` | Document expired | 采集时：证件的到期日期早于当前时间（`error`，自动拒绝）。通过后：当已通过证件的日期过期时，持续到期监控会追加此警告并附带 `log_type: "warning"`，且报告状态变更为 `Expired`。 | 采集时为 `error`；监控触发为 `warning` |
| `DOCUMENT_SIDES_MISMATCH` | Document sides mismatch | 正面和背面图像不属于同一证件。 | 可配置 — 数据不一致，默认提示信息 |
| `DOCUMENT_BACK_SIDE_NOT_AVAILABLE` | Back side not available for this document | 工作流要求采集正反两面，正面已识别，但 Didit 的证件目录中该具体证件未登记背面，因此仅能采集正面。报告的证据仅含单面。所提交的证件本身没有问题，绝不会要求持有人重拍，且重新扫描也无法补充背面。`additional_data` 包含识别出的 `front_document_name`。 | `information` — 绝不影响决策 |
| `PORTRAIT_IMAGE_NOT_DETECTED` | Portrait image not detected | 在应当包含肖像照片的证件上未能定位到肖像（当用户先上传非肖像面时会暂缓判断）。 | `error` — **自动拒绝** |
| `DOCUMENT_HAS_NO_PORTRAIT` | Document has no portrait | 识别出的证件族任何一面均不包含肖像照片（某些居留许可、健康卡、登记证明、税务卡以及部分驾照/身份证）。这是该证件类型在目录层面的客观事实，并非图像质量问题 — 重新扫描证件无法改变此结果。 | 可配置 — 无肖像证件，默认人工审核 |
| `IMAGE_TOO_BLURRY` / `IMAGE_TOO_DARK` / `IMAGE_TOO_BRIGHT` | Document image is too blurry / too dark / too bright | 图像质量关卡拒绝了上传（提示用户重拍）。`additional_data` 包含未通过的 `side`。成功重拍将清除旧警告；在用户最后一次允许的尝试中会跳过该关卡，因此绝不会强行阻断用户。 | 可配置 — 按每项风险设置图像质量操作，默认提示信息 |

> [!NOTE]
>
> 采集流程还可能通过反馈代码 `IMAGE_RESOLUTION_TOO_LOW`、`DOCUMENT_NOT_FULLY_VISIBLE`、`IMAGE_QUALITY_TOO_LOW` 和 `DOCUMENT_OCCLUSION_DETECTED`（判定手指或物体在物理上遮挡了印刷文本）拒绝上传。每种情况都会在 SDK 中提示重拍，并在报告中作为独立风险记录，由“图像质量”设置进行路由分流 — `DOCUMENT_OCCLUSION_DETECTED` 和 `IMAGE_QUALITY_TOO_LOW` 共享同一操作。这些代码描述的是*采集*过程：重拍成功即可清除警告。遮挡字段是否应当影响最终决策，则属于下方在决策时触发、默认设为人工审核的独立完整性风险 `CRITICAL_FIELD_OCCLUSION_DETECTED`。

> [!TIP]
>
> 如果您的工作流依赖人脸比对而非证件肖像来核实身份，请考虑将**无肖像证件**路由至拒绝 — 否则无肖像证件族进入人脸比对环节时将缺少比对基准。

### 字段提取

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `NAME_NOT_DETECTED` | First name and/or last name not detected | 无法提取名和/或姓。当持有人合法拥有单名（即仅有一个姓名）（单名国家/地区，或 MRZ 本身仅含单个姓名）且至少提取到一个姓名值时，予以豁免。 | 可配置 — 无效验证，默认人工审核 |
| `DATE_OF_BIRTH_NOT_DETECTED` | Date of birth not detected | 无法从应当包含出生日期的证件中提取出生日期。 | 可配置 — 无效验证，默认人工审核 |
| `DOCUMENT_NUMBER_NOT_DETECTED` | Document number not detected | 无法提取证件号码或个人号码。 | 可配置 — 无效验证，默认人工审核 |
| `EXPIRATION_DATE_NOT_DETECTED` | Expiration date not detected | 无法从应当包含到期日期的证件中提取到期日期。 | 可配置 — 未检测到到期日期，默认提示信息 |
| `INVALID_DATE` | Invalid Date | 证件上的日期（出生日期或到期日期）无法解析为有效日期。在当前采集流程中，这会在上传期间体现为重拍提示，而非存储的警告；该代码仍保留在“无效验证”路由分组中，并可能出现在较早的会话中。 | 可配置 — 无效验证，默认人工审核 |
| `DOCUMENT_NUMBER_FORMAT_MISMATCH` | 证件号码格式不匹配 | 证件号码与为此证件类型配置的预期格式不匹配。`additional_data` 包含 `expected_format` 和 `extracted_value`。 | 可配置 — 格式不匹配，默认为审核 |
| `PERSONAL_NUMBER_FORMAT_MISMATCH` | 个人编号格式不匹配 | 个人编号与为此证件类型配置的预期格式不匹配。 | 可配置 — 格式不匹配，默认为审核 |
| `CRITICAL_FIELD_OCCLUSION_DETECTED` | 关键证件字段被遮挡 | 遮挡检查报告拍摄图像上的关键打印字段被物理遮挡 — 身份号码、姓名、出生日期或到期日期。这是一个证件完整性信号，而不是拍摄质量信号：遮挡报告所核对的那些关键数字，正是涂黑或篡改证件的典型特征。被遮挡字段读取到的值将从提取结果中舍弃，而不是作为已确认的值返回，因此相应的 `*_NOT_DETECTED` 风险通常会伴随此警告一同出现。`additional_data` 在 `covered_fields` 中包含被遮挡的字段名称，当其中之一为 `document_number` 或 `personal_number` 提供数据时，还会包含 `covered_identifiers`。 | 可配置 — 关键字段被遮挡，默认为审核 |

### MRZ、QR、条形码

对于已知 MRZ 不可靠的证件类型，将跳过所有三种 MRZ 风险。

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `MRZ_NOT_DETECTED` | 未检测到 MRZ | 在应具有 MRZ 的证件上无法定位到 MRZ。 | 可配置 — 无效 MRZ，默认为信息 |
| `MRZ_VALIDATION_FAILED` | MRZ 无效 | MRZ 未通过校验和/格式验证。通常是拍摄质量低所致；也可能表明存在篡改。 | 可配置 — 无效 MRZ，默认为信息 |
| `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | MRZ 与 OCR 提取的数据存在不一致 | MRZ 内容与 VIZ（可见区）OCR 不一致。可能存在涂改。 | 可配置 — 数据不一致，默认为信息 |
| `QR_NOT_DETECTED` | 未检测到二维码 | 在应具有二维码的证件上无法定位到二维码。 | 可配置 — 无效代码，默认为信息 |
| `QR_VALIDATION_FAILED` | 二维码验证失败 | 二维码内容无法与证件的其他部分对照验证。 | 可配置 — 无效代码，默认为信息 |
| `BARCODE_NOT_DETECTED` | 未检测到条形码 | 在应具有条形码的证件上无法定位到条形码。 | 可配置 — 无效代码，默认为信息 |
| `BARCODE_VALIDATION_FAILED` | 条形码验证失败 | 条形码内容无法与证件的其他部分对照验证。 | 可配置 — 无效代码，默认为信息 |
| `BARCODE_SIGNATURE_INVALID` | 条形码签名无效 | 条形码包含签发机构的数字签名，但该签名未通过验证 - 条形码中的数据并非机构签署的数据，表明存在伪造或篡改证件。目前针对**法国 2D-Doc (ANTS)** 条形码进行检查，已验证的签名允许 Didit 提升字段可信度而无需 MRZ 相互印证；AAMVA（美国/加拿大驾照和身份证件）签名仅作检测和记录，尚未强制执行。 | 固定 - 审核（独立的操作组 `invalid_barcode_signature_action`；尚不可通过控制台/API 配置） |
| `DATA_INCONSISTENT` | 证件中的 OCR 数据不一致 | 从证件不同部分提取的数据不一致 — 通常是同一证件的正反两面。 | 可配置 — 数据不一致，默认为信息 |

> [!NOTE]
>
> 条形码签名验证目前涵盖法国国民身份证，其 ANTS 2D-Doc 条形码由签发机构签名。仅当签名检查本身拒绝 payload 时，才会触发 `BARCODE_SIGNATURE_INVALID`。未包含签名的条形码、由尚未纳入 Didit 信任库的机构签名的条形码，或签名无法解码的条形码将被视为未经认证的数据，并照常与 MRZ 和打印文本进行验证，而不会触发此风险。
>
> 美国和加拿大的驾照（AAMVA）条形码未经过密码学验证：那里的数字签名是可选的且因管辖区而异，并且没有任何管辖区发布验证密钥，因此 Didit 仅检测并记录 payload 是否包含签名；签名本身绝不会被检查。目前 AAMVA 签名失败不作为风险信号。被篡改的 AAMVA payload 仅会表现为 `BARCODE_VALIDATION_FAILED`，并且仅在篡改同时导致条形码与 MRZ 或打印/OCR 数据不一致时才会出现 - 在内部数据原本一致的 payload 上伪造的签名将完全不会产生任何信号。
>
> 出现 `BARCODE_SIGNATURE_INVALID` 时绝不会要求用户重新拍摄：与 payload 不匹配的签名无法通过拍出更好的照片来解决。

### 身份匹配

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `ID_DOCUMENT_IN_BLOCKLIST` | 身份证件在黑名单中 | 证件与黑名单中的证件匹配（相同的出生日期、签发国家/地区和完全相同的证件号码），或与手动加入黑名单的证件号码匹配。`additional_data` 包含被列入黑名单的会话引用。 | `error` — **自动拒绝** |
| `ID_DOCUMENT_IN_ALLOWLIST` | 身份证件在白名单中 | 证件号码与您的证件白名单匹配，因此跳过了重复用户操作。`additional_data` 包含 `document_number`。 | `information` |
| `POSSIBLE_DUPLICATED_USER` | 来自其他会话的可能重复用户 | 您应用中的另一份证件具有相同的出生日期、相同的签发国家/地区以及高度相似的姓名 — 属于不同的用户（`vendor_data`），无论该会话的状态如何。`additional_data` 包含重复的会话引用。 | 可配置 — 重复用户，默认为信息 |
| `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | 证件姓名与其他已通过的证件不同 | 此证件上的姓名与同一用户先前已通过的证件不一致。仅针对 Didit 协议 (UserKYC) 账户生成，不适用于标准 API 会话。 | 可配置 — 数据不一致，默认为信息 |
| `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | 身份证件验证证件之间的数据不匹配 | 同一会话中的两份身份证件在姓名/出生日期上不一致。 | 可配置 — 数据不一致（Data Inconsistency），默认为 information |
| `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY` | 证件采集期间的自拍照与证件头像不匹配 | 在证件采集期间通过用户前置摄像头拍摄的人脸与证件上的头像不太匹配。 | 基于阈值：低于拒绝阈值为 `error`，达到或低于审核阈值为 `warning` |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | 证件采集期间的自拍照与黑名单中的人脸匹配 | 证件采集期间由前置摄像头拍摄的自拍照中的人脸，以高置信度与您的人脸黑名单中的人脸匹配，无论该人脸是通过活体检测添加、来自其他会话的证件采集自拍照，还是通过上传添加。当黑名单中的人脸来自某个会话时，`additional_data` 携带黑名单会话引用（`blocklisted_session_id`、`blocklisted_session_number`），并包含匹配自拍照的 `face_image_source`（`front_image_camera_front` 或 `back_image_camera_front`）。 | `error` — **自动拒绝** |
| `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` | 证件采集期间的自拍照可能与黑名单中的人脸匹配 | 证件采集自拍照中的人脸与您的人脸黑名单中的人脸相似，但相似度不足以确认匹配。`additional_data` 同上。 | `warning` — **始终审核** |
| `FRONT_CAMERA_DUPLICATED_FACE` | 证件采集期间的自拍照与已通过的用户匹配 | 证件采集期间由前置摄像头拍摄的自拍照中的人脸，以高置信度与您应用中已通过验证的用户的人脸匹配，因此可能是同一个人在另一个账户下再次验证。`additional_data` 携带匹配的会话（`duplicated_session_id`、`duplicated_session_number`）以及匹配自拍照的 `face_image_source`。 | 依据**静默采集中的重复人脸**设置（默认通过，`information`） |
| `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` | 证件采集期间的自拍照可能与已通过的用户匹配 | 证件采集自拍照中的人脸与您应用中已通过验证的用户的人脸相似，但相似度不足以确认匹配。`additional_data` 同上。 | 依据**静默采集中的重复人脸**设置（默认通过，`information`） |
| `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` | 证件采集自拍照与姓名不同的用户匹配 | 在触发 `FRONT_CAMERA_DUPLICATED_FACE` 的基础上触发，表明已通过的用户是以不同的姓名进行验证的。`additional_data` 会补充 `name_match_score`；绝不会携带其他用户的姓名。 | 依据**静默采集重复且姓名不同**（Silent Capture duplicate with a different name）设置（默认审核，`warning`） |
| `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` | 证件采集自拍照与出生日期不同的用户匹配 | 在触发 `FRONT_CAMERA_DUPLICATED_FACE` 的基础上触发，表明已通过用户的身份证件显示了不同的出生日期。同一人的不同证件（例如身份证之后的护照）、换发/更新的证件，或来自同一国家/地区的相同证件号码不会被标记。`additional_data` 会补充 `mismatch_dimensions`，绝不会携带其他用户的证件数据。 | 依据**静默采集重复且出生日期不同**（Silent Capture duplicate with a different date of birth）设置（默认审核，`warning`） |
| `FRONT_CAMERA_CAPTURED_DOCUMENT` | 前置摄像头采集到身份证件而非用户 | 扫描证件时前置摄像头拍摄的画面显示的是身份证件（例如举到摄像头前的卡片）且没有人。不会计算该帧的证件采集自拍照匹配。 | 始终**审核** |

### 证件真实性 (防篡改)

在工作流中针对每种欺诈类型由阈值驱动。在独立 OCR API 上，这三种风险会无条件拒绝，且未产生可用分数的核验请求将返回 `In Review` 而非通过。

分数本身记录在每份 V3 报告中的 [`document_liveness`](https://docs.didit.me/zh/core-technology/id-verification/report-id-verification#证件活体检测评分) 下，即使未触发任何警告也是如此，因此已通过的证件仍可用于审计。

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `SCREEN_CAPTURE_DETECTED` | 检测到证件屏幕翻拍 | 证件是从屏幕上翻拍的，而非真实实体证件。 | 低于拒绝阈值为 `error`，低于审核阈值为 `warning`，否则为 `information` |
| `PRINTED_COPY_DETECTED` | 检测到证件复印件/打印件 | 证件疑似为打印件而非原件。 | 采用相同的三档阈值 |
| `PORTRAIT_MANIPULATION_DETECTED` | 检测到头像篡改 | 头像区域疑似被替换或修改。 | 采用相同的三档阈值 |
| `DOCUMENT_LIVENESS_NOT_COMPUTED` | 无法计算证件真实性核验 | 所请求的证件真实性（防伪）核验未返回可用分数 — 服务商故障、返回非 200，或返回 HTTP 200 但包含 `status="ERR"` — 因此从未对该证件进行头像替换、打印件或屏幕翻拍检查。缺少分数并不能作为证件真实性的证据。仅适用于独立 OCR API。 | `warning` + `In Review`（不可配置；绝不会覆盖 `Declined`） |

### 采集通道完整性

| 风险 | 简短描述 | 原因 | 可通过以下项配置 | 默认值 |
| - | - | - | - | - |
| `INJECTION_ATTACK_DETECTED` | 检测到注入攻击 | 图像采集是由外部注入的，而非通过设备自带摄像头采集：可播放任意视频的软件虚拟摄像头、由页面或浏览器自动化生成的摄像头画面、被挂钩的摄像头或附加到应用上的插桩工具提供了这些帧。`additional_data.reasons` 仅列出证明该情况的原因，`source` 为 `capture_integrity`。该检测适用于证件采集以及用于身份核查所拍摄的自拍照。 | `id_verification_injection_attack_action` | **拒绝** |

`log_type` 反映了所配置的操作：拒绝对应 `error`，审核对应 `warning`，无操作对应 `information`。
建议的操作：将已拒绝的会话视为遭到注入攻击的采集结果，并要求该人员在带有内置摄像头的实体设备上重试。
真实用户可能产生的信号绝不会触发 `INJECTION_ATTACK_DETECTED`，且保持为提示信息。
转接真实摄像头的应用（例如将手机用作网络摄像头，或在真实网络摄像头上叠加特效层）不会被报告为注入攻击。
这是注入攻击检测，它与呈现攻击检测（向真实摄像头出示伪造物）不同。

### 已知公开证件图像

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `PUBLIC_DOCUMENT_IMAGE_DETECTED` | 检测到已知互联网公开证件图像 | 提交的证件图像与已知的互联网公开图像匹配（例如证件样本、新闻图片或图库库存照片），因此不可能是用户本人实体证件的照片。比对使用针对 Didit 已知公开证件图像库的精确和感知（pHash/dHash）指纹识别；`additional_data` 包含 `match_type`（`exact` 或 `perceptual`）、`source`、`source_url` 和 `similarity_score`（0-100）。 | 固定 - 工作流中为审核；在独立 `/id-verification` API 上**自动拒绝** |

### 预期详细信息不匹配

当您向会话传递 `expected_details` 时，Didit 会针对每个不匹配的字段发出不匹配警告。一个分组配置（`expected_details_mismatch_action`，默认审核）控制所有这些警告的路由：

| 风险 | 简短描述 | 原因 |
| - | - | - |
| `FULL_NAME_MISMATCH_WITH_PROVIDED` | 姓名与提供的信息不匹配 | 提供的姓名在与证件比对时的得分低于姓名匹配阈值。 |
| `DOB_MISMATCH_WITH_PROVIDED` | 出生日期与提供的信息不匹配 | 提供的出生日期不匹配。 |
| `GENDER_MISMATCH_WITH_PROVIDED` | 性别与提供的信息不匹配 | 提供的性别不匹配。 |
| `COUNTRY_MISMATCH_WITH_PROVIDED` | 国家/地区与提供的信息不匹配 | 提供的国家/地区与 `issuing_state` 不匹配。 |
| `NATIONALITY_MISMATCH_WITH_PROVIDED` | 国籍与提供的信息不匹配 | 提供的国籍不匹配。 |
| `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | 身份证件号码与提供的信息不匹配 | 提供的证件号码与证件号码、个人编号或税号不匹配。 |

每个不匹配警告都会在 `additional_data` 中携带预期值和提取值。

### 年龄

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `MINIMUM_AGE_NOT_MET` | 未达到最低年龄 | 持有人未达到配置的最低年龄（全局或按国家/地区/州）。`additional_data` 包含 `min_age_allowed` 和 `user_age`。 | 可配置 — 最低年龄，默认拒绝（`error`）；在独立 OCR API 上无条件拒绝 |
| `MAXIMUM_AGE_EXCEEDED` | 超过最高年龄 | 持有人超过配置的最高年龄。`additional_data` 包含 `max_age_allowed` 和 `user_age`。 | 可配置 — 最高年龄，默认拒绝（`error`） |
| `AGE_NOT_DETECTED` | 未检测到年龄 | 自适应年龄验证工作流：无法从证件中提取年龄。 | `error` — **自动拒绝** |
| `AGE_BELOW_MINIMUM` | 年龄低于最低要求 | 自适应年龄验证工作流：提取的年龄低于最低要求。 | `error` — **自动拒绝** |

### 地址

| 风险 | 简短描述 | 原因 | 严重程度 |
| - | - | - | - |
| `UNPARSED_ADDRESS` | 无法确定地址位置 | 证件定义了地址字段，但提取的地址无法被解析或定位地理位置。 | 可配置 — 无法解析的地址，默认提示信息 |

## 跨会话证件比对

除上述警告外，V3 ID 报告还会提供一个 `matches[]` 数组 — 最多包含应用中具有相同出生日期、相同签发国家/地区以及高度相似姓名的其他 5 个证件（黑名单中的证件还要求证件号码完全匹配），属于同一用户的会话除外。添加到黑名单中的证件会显示 `is_blocklisted: true`。白名单中的证件仍会出现在比对结果中，但会跳过针对重复用户的操作。

每个比对项包含 `session_id`、`session_number`、`vendor_data`、`verification_date`、`user_details`（`name`、`document_type`、`document_number`）、`status`、`is_blocklisted`、`api_service` 以及经过签名的 `front_image_url`。

## 示例

### 处于默认路由（提示信息）的可配置警告

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "QR_NOT_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "QR not detected",
    "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
    "node_id": "id_primary"
  }
]
```

### 过期证件自动拒绝

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOCUMENT_EXPIRED",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Document expired",
    "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
    "node_id": "id_primary"
  }
]
```

### 带有 payload 的预期详细信息不匹配

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOB_MISMATCH_WITH_PROVIDED",
    "additional_data": {
      "expected_dob": "1990-01-01",
      "extracted_dob": "1991-03-15"
    },
    "log_type": "warning",
    "short_description": "Date of birth mismatch with provided information",
    "long_description": "The provided date of birth in `expected_details` doesn't match the date extracted from the document.",
    "node_id": "id_primary"
  }
]
```

## 警告类型

系统会根据应用的配置为每个风险分配一个严重程度。三种严重程度分别为：

## 相关内容

* [身份证件验证报告](https://docs.didit.me/zh/core-technology/id-verification/report-id-verification.md) — 完整报告结构和状态。
* [证件监控](https://docs.didit.me/zh/core-technology/id-verification/document-monitoring-id-verification.md) — Didit 如何检测篡改和跨会话重复。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — `session.status.updated` 在 ID 步骤完成后立即携带警告信息。
* [数据模型 — 身份证件验证](https://docs.didit.me/zh/reference/data-models.md#身份证件验证) — 逐字段的标准规范结构。
* [数据模型 — 警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象) — `warnings[]` 中每个条目的结构。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.