> ## 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 地址证明报告：涵盖提取的地址、证件类型、签发方、日期、姓名匹配分数、PDF 叠加篡改证据及各类警告信息。 ## 概述 地址证明（POA）验证支持单个不超过 15 MB 的 PDF 或图片（TIFF、JPG、JPEG、PNG、WEBP，可选 ZIP 压缩），执行文件类型分类、基于 LLM 的提取以及 PDF/EXIF 取证分析，并返回： * **提取的地址** — 包含原始地址和结构化地址（`street_1`、`city`、`region`、`postal_code`、经纬度）。 * **文件元数据** — 文件大小、内容类型、创建和修改日期、EXIF 日期、签名信息以及来自 PDF 取证分析的任何叠加层篡改证据。 * 与已验证的身份证件以及创建会话时提供的预期信息之间的**姓名匹配分数**。 * 当文件为银行对账单时的**银行相关额外字段**（账号、IBAN、排序代码、路由号码、SWIFT/BIC、分支）。 ![显示提取的地址字段和文件类型的 Didit 地址证明报告屏幕截图](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/proof-of-address-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=099d1bd6cf0c215cc93c3a504b8aa9ee) > [!NOTE] > > POA 提取会执行非结构化文本读取，这会导致每个文件产生 **5–15 秒**的延迟。只有在整个工作流步骤完成后才会触发 Webhook — 在此时间窗口内，调用决策 endpoint 的频率请勿高于每 5 秒一次。 ## 在 API 响应中的位置 决策 endpoint 在 `GET /v3/session/{sessionId}/decision/` 中以复数数组 **`poa_verifications[]`** 的形式返回 POA。每个条目代表工作流中 POA 节点的一次执行；包含多个 POA 步骤（例如银行对账单 + 水电费账单）的会话会为每次执行生成一个条目，并带有各自的 `node_id`。 ```text theme={null} GET /v3/session/{sessionId}/decision/ ──▶ { "poa_verifications": [ { node_id, status, document_type, poa_address, … }, … ] } ``` 下方的结构与规范数据结构一致 — 请参阅[数据模型](https://docs.didit.me/zh/reference/data-models.md#地址证明)。 ## 数据结构 有关规范数据结构，请参阅[数据模型参考中的地址证明](https://docs.didit.me/zh/reference/data-models.md#地址证明)。 ```typescript theme={null} interface POAV3 { status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review'; node_id: string | null; issuing_state: string | null; // ISO 3166-1 alpha-3 document_type: // never null — falls back to 'UNKNOWN' | 'UTILITY_BILL' | 'BANK_STATEMENT' | 'GOVERNMENT_ISSUED_DOCUMENT' | 'OTHER_POA_DOCUMENT' | 'UNKNOWN'; document_subtype: string; // e.g. 'ELECTRICITY_BILL', 'ACCOUNT_STATEMENT'; // never null — falls back to 'UNKNOWN' issuer: string | null; issue_date: string | null; // YYYY-MM-DD expiration_date: string | null; // YYYY-MM-DD when present // Extracted address poa_address: string | null; // raw, single-line poa_formatted_address: string | null; // geocoded/formatted poa_parsed_address: { address_type?: string; street_1?: string; street_2?: string; city?: string; region?: string; postal_code?: string; country?: string; // ISO 3166-1 alpha-2 raw_results?: object; document_location?: { latitude: number; longitude: number }; } | null; document_file: string | null; // presigned URL, expires after ~4 hours document_language: string | null; // ISO 639-1, e.g. 'en' name_on_document: string | null; // Expected details (when supplied at session creation) expected_details_address: string | null; expected_details_formatted_address: string | null; expected_details_parsed_address: object | null; // Match scores (float, 0-100) name_match_score_expected_details: number | null; name_match_score_id_verification: number | null; // PDF + image forensics document_metadata: { file_size: number | null; content_type: string | null; creation_date: string | null; modified_date: string | null; creator: string | null; producer: string | null; software: string | null; encryption: string | null; is_signed: boolean | null; is_tampered: boolean | null; signature_info: object | null; exif_original_date: string | null; exif_digitized_date: string | null; processed_by_known_editor: boolean | string | null; has_different_creation_mod_date: boolean | null; overlay_manipulation: { detected: boolean; analyzed: boolean; signals: string[]; // 'duplicate_font_subset', 'glyph_fragmentation' duplicate_font_subsets: object[]; fragmented_fonts: object[]; manipulated_regions: { page: number; x: number; y: number; width: number; height: number; page_width: number; page_height: number; }[]; } | null; // null for non-PDF uploads or when not analyzed } | null; // Bank-related and custom fields extra_fields: { bank_account_number: string | null; bank_iban: string | null; bank_sort_code: string | null; bank_routing_number: string | null; bank_swift_bic: string | null; bank_branch_name: string | null; bank_branch_address: string | null; document_phone_number: string | null; additional_names: string[]; [customField: string]: unknown; }; extra_files: string[]; // presigned URLs for additional uploaded files // QR codes and barcodes detected_codes: { type: string; // 'QR_CODE', 'CODE_128', 'EAN_13', 'DATA_MATRIX', 'PDF_417', … page_number: number; // 1-based position: [number, number][] | null; x: number | null; y: number | null; width: number | null; height: number | null; page_width: number; page_height: number; raw_payload: string; // base64, empty string when unavailable parsed_payload: unknown | null; // null when located but undecodable }[]; warnings: Warning[]; // see Data Models — Warning object } ``` `warnings[]` 中的每个条目都是一个[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)：`{ feature, risk, additional_data, log_type, short_description, long_description, node_id }`，对于此报告，`feature` 始终为 `"PROOF_OF_ADDRESS"`。 ## 状态值 `status` 使用功能级状态枚举（`FeatureStatusChoices`）。 | 值 | 含义 | | - | - | | `Not Finished` | 该会话的 POA 节点尚未完成（默认状态）。 | | `Approved` | 文件解析正常，且没有警告触发拒绝或审核。 | | `In Review` | 针对您工作流的至少一个可配置警告被设为**审核**（且没有任何拒绝项）。 | | `Declined` | 触发了硬性拒绝警告（`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`），或者针对您工作流的某个可配置警告被设为**拒绝**。 | 在工作流节点上配置的自定义状态规则可以进一步调整计算得出的状态；规则按优先级 Declined > In Review > Approved 组合生效。完整风险到操作的映射关系（包括仅限工作流的 `FUTURE_ISSUE_DATE` 重试行为），请参阅[地址证明警告](https://docs.didit.me/zh/core-technology/proof-of-address/warnings-proof-of-address.md)。 ## PDF 叠加篡改证据 当提交的文件为 PDF 时，`document_metadata.overlay_manipulation` 可能包含疑似文字叠加的取证证据： * `detected`：检查发现篡改证据时为 `true`。 * `analyzed`：PDF 能够被分析时为 `true`。 * `analysis_incomplete`：仅当文件无法完整检查时存在且为 `true`。已检查的部分在可能的范围内保留其检查结果，同时文档会触发 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`。 * `signals`：触发的检查项（`duplicate_font_subset`、`glyph_fragmentation`）。 * `manipulated_regions`：围绕疑似被编辑文字的页面坐标矩形。每个矩形使用 PDF 页面坐标空间（`x`、`y`、`width`、`height`、`page_width`、`page_height`），便于审核人员在 PDF 预览中标出受影响的区域。 当文件不是 PDF，或 PDF 无法分析时，该字段为 `null`。当 `detected=true` 时，系统还会发出 `SUSPECTED_DOCUMENT_MANIPULATION` 警告，其 `additional_data` 与上述信号和矩形信息保持一致。但如果存在更强的信号（数字签名后被修改，即 `is_tampered=true`），则优先采用该信号，此时 `additional_data` 描述的是签名篡改情况。 ## 二维码与条形码 每份 POA 报告都包含 `detected_codes`，涵盖所有已处理的页面。每个条目包含： | 字段 | 描述 | | - | - | | `type` | 检测到的码制，例如 `QR_CODE`、`CODE_128`、`EAN_13`、`DATA_MATRIX` 或 `PDF_417` | | `page_number` | 从 1 开始的页码 | | `position` | 渲染页面像素坐标中的检测多边形，无法获得可靠位置时为 `null` | | `x`, `y`, `width`, `height` | 渲染页面像素坐标中的边界框，无法获得可靠位置时为 `null` | | `page_width`, `page_height` | 坐标所使用的渲染页面尺寸 | | `parsed_payload` | 解码后的字符串或结构化值，在只能定位码时为 `null` | | `raw_payload` | 可用时的原始解码器 payload（Base64 字符串）；否则为空字符串 | 未找到受支持的码时，`detected_codes` 为空数组。Didit 绝不对 payload 进行猜测：损坏或无法读取的码可能会连同其位置一起返回，且 `parsed_payload: null`，而码检测失败并不会导致 POA 验证失败。 ## 示例 ### 已通过 — 银行对账单 ```json theme={null} { "poa_verifications": [ { "status": "Approved", "node_id": "feature_poa_1", "issuing_state": "USA", "document_type": "BANK_STATEMENT", "document_subtype": "ACCOUNT_STATEMENT", "issuer": "National Bank", "issue_date": "2026-04-15", "expiration_date": null, "document_language": "en", "name_on_document": "John A. Smith", "poa_address": "123 Main St, Apartment 4B, New York, NY 10001", "poa_formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA", "poa_parsed_address": { "address_type": "Street", "street_1": "123 Main St", "street_2": "Apartment 4B", "city": "New York", "region": "NY", "postal_code": "10001", "country": "US", "document_location": { "latitude": 40.7128, "longitude": -74.0060 } }, "document_file": "https:///.../poa.pdf?X-Amz-Expires=14400", "document_metadata": { "file_size": 246810, "content_type": "application/pdf", "creation_date": "2026-04-15", "modified_date": "2026-04-15", "creator": "PDFKit", "producer": "Quartz", "software": null, "encryption": null, "is_signed": false, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": null }, "name_match_score_expected_details": 100, "name_match_score_id_verification": 98, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "extra_fields": { "bank_account_number": "****1234", "bank_iban": null, "bank_sort_code": null, "bank_routing_number": "021000089", "bank_swift_bic": "NABNUS33", "bank_branch_name": "Manhattan Midtown", "bank_branch_address": "111 Wall St, New York, NY", "document_phone_number": null, "additional_names": [] }, "extra_files": [], "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9uYXRpb25hbGJhbmsuZXhhbXBsZS9zdG10Lzk5ODE=", "parsed_payload": "https://nationalbank.example/stmt/9981" }, { "type": "CODE_128", "page_number": 1, "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDAxMjM0NTY3ODk=", "parsed_payload": "001234567 89" } ], "warnings": [] } ] } ``` ### 已拒绝 — 叠加层篡改与姓名不匹配 ```json theme={null} { "poa_verifications": [ { "status": "Declined", "node_id": "feature_poa_1", "issuing_state": "GBR", "document_type": "UTILITY_BILL", "document_subtype": "ELECTRICITY_BILL", "issuer": "BritishEnergy", "issue_date": "2026-03-10", "expiration_date": null, "document_language": "en", "name_on_document": "JOHN B SMYTH", "poa_address": "44 King's Road, London, SW3 4UD", "poa_formatted_address": "44 King's Road, London, SW3 4UD, United Kingdom", "poa_parsed_address": { "street_1": "44 King's Road", "city": "London", "postal_code": "SW3 4UD", "country": "GB", "document_location": { "latitude": 51.4880, "longitude": -0.1690 } }, "document_file": "https:///.../poa.pdf?X-Amz-Expires=14400", "document_metadata": { "file_size": 412910, "content_type": "application/pdf", "creation_date": "2026-03-10", "modified_date": "2026-05-12", "creator": "Adobe Acrobat Pro", "producer": "Adobe PDF Library", "software": "Adobe Acrobat", "encryption": null, "is_signed": false, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": true, "overlay_manipulation": { "detected": true, "analyzed": true, "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 } ] } }, "name_match_score_expected_details": 62, "name_match_score_id_verification": 60, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [] }, "extra_files": [], "detected_codes": [], "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" }, { "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/warnings-proof-of-address.md) — POA 可能发出的所有警告代码 * [地址证明概述](https://docs.didit.me/zh/core-technology/proof-of-address/overview.md) — 支持的文件类型与验证规则 * [数据模型 — 地址证明](https://docs.didit.me/zh/reference/data-models.md#地址证明) — 规范数据结构 * [Webhook](https://docs.didit.me/zh/integration/webhooks.md) — `status.updated` 携带 POA payload > [!NOTE] > > `document_file` 和 `extra_files[]` 为预签名 URL，有效期约为 4 小时。如需刷新 URL，请重新调用决策 endpoint。仅在自身系统中存储验证状态和解析后的地址字段 — 尽量减少留存的文件数据。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.