> ## 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 从政府签发的身份证明文件（护照、身份证、驾驶执照和居留许可）中提取并验证的所有内容。它整合了 OCR 识别的个人基本信息与证件字段、已拍摄媒体文件的签名 URL、已解析且包含地理位置的地址数据、每面图像质量评分、MRZ 内容、多文字系统（拉丁文/非拉丁文）明细，以及跨会话证件匹配结果。

用户在工作流中完成证件拍摄步骤（或调用独立 OCR endpoint）后，系统会生成该报告。Didit 会识别证件类型、运行 OCR、验证 MRZ / 条形码 / 二维码、解析地址、筛查防篡改迹象（屏幕翻拍、复印件、人像篡改），并将该证件与您应用中拍摄过的所有其他证件进行比对。

每份报告都带有独立的 `status`（独立于整体会话状态），反映身份证件验证单项步骤的处理结果：

* **已通过** — 证件已识别，所有必需字段均已提取，且未触发路由至拒绝的警告。
* **审核中** — 触发了一项或多项警告，且您的工作流将其路由至人工审核。
* **已拒绝** — 触发了自动拒绝条件（不支持的证件、证件已过期、缺少人像照片、命中黑名单、自适应年龄检查失败），或触发了配置操作为拒绝的警告（最低/最高年龄默认配置为拒绝）。
* **已过期** — 证件的 `expiration_date` 在验证**之后**已过。Didit 的持续到期监控会将报告状态从 `Approved` 切换为 `Expired`，追加 `DOCUMENT_EXPIRED` 警告，并将已通过的会话流转至 `Kyc Expired` 会话状态。
* **未完成** — 用户未完成拍摄步骤。

## 在 API 响应中的位置

身份证件报告包含在 `id_verifications[]` 数组中 — **始终为 JSON 数组**，绝非单一的 `id_verification` 对象。当工作流运行多个证件步骤（例如主身份证件加上升级验证步骤）时，数组中会出现多条记录。

