> ## 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 地址证明警告代码汇总：包含姓名不匹配、证件过期、元数据异常及不支持的类型等。支持针对各项警告配置自动拒绝规则。

## 概述

地址证明（POA）验证会在提取和取证分析期间检测到任何质量、真实性或匹配问题时，在 `poa_verifications[].warnings[]` 上发出警告。每个警告都是一个 `feature` 设置为 `"PROOF_OF_ADDRESS"` 的 [Warning 对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)。少数风险会始终强制为 `Declined`；其余风险则遵循在您的工作流中配置的针对每种风险的操作（`DECLINE` / `REVIEW` / `NO_ACTION`）。

以下各项风险均已针对生产决策流水线进行了核验；表格中逐字复现了准确的简短和详细描述字符串。

> [!NOTE]
>
> POA 提取会给每份证件带来 **5–15 秒**的延迟。仅当工作流步骤完成时才会写入警告；轮询频率切勿快于每 5 秒一次。

## 两种生产路径

POA 警告通过两种不同的路径生成，它们之间的风险集合有所不同：

* **工作流会话**（验证会话内的 POA 步骤）：上传 endpoint 首先运行带有重试循环的阻塞性验证（参见[重试行为](#重试行为-工作流会话)），然后最终存储的警告由 `check_poa_risks` 以及多证件姓名核验计算得出。
* **独立 API**（`POST /v3/poa/`）：警告仅来自 `check_poa_risks`。没有重试循环、没有已验证证件上下文且只有一份证件，因此独立 API **从未**生成 `NAME_MISMATCH_ID_VERIFICATION`、`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`、`POA_MAX_ATTEMPTS_EXCEEDED` 和 `FUTURE_ISSUE_DATE`。提取前验证错误在此路径上会被丢弃。

`POOR_DOCUMENT_QUALITY` 在风险枚举中定义并保留在操作映射中，但 **POA 流水线中没有任何代码路径会生成它**：它从未在任一路径的 `warnings[]` 中出现过。请勿针对其编写分支逻辑。

## 自动拒绝警告 (始终强制为 `Declined`)

这些风险属于 `AUTO_DECLINE_RISKS`；记录后，无论配置如何，POA 状态均为 `Declined`，且 `log_type` 始终为 `error`。

| 风险 | 原因 | 建议的补救措施 |
| - | - | - |
| `MISSING_ADDRESS_INFORMATION` | 无法从证件中提取到地址。 | 要求用户重新提交清晰显示其地址的证件。 |
| `POA_DOCUMENT_EXPIRED` | 证件通过以下两种路径之一判定为已过期：其**印刷的到期日期**已过，或者其**存在时间超过了该类型配置的最大证件年限**。默认值：`UTILITY_BILL` 和 `BANK_STATEMENT` 为 **3 个月**，`GOVERNMENT_ISSUED_DOCUMENT` 和 `OTHER_POA_DOCUMENT` 为 **12 个月**（一个月按 30 天计算；`-1` 会禁用该核验）。`additional_data` 始终包含 `expiration_reason`（`printed_expiration` 或 `age_window`）、`document_type`、`document_subtype` 和 `issue_date`；`printed_expiration` 路径会添加 `expiration_date`，而 `age_window` 路径会添加 `max_age_months`。 | 要求用户提供有效或较新的证件，或者提高该类型的 `age_months`。 |
| `INVALID_DOCUMENT_TYPE` | 证件无法归类为任何受支持的 POA 类型（`document_type` 会回退至 `UNKNOWN`）。 | 要求用户重新提交；检查文件是否损坏。 |
| `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | 证件年龄核验本身失败（根据签发日期计算到期日期时出错）。 | 要求用户提供签发日期清晰可读的证件。 |

`FUTURE_ISSUE_DATE` 也列在 `AUTO_DECLINE_RISKS` 中，但它在提取前验证中只有一个生成源（签发日期在未来超过 7 天），其错误仅会进入**工作流重试循环**：在该处表现为阻塞性上传错误，独立 API 从未生成该错误，并且不会写入 `warnings[]`。参见[重试行为](#重试行为-工作流会话)。

## 可配置警告

以下每项警告都跟随工作流 POA 节点上的一个操作开关（`DECLINE` / `REVIEW` / `NO_ACTION`）。警告的 `log_type` 与所配置的操作保持一致：拒绝对应 `error`，审核对应 `warning`，无操作对应 `information`。

| 风险 | 原因 | 操作开关 | 默认值 |
| - | - | - | - |
| `NAME_MISMATCH_WITH_PROVIDED` | 证件上的姓名与创建会话时提供的姓名（`expected_details`）相比，分数低于 `poa_name_match_score_threshold`（默认值为 86）。 | `poa_name_or_address_mismatch_action` | 审核 |
| `NAME_MISMATCH_ID_VERIFICATION` | 证件上的姓名与已核验的身份证件相比，分数低于阈值。`additional_data`：`{ poa_name, kyc_name, match_score }`。仅适用于工作流会话。 | `poa_name_or_address_mismatch_action` | 审核 |
| `ADDRESS_MISMATCH_WITH_PROVIDED` | 提取出的地址与通过 API 提供的地址不一致，或两个地址中任一无法验证为住宅地址。 | `poa_name_or_address_mismatch_action` | 审核 |
| `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | 证件的国家/地区与通过 API 提供的国家/地区不一致（已按 ISO-3 标准化）。`additional_data`：`{ expected_country, extracted_country }`。 | `poa_name_or_address_mismatch_action` | 审核 |
| `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | 同一会话中的两份或多份 POA 证件带有不同的姓名。`additional_data` 包含两个节点 ID、两个姓名以及匹配分数。仅适用于工作流会话。 | `poa_name_or_address_mismatch_action` | 审核 |
| `DOCUMENT_METADATA_MISMATCH` | 文件为空（`file_size` 为 0），或其 EXIF 日期格式有误。 | `poa_document_issues_action` | 审核 |
| `SUSPECTED_DOCUMENT_MANIPULATION` | 取证分析发现篡改证据：数字签名后被修改（`is_tampered`）、叠加文本被篡改（附带 `additional_data.manipulated_regions` 矩形区域）、已知的 PDF 编辑器、EXIF 日期不一致，或可疑的重新导出。`additional_data.detection_method` 标明触发的检查项。 | `poa_document_authenticity_action` | **拒绝** |
| `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | 某文本字段被清空并以另一种字体重新输入，而文件中没有证据表明其内容是否发生变化：在线编辑器也会重新输入未改动的文本。此警告本身从不单独触发 `SUSPECTED_DOCUMENT_MANIPULATION`；若同一证件上的其他信号触发了它，则以两者中较严格的操作为准。`additional_data.detection_method` 为 `unproven_text_replacement`，并包含 `replaced_text` 和 `manipulated_regions`。若文件未能完整检查，同样会触发此警告，因为未检查的部分可能包含此类字段：此时 `detection_method` 为 `analysis_incomplete`，除非在已检查的部分中发现了字段，否则 `replaced_text` 和 `manipulated_regions` 为空。 | `poa_document_unproven_text_replacement_action` | 审核 |
| `UNSUPPORTED_DOCUMENT_LANGUAGE` | 证件的语言不在 `poa_languages_allowed` 中。 | `poa_unsupported_language_action` | **拒绝** |
| `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 检测到的证件类型未在该证件所属国家/地区的 `poa_documents_allowed` 中启用，或其子类型被明确禁用。 | `poa_unsupported_document_type_action` | **拒绝** |
| `ISSUER_NOT_IDENTIFIED` | 无法从证件中识别出签发机构。 | `poa_issuer_not_identified_action` | 审核 |
| `UNABLE_TO_EXTRACT_ISSUE_DATE` | 证件上找不到有效的签发日期。 | `poa_issue_date_not_detected_action` | 审核 |
| `POA_NAME_NOT_DETECTED` | 证件上未检测到姓名。 | `poa_issue_date_not_detected_action`（共用开关） | 审核 |
| `UNPARSABLE_OR_INVALID_ADDRESS` | 已提取出地址，但无法解析并地理编码为有效的住宅地址。 | `poa_unparsable_or_invalid_address_action` | 审核 |
| `POA_MAX_ATTEMPTS_EXCEEDED` | 用户在工作流重试循环中耗尽了 `poa_max_retry_attempts`（默认值为 2）。`additional_data`：`{ attempts }`。仅适用于工作流会话。 | `poa_max_attempts_exceeded_action` | **拒绝** |

> [!NOTE]
>
> 所有姓名和地址不匹配共用**一个操作**：`poa_name_or_address_mismatch_action` 涵盖两种姓名风险、两种地址风险以及跨证件姓名检查，您无法分别配置姓名和地址不匹配的处理方式。在独立 API 上，同一组由 `poa_address_mismatch_action` 请求选项控制（`poa_name_mismatch_action` 选项虽可接受，但从不被读取）。

## 独立 API 差异 (`POST /v3/poa/`)

独立 endpoint 构建了相同的风险到操作映射，但其请求级选项仅接受 `DECLINE` 或 `NO_ACTION`（全部默认为 `DECLINE`）：

* 在此 endpoint 上，`UNABLE_TO_EXTRACT_ISSUE_DATE` 和 `POA_NAME_NOT_DETECTED` **硬编码为拒绝**。
* `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 和 `UNPARSABLE_OR_INVALID_ADDRESS` 在此为**信息性警告**：其操作默认为不执行，且不可按请求进行配置。
* 从不产生 `FUTURE_ISSUE_DATE`、`POOR_DOCUMENT_QUALITY`、`NAME_MISMATCH_ID_VERIFICATION`、`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` 和 `POA_MAX_ATTEMPTS_EXCEEDED`：在此 endpoint 上，日期在未来的证件**不会**被自动拒绝。

有关请求选项，请参阅 [POST /v3/poa/ API 参考](https://docs.didit.me/zh/standalone-apis/proof-of-address.md)。

## 重试行为 (工作流会话)

在验证会话中，地址证明（POA）上传步骤会在接受证件之前运行阻塞式验证。当检测到阻塞性错误 — `INVALID_DOCUMENT_TYPE`、`UNABLE_TO_EXTRACT_ISSUE_DATE`、`FUTURE_ISSUE_DATE`、`POA_NAME_NOT_DETECTED`、`MISSING_ADDRESS_INFORMATION`、`POA_COUNTRY_MISMATCH_WITH_PROVIDED`、`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`、`UNSUPPORTED_DOCUMENT_LANGUAGE` 或 `POA_DOCUMENT_EXPIRED` — 上传将被拒绝并返回 `400`，同时将风险代码作为消息返回，用户可以尝试使用更合适的证件重新提交。

对于 `POA_DOCUMENT_EXPIRED`，`400` 响应体还会包含 `expiration_reason`（`printed_expiration` 或 `age_window`），以便您的 UI 显示准确的原因；在 `age_window` 路径下，它还会额外包含 `max_age_months`。在 `printed_expiration` 路径下，`max_age_months` 会被有意省略，因为该证件是由于其上打印的到期日期而被拒绝，而非由于时效窗口限制。

一旦用户用尽了 `poa_max_retry_attempts` 次尝试（默认为 2 次，可配置为 2–5 次），提交仍会被接受：系统会根据保存的证件重新计算存储的警告，追加 `POA_MAX_ATTEMPTS_EXCEEDED`，并根据完整的风险集合得出最终状态。因此，`FUTURE_ISSUE_DATE` 会阻止上传，却永远不会出现在 `warnings[]` 中。

## 可配置设置

工作流的 POA 节点公开了以下配置项（与 `VerificationSettings` 字段对应）：

| 设置 | 控制项 | 默认值 |
| - | - | - |
| `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`、`NAME_MISMATCH_ID_VERIFICATION`、`ADDRESS_MISMATCH_WITH_PROVIDED`、`POA_COUNTRY_MISMATCH_WITH_PROVIDED`、`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | 审核 |
| `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | 审核 |
| `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | 拒绝 |
| `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | 审核（从不审核的工作流在其自身的 `poa_document_authenticity_action` 为拒绝时使用该操作，否则为不操作；独立 API 则遵循请求中的 `poa_document_authenticity_action`） |
| `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | 拒绝 |
| `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 拒绝 |
| `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | 审核 |
| `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`、`POA_NAME_NOT_DETECTED` | 审核 |
| `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | 审核 |
| `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | 拒绝 |
| `poa_documents_allowed` | 按国家/地区接受的证件类型，每种类型包含 `enabled` 和 `age_months`（`-1` = 无限制）；可通过 `document_subtypes_config` 按子类型进行覆盖配置。 | 水电费账单和银行对账单：3 个月；政府签发及其他：12 个月 |
| `poa_languages_allowed` | 接受的证件语言。 | 所有支持的语言 |
| `poa_name_match_score_threshold` | 触发 `NAME_MISMATCH*` 风险之前的最低姓名匹配分数（0–100）。 | 86 |
| `poa_max_retry_attempts` | 重试循环放弃之前的上传尝试次数（2–5）。 | 2 |

## 姓名匹配逻辑

POA 姓名匹配容许常见的变化形式：

* **中间名和首字母缩写**采用宽容匹配（允许存在或缺失）。
* **候选姓名** — 对证件上检测到的每个姓名（`name_on_document` 以及 `additional_names`）进行评分，并保留得分最高的候选姓名。
* **匹配阈值** — 默认的 `poa_name_match_score_threshold` 为 **86**；低于该分数将触发相关的 `NAME_MISMATCH*` 警告。

数值分数在报告中公开为 `name_match_score_expected_details` 和 `name_match_score_id_verification`（0–100）。即使未引发任何警告，这些分数值对于精细化人工审核也十分有用。

## 示例

### 覆盖层篡改 (默认拒绝)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
      "additional_data": {
        "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
        "detection_method": "overlay_text_manipulation",
        "signals": ["duplicate_font_subset", "glyph_fragmentation"],
        "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
        "fragmented_fonts": [],
        "manipulated_regions": [
          { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
        ]
      },
      "log_type": "error",
      "short_description": "Suspected document manipulation",
      "long_description": "The system detected signs of potential document manipulation or editing.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### 过期证件 + 缺失地址 (自动拒绝)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "POA_DOCUMENT_EXPIRED",
      "additional_data": {
        "expiration_reason": "age_window",
        "max_age_months": 3,
        "document_subtype": "ELECTRICITY_BILL",
        "document_type": "UTILITY_BILL",
        "issue_date": "2025-11-02"
      },
      "log_type": "error",
      "short_description": "Document expired",
      "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.",
      "node_id": "feature_poa_1"
    },
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "MISSING_ADDRESS_INFORMATION",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Missing address information",
      "long_description": "The document does not contain complete or clear address information that can be extracted.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### 姓名不匹配 (默认审核)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "NAME_MISMATCH_ID_VERIFICATION",
      "additional_data": {
        "poa_name": "JOHN B SMYTH",
        "kyc_name": "John A. Smith",
        "match_score": 60
      },
      "log_type": "warning",
      "short_description": "Name mismatch with ID verification",
      "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

## 相关内容

* [地址证明报告](https://docs.didit.me/zh/core-technology/proof-of-address/report-proof-of-address.md) — 完整响应格式、覆盖层篡改取证分析、状态语义
* [地址证明概述](https://docs.didit.me/zh/core-technology/proof-of-address/overview.md) — 接受的证件类型
* [数据模型 — 地址证明](https://docs.didit.me/zh/reference/data-models.md#地址证明) — 规范模式和警告对象
* [Webhooks](https://docs.didit.me/zh/integration/webhooks.md) — `status.updated` 携带 POA 警告

### 警告类型


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