跳转到主要内容

概述

地址证明(POA)验证会在提取和取证分析期间检测到任何质量、真实性或匹配问题时,在 poa_verifications[].warnings[] 上发出警告。每个警告都是一个 feature 设置为 "PROOF_OF_ADDRESS" 的 Warning 对象。少数风险会始终强制为 Declined;其余风险则遵循在您的工作流中配置的针对每种风险的操作(DECLINE / REVIEW / NO_ACTION)。 以下各项风险均已针对生产决策流水线进行了核验;表格中逐字复现了准确的简短和详细描述字符串。
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。 FUTURE_ISSUE_DATE 也列在 AUTO_DECLINE_RISKS 中,但它在提取前验证中只有一个生成源(签发日期在未来超过 7 天),其错误仅会进入工作流重试循环:在该处表现为阻塞性上传错误,独立 API 从未生成该错误,并且不会写入 warnings[]。参见重试行为。

可配置警告

以下每项警告都跟随工作流 POA 节点上的一个操作开关(DECLINE / REVIEW / NO_ACTION)。警告的 log_type 与所配置的操作保持一致:拒绝对应 error,审核对应 warning,无操作对应 information。
所有姓名和地址不匹配共用一个操作: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 参考。

重试行为 (工作流会话)

在验证会话中,地址证明(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_on_document 以及 additional_names)进行评分,并保留得分最高的候选姓名。
  • 匹配阈值 — 默认的 poa_name_match_score_threshold 为 86;低于该分数将触发相关的 NAME_MISMATCH* 警告。
数值分数在报告中公开为 name_match_score_expected_details 和 name_match_score_id_verification(0–100)。即使未引发任何警告,这些分数值对于精细化人工审核也十分有用。

示例

覆盖层篡改 (默认拒绝)

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

姓名不匹配 (默认审核)

相关内容

警告类型

最后修改于 2026年11月7日