* **会话决策 API** — `GET /v3/session/{sessionId}/decision/` 在顶层返回 `id_verifications[]`。请参阅 [检索会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。
* **Webhook** — 一旦该步骤生成数据，`session.status.updated` payload 就会包含相同的 `id_verifications[]` 数组。请参阅 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)。
* **独立 OCR API** — 直接提交证件会返回包含相同字段的单一 `id_verification` 对象。请参阅 [独立 OCR API](https://docs.didit.me/zh/standalone-apis/id-verification.md)。

> [!NOTE]
>
> 读取 `response.id_verifications[0]` 并遍历该数组。单一的 `id_verification` 结构仅存在于独立 OCR API 中 — 在 v3 决策 endpoint 中并不存在。

## 数据结构

权威的逐字段数据结构请参见[数据模型](https://docs.didit.me/zh/reference/data-models.md#身份证件验证)参考页面。以下字段直接来自 `IDVerificationV3Serializer`，该序列化器扩展了 `IDVerificationV2Serializer`，并新增了 `node_id`、跨会话 `matches[]` 数组以及 Silent Capture 的 `document_selfie_face_matches[]` 数组。

### 顶层字段

| 字段 | 类型 | 描述 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Expired" \| "Not Finished"` | 证件验证步骤状态。 |
| `node_id` | string \| null | 生成此报告的工作流图节点。 |
| `document_type` | `"Passport" \| "Identity Card" \| "Driver's License" \| "Residence Permit" \| "Health Insurance Card" \| "Tax Card" \| "Social Security Card" \| "Work Permit" \| "Visa" \| "Public Service Card" \| "Birth Certificate" \| "Firearm License" \| "Other" \| null` | 识别出的顶层证件类别（人类可读）。 |
| `document_subtype` | string \| null | 来自 Didit 证件注册库的证件子类型代码，已根据工作流证件设置接受的范围进行过滤。特定地区的证件包含地区名称，例如 `QUEENSLAND_DRIVER_LICENSE_GENERIC`。完整的代码列表请参见[证件子类型](https://docs.didit.me/zh/core-technology/id-verification/document-subtypes-id-verification.md)，包括如何区分美国商业驾照（CDL）与标准驾照。 |
| `document_number` | string | 经 OCR 识别的证件号码。对于同时印有驾照号和卡号的驾照，请参见表格下方的说明。 |
| `personal_number` | string | 经 OCR 识别的个人/公民身份识别号码（当与证件号码不同时）。 |
| `portrait_image`, `front_image`, `front_video`, `back_image`, `back_video`, `full_front_image`, `full_back_image` | string (signed URL) | 采集的媒体文件。URL 经过签名且有时效性，请及时下载，切勿保存该 URL。 |
| `front_image_camera_front`, `back_image_camera_front` | string (signed URL) \| null | 证件采集期间由用户前置摄像头拍摄的帧。用于跨摄像头人脸核对，并与您的[人脸黑名单](https://docs.didit.me/zh/console/blocklist-users.md#人脸黑名单)进行比对；每一张也可以[添加到人脸黑名单](https://docs.didit.me/zh/management-api/lists/create-entry.md#来自证件拍摄自拍照的人脸)。 |
| `front_image_camera_front_face_match_score`, `back_image_camera_front_face_match_score` | float (0–100) \| null | 前置摄像头帧与证件人像之间的相似度分数。 |
| `document_selfie_face_matches` | array \| null | 人脸与证件采集期间拍摄的自拍照匹配的历史会话或人脸黑名单条目（[Silent Capture 人脸搜索](https://docs.didit.me/zh/core-technology/face-search/overview.md#证件采集期间拍摄的自拍照)）。条目格式与 `liveness_checks[].matches` 相同；`match_image_url` 为会过期的预签名 URL。对于较早的会话或未运行搜索的情况为 `null`，运行后未发现匹配项则为 `[]`。 |
| `front_image_quality_score`, `back_image_quality_score` | object \| null | 各面的图像质量评估（参见图像质量分数）。 |
| `document_liveness` | object \| null | 每种欺诈类型的证件防伪活体分数及其评判阈值（参见证件活体分数）。仅限 V3。 |
| `date_of_birth`, `expiration_date`, `date_of_issue` | string (YYYY-MM-DD) | 证件日期。 |
| `age` | number | 根据 `date_of_birth` 计算出的持证人周岁年龄。 |
| `issuing_state` | string (ISO 3166-1 alpha-3) | 签发国家代码。 |
| `issuing_state_name` | string | 本地化的国家名称。 |
| `first_name`, `last_name`, `full_name` | string | 由 `preferred_characters` 指定的文字系统所对应的持证人姓名（见下文）。 |
| `gender` | `"M" \| "F" \| "U"` | 性别（如证件上有此信息；`U` = 未知）。 |
| `address`, `formatted_address` | string | 原始地址及经地理编码/格式化的地址字符串。 |
| `place_of_birth` | string | 经 OCR 识别的出生地。 |
| `marital_status` | `"SINGLE" \| "MARRIED" \| "DIVORCED" \| "WIDOWED" \| "UNKNOWN"` | 婚姻状况（如证件上有此信息）。 |
| `nationality` | string (ISO 3166-1 alpha-3) | 持证人国籍（当与签发国家不同时）。 |
| `extra_fields` | object | 证件特有附加信息（驾照准驾车型、血型、其他文字系统姓名、`tax_number` 等）。 |
| `mrz` | object \| null | 解析后的 MRZ 键/值字段。 |
| `parsed_address` | object \| null | 结构化且经地理编码的地址（`street_1`、`street_2`、`city`、`region`、`country`、`postal_code`、`address_type`、`formatted_address`、`document_location`、`raw_results`、`is_best_match`）。 |
| `extra_files[]` | array of signed URLs | 附加到此证件的其他图像。 |
| `matches[]` | array | 跨会话证件匹配项（参见跨会话匹配）。 |
| `warnings[]` | array | 模块级警告：请参见[身份证件验证警告](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification.md)。 |

> [!NOTE]
>
> **`issuing_state` 始终是国家级别，绝非国家以下行政区级别。** 对于所有证件类型，包括由州或省签发的驾照（澳大利亚、美国、加拿大），`issuing_state` 和 `issuing_state_name` 报告的都是**国家**（例如 `AUS` / `Australia`），而非州/省。当证件包含国家以下行政区的值时，可在 `parsed_address.region` 中单独获取（在某些证件类型上回退至 `extra_fields.state`）。**Business Console** 会话概览在存在该值时，会将其显示在**签发国家**下方的 **Region** 行中。

> [!NOTE]
>
> **包含两个号码的驾照（澳大利亚）。** 澳大利亚驾照同时印有驾照号（licence number，用于标识持证人的驾驶资格，补发卡片时保持不变）和卡号（card number，用于标识实体卡片，每次重新签发时都会变更）。对于这些驾照，Didit 始终采用相同的映射方式：
>
> * `personal_number`：**驾照号**
> * `document_number`：**卡号**
>
> 这适用于澳大利亚的所有州和领地（NSW、VIC、QLD、WA、SA、TAS、ACT、NT）。在某些版本中，卡号仅印在背面，因此只有在采集了驾照背面时才能读取。当无法读取卡号时，驾照号将**同时**作为 `document_number` 和 `personal_number` 上报，因此验证完成后 `document_number` 始终包含一个标识符。无论哪种情况，`personal_number` 都是驾照号。在其他证件类型上，`document_number` 仍是主要的 OCR 识别号码，其本身可能就是持证人级别的标识符。

> [!NOTE]
>
> **阿根廷 CUIL 为 `extra_fields.tax_number`，绝非 `personal_number`。**
> 阿根廷证件上印有 CUIL（AFIP、ANSES 和征信机构所依据的 11 位标识符），每种证件上的印刷位置不同，且 DNI 在其旁边还印有第二个 11 位数字：
>
> * 在**驾照**上，`personal_number` 携带的即为 CUIL；
> * 在 **DNI** 上，`personal_number` 携带的是 *número de trámite*（办理编号），该编号用于标识办卡申请，并非持有人本人的标识符。DNI 的 CUIL 是从其独立的印刷字段中读取的。
>
> 因此，对于阿根廷证件，`personal_number` **并不是**可靠的 CUIL：在 DNI 上，它是一个 11 位数字，在任何登记系统中都会静默返回无结果。请改用 `extra_fields.tax_number`。无论持有人出示哪种阿根廷证件，仅当该值通过真实 CUIL 校验（个人前缀加上模 11 校验位）时，Didit 才会以不带分隔符的规范数字形式（`27111111117`）进行报告。当卡片上的 CUIL 无法读取时，该键会被省略，而不是填充一个非 CUIL 的数字；您可以采集驾照作为第二份证件，或通过问卷回答或会话的 `metadata` 收集 CUIL，以覆盖这些用户。

### 图像质量评分

`front_image_quality_score` 和 `back_image_quality_score` 分别返回：

| 字段 | 类型 | 衡量指标 |
| - | - | - |
| `focus_score` | number 0–100 | 清晰度：最高 10% 的局部拉普拉斯方差，对均匀背景具有稳健性。权重 45%。 |
| `brightness_score` | number 0–100 | 惩罚过暗或过曝的图像。权重 30%。 |
| `brightness_issue` | `"ok" \| "too_dark" \| "too_bright"` | 当 `brightness_score` 偏低时的亮度问题方向。 |
| `resolution_score` | number 0–100 | 基于采集图像的总像素数。权重 25%。 |
| `is_document_fully_visible` | boolean \| null | 当证件的四个角全部可见时为 `true`，当任何角被切除时为 `false`，当角点检测不可用时为 `null`。 |
| `overall_score` | number 0–100 | 加权综合得分（清晰度 45%、亮度 30%、分辨率 25%）。 |

> [!TIP]
>
> 将 `overall_score` 用作快速的适用性检查：高于 **70** 的分数通常表明采集质量足以进行可靠的验证。

### 证件活体检测评分

`document_liveness` 报告[证件活体检测](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification.md#证件真实性-防篡改)测量的结果，**无论其是否引发了警告**。警告仅在分数低于工作流的某一阈值时才会产生，因此在引入此字段之前，已通过的证件完全不携带任何活体证据；该字段正是您对已通过的会话进行审计的方式。当检查未运行时（例如非证件核验方式，或会话日志中记录的模型服务中断），该字段为 `null`。

它针对每种欺诈类型（`portrait_replace`、`printed_copy` 和 `screen_replay`）各包含一个对象，每个对象具有：

| 字段 | 类型 | 含义 |
| - | - | - |
| `score` | number 0–100 \| null | 证件针对该欺诈类型为真实证件的可能性（越高 = 越可能是真实证件）。它是两面中的**最低值**，也是决策所使用的值。当两面均未产生可用分数时为 `null`（例如在未检测到人像的一面上，人像分数会被丢弃）。 |
| `front`, `back` | number 0–100 \| null | 每个已采集面所对应的分数。对于未采集或分数被丢弃的一面为 `null`。 |
| `decline_threshold`, `review_threshold` | number \| null | 身份证件验证节点评估该证件时保存的阈值。后续工作流修改不会改变它们。当历史评估证据不可用时为 `null`。 |
| `bucket` | `"approve" \| "review" \| "decline" \| null` | `score` 相对于这些阈值所处的状态：低于 `decline_threshold` → `decline`，低于 `review_threshold` → `review`，否则为 `approve`。当没有可用分数、未应用该检查或历史评估证据不可用时为 `null`。该 bucket 描述的是针对此欺诈类型的检查，而非整体会话状态。 |

```json theme={null}
"document_liveness": {
  "portrait_replace": {
    "score": 96.46,
    "front": 96.46,
    "back": 98.2,
    "decline_threshold": 35,
    "review_threshold": 70,
    "bucket": "approve"
  },
  "printed_copy": {
    "score": 91.2,
    "front": 91.2,
    "back": 93.7,
    "decline_threshold": 35,
    "review_threshold": 77,
    "bucket": "approve"
  },
  "screen_replay": {
    "score": 99.9,
    "front": 99.9,
    "back": 99.5,
    "decline_threshold": 30,
    "review_threshold": 70,
    "bucket": "approve"
  }
}
```

对于未保存评估证据的历史证件，存储的分数仍然可见，但阈值和 `bucket` 均为 `null`。当前工作流设置绝不会用于重构历史结果。这同样适用于尚未完成证件评估的采集。

Business Console 会在会话的身份证件验证部分的**证件活体检测**区块中显示相同的这三行。

### 跨会话匹配

`matches[]` 列出您的应用中与此证件匹配的最多 **5** 份其他证件：相同的**出生日期**、相同的**签发国家/地区**以及高度相似的**姓名**。列入黑名单的证件还要求证件号码完全匹配。属于同一用户（相同 `vendor_data`）的会话将被排除。

每个条目包含 `session_id`、`session_number`、`vendor_data`、`verification_date`、`user_details`（`name`、`document_type`、`document_number`）、`status`、`is_blocklisted`（当证件已添加到您的黑名单时为 `true`）、`api_service` 以及经过签名的 `front_image_url`。

## 状态值

| 状态 | 含义 | 下游影响 |
| - | - | - |
| `Approved` | 证件已被识别，已提取必填字段，所有检查均已达到配置的阈值并通过。 | 计为一次成功的身份证件验证。 |
| `In Review` | 触发了一项或多项警告，并且工作流会将其转入审核。 | 会话也将转为 `In Review`，直至审核员进行处理。 |
| `Declined` | 触发了自动拒绝条件（不受支持的证件、已过期证件、缺少人像照片、命中黑名单、自适应年龄不合格）或触发了配置为拒绝的警告。 | 除非另一个已通过的分支满足工作流要求，否则该会话将被拒绝。 |
| `Expired` | 证件的到期日期在批准**之后**已过。由 Didit 的持续证件监控设置（默认开启，**Expiration mode** 为 **Allow expired** 的国家/地区和证件类型除外），同时伴有 `DOCUMENT_EXPIRED` 警告。 | 已通过的会话将转为 `Kyc Expired`。 |
| `Not Finished` | 用户放弃了采集步骤。 | 身份证件分支未产生结果。 |

## 多文字系统证件 (拉丁 / 非拉丁)

部分证件（例如吉尔吉斯斯坦、哈萨克斯坦、俄罗斯、日本、韩国、中国、阿拉伯语、泰国等）会在持证人的姓名、地址或出生地信息中**同时**印制拉丁转写**并且**印制本地文字系统。您可以通过工作流（或独立 API）设置中的 `preferred_characters` 来选择哪个文字系统用于填充顶层响应字段：

| 值 | 用于填充顶层字段的内容 | 另一种文字系统存入 |
| - | - | - |
| `latin` *(默认)* | 证件上印制的拉丁转写 | `extra_fields.*_non_latin` |
| `non_latin` | 证件上印制的本地文字系统值 | `extra_fields.*_latin` |

替代文字系统的值位于 `extra_fields` 内，带有相应后缀键名：`first_name_non_latin`、`last_name_non_latin`、`middle_name_non_latin`、`full_name_non_latin`、`address_non_latin`、`place_of_birth_non_latin`（或对应的 `_latin` 变体）。

### 替代文字系统字段何时出现

* **仅当证件上确实同时存在两种文字系统时。** 如果名义上标记为“Surname-Kyrgyz (Cyrillic)”的 OCR 字段被提取为拉丁文字文本（同形异义字或拉丁转写），则其**不**符合非拉丁替代值的条件，并且该键会被省略。
* 当名字、中间名和姓氏组件均可用时，`full_name_non_latin`（以及 `full_name_latin`）始终由这些单独的组件**重新组合** — 为了保持一致性，OCR 提取的原始“Full Name”字段将被忽略。
* 当 `preferred_characters=latin` 但证件**仅**包含非拉丁文本时（因此顶层字段最终为非拉丁文本），Didit 会执行一次转写处理，并提供 `first_name_latin`、`last_name_latin`、`middle_name_latin`、`full_name_latin`、`place_of_birth_latin` 和 `address_latin` 作为拉丁备选字段。

```json theme={null}
{
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "extra_fields": {
    "first_name_non_latin": "Айна"
  }
}
```

`last_name_non_latin` 不存在，因为在此样本中，证件的“Surname (Cyrillic)”字段返回的是拉丁字符 — 没有提取到真正的非拉丁姓氏。

## 示例

### Approved — 无异常西班牙身份证 (所有字段)

```json theme={null}
{
  "id_verifications": [
    {
      "status": "Approved",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "personal_number": "SAMPLE-PER-12345",
      "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
      "front_image": "https://<media-host>/.../front.jpg?signature=...",
      "front_video": "https://<media-host>/.../front.mp4?signature=...",
      "back_image": "https://<media-host>/.../back.jpg?signature=...",
      "back_video": "https://<media-host>/.../back.mp4?signature=...",
      "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
      "full_back_image": "https://<media-host>/.../full_back.jpg?signature=...",
      "front_image_camera_front": null,
      "back_image_camera_front": null,
      "front_image_camera_front_face_match_score": null,
      "back_image_camera_front_face_match_score": null,
      "front_image_quality_score": {
        "focus_score": 85.3,
        "brightness_score": 92.1,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 84.6
      },
      "back_image_quality_score": {
        "focus_score": 79.1,
        "brightness_score": 90.5,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 81.5
      },
      "date_of_birth": "1990-01-01",
      "age": 35,
      "expiration_date": "2031-06-02",
      "date_of_issue": "2021-06-02",
      "issuing_state": "ESP",
      "issuing_state_name": "Spain",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "gender": "M",
      "address": "Avda de Madrid 34",
      "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
      "place_of_birth": "Madrid",
      "marital_status": "SINGLE",
      "nationality": "ESP",
      "extra_fields": {},
      "mrz": {
        "document_number": "SAMPLE-DOC-12345",
        "surname": "DOE",
        "name": "JOHN",
        "birth_date": "900101",
        "expiry_date": "310602"
      },
      "parsed_address": {
        "street_1": "Avda de Madrid 34",
        "street_2": null,
        "city": "Madrid",
        "region": "Madrid",
        "country": "ES",
        "postal_code": "28822",
        "address_type": "Avda",
        "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
        "document_location": { "latitude": 40.4168, "longitude": -3.7038 },
        "raw_results": {
          "geometry": {
            "location": { "lat": 40.4168, "lng": -3.7038 },
            "location_type": "ROOFTOP"
          }
        },
        "is_best_match": true
      },
      "extra_files": [],
      "warnings": [],
      "node_id": "id_primary",
      "matches": []
    }
  ]
}
```

### In Review — 应当包含二维码的证件未检测到二维码

已精简 — 真实的响应始终包含上述所示的完整字段集。

```json theme={null}
{
  "id_verifications": [
    {
      "status": "In Review",
      "node_id": "id_primary",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "warnings": [
        {
          "feature": "ID_VERIFICATION",
          "risk": "QR_NOT_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "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"
        }
      ]
    }
  ]
}
```

## 安全注意事项

针对证件图像和视频返回的签名 URL 是临时的 — 它们在有限的有效时间窗口后就会过期。请将其视为短效链接：及时下载所需内容，并且不要缓存或对外公开展示。通常，您的应用只需要 `status`、少量个人信息字段以及各类警告 — 尽量减少存储的数据，以最大限度降低未来发生数据泄露时的风险敞口。

## 相关内容

* [身份证件验证警告](https://docs.didit.me/zh/core-technology/id-verification/warnings-id-verification.md) — 完整的警告枚举、原因及处置方法。
* [证件监控](https://docs.didit.me/zh/core-technology/id-verification/document-monitoring-id-verification.md) — Didit 如何筛查篡改和跨会话重复。
* [支持的证件](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification.md) — 涵盖哪些证件类型和国家/地区。
* [证件子类型](https://docs.didit.me/zh/core-technology/id-verification/document-subtypes-id-verification.md) — 完整的 `document_subtype` 代码列表，包括美国商业驾照与标准驾照的检测。
* [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — 监听 `session.status.updated` 以接收报告。
* [数据模型 — 身份证件验证](https://docs.didit.me/zh/reference/data-models.md#身份证件验证) — 包含所有字段的规范架构。


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