> ## 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.

# Document AI 报告：提取字段

> Didit Document AI 报告参考：包含文档上传 endpoint、单份文档提取字段 JSON 结构、验证状态及 decision features[] 配置说明。

## 概述

Document AI 每个步骤最多接受 3 份证件（PDF 或图像 — PDF、JPG、JPEG、PNG、TIFF、WebP）。每份证件都会根据其配置的 `document_key` 进行分类，由视觉语言模型根据您的字段定义构建的模式进行读取，并运行 PDF/EXIF 取证分析。针对每份证件，它会存储：

* **提取的字段** — 以您配置的字段 `key` 为键的映射，其值的类型与您声明的一致（`text` → string、`number` → number、`date` → `YYYY-MM-DD`）。无法读取的字段为 `null`。
* **检测到的二维码与条形码** - 每个渲染页面的解码 payload 和像素坐标。能够定位但无法解码的二维码仍会返回，且 `parsed_payload: null`。
* **证件状态** — `Approved`、`In Review`、`Declined` 或 `Not Finished`。
* **证件元数据** — 文件取证信息，包括任何覆盖/篡改痕迹。
* **交叉核对结果** — 与已验证身份进行姓名匹配的结果，以及任何自定义字段交叉引用的结果。

## 上传证件

证件会逐一上传至 Document AI endpoint。在托管会话或 SDK 流程中，系统会自动为您处理此操作；其接口规范为：

```text theme={null}
POST https://verification.didit.me/v3/document-ai/documents/
multipart/form-data — Session-Token: <session token>
```

| 字段 | 必填 | 描述 |
| - | - | - |
| `document_key` | 是 | 此文件对应的已配置证件 |
| `document` | 是 | 要上传的文件 |
| `locale` | 否 | 用于解析屏幕标题/描述的语言环境 |

响应将推进流程：

```json theme={null}
{
  "valid": true,
  "next_step": "DOCUMENT_AI",
  "document_ai_status": "In Progress",
  "uploaded_document_keys": ["proof_of_funds"],
  "required_document_keys": ["proof_of_funds", "payslip"]
}
```

当 `required_document_keys` 中的每一项都出现在 `uploaded_document_keys` 中且没有未完成的证件时，该步骤即告完成（`next_step` 移过 `DOCUMENT_AI`）。

## 在 API 响应中的体现位置

`GET /v3/session/{sessionId}/decision/` 会在两个位置呈现 Document AI 的结果，无论是用户验证（KYC）还是企业验证（KYB）会话均适用 — 无论 `session_kind` 为何，`document_ai_documents[]` 数组和 PDF 报告均相同：

* **`features[]`** — 每个 Document AI 节点的摘要条目，用于枚举运行了哪些功能：

  ```json theme={null}
  { "features": [ { "feature": "DOCUMENT_AI", "node_id": "feature_document_ai_1" } ] }
  ```

* **`document_ai_documents[]`** — 完整结果，每个 Document AI 节点对应一组。每个组包含该节点的综合 `status`、已上传的 `items` 列表以及所有 `warnings`。每份上传的证件都是一个条目，包含您配置的字段（位于 `extracted_data` 下）、检测到的代码（位于 `detected_codes` 下）、其自身的 `status`、字段定义、取证 `document_metadata` 以及 `cross_check_result`。

各节点内各证件的状态会按照 **Declined > In Review > Approved** 的优先级合并为该节点的状态。

## 决策示例

对于配置了 `account_holder`（文本）、`balance`（数字）、`currency`（文本）和 `statement_date`（日期）的**资金证明**证件：

```json theme={null}
{
  "document_ai_documents": [
    {
      "node_id": "feature_document_ai_1",
      "status": "Approved",
      "items": [
        {
          "uuid": "5c1f0a2e-9b3d-4c7a-8f21-0a4e8e7d6c12",
          "document_key": "proof_of_funds",
          "status": "Approved",
          "original_filename": "statement.pdf",
          "extracted_data": {
            "account_holder": "Sophia Martinez",
            "balance": 18450.75,
            "currency": "EUR",
            "statement_date": "2026-05-31"
          },
          "detected_codes": [
            {
              "type": "QR_CODE",
              "page_number": 2,
              "position": [[124, 86], [306, 86], [306, 268], [124, 268]],
              "x": 124,
              "y": 86,
              "width": 182,
              "height": 182,
              "page_width": 1190,
              "page_height": 1684,
              "raw_payload": "SU5WLTIwMjYtMDA0Mg==",
              "parsed_payload": "INV-2026-0042"
            }
          ],
          "fields": [
            { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
            { "key": "balance", "name": "Balance", "type": "number", "required": false },
            { "key": "currency", "name": "Currency", "type": "text", "required": false },
            { "key": "statement_date", "name": "Statement date", "type": "date", "required": false }
          ],
          "document_metadata": { "is_tampered": false },
          "cross_check_result": null,
          "created_at": "2026-05-31T10:12:00Z"
        }
      ],
      "warnings": []
    }
  ]
}
```

`page_number` 从 1 开始。`position` 包含检测到的多边形，而 `x`、`y`、`width` 和 `height` 提供其边界框。所有坐标均使用渲染页面的像素空间，其尺寸为 `page_width` 和 `page_height`。当未找到受支持的代码时，`detected_codes` 为空数组。对于 `parsed_payload: null` 的条目，仅将其视为存在并记录了位置，而非已解码的值。

由于每个字段均可通过 `document_ai.<field_key>` 进行寻址，您可以直接根据 `extracted_data` 中的值驱动分支逻辑和[自定义状态规则](https://docs.didit.me/zh/core-technology/document-ai/warnings-document-ai.md) — 包括与其他步骤（例如 `kyc.full_name` 或问卷回答）进行交叉比对。


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