> ## 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. # 地址证明 API：POA 验证与 OCR | Didit > 通过 POST /v3/poa/ 验证水电费账单、银行对账单和租约。Didit 提供 OCR 地址提取、真伪检测，按次计费，无需签约。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/poa/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/poa/: post: tags: - Standalone APIs summary: 地址证明（证件 OCR + 地址核验） description: >- 单次调用即可提取并验证地址证明文件（公用事业账单、银行对账单以及政府签发的文件）。返回签发方、签发/到期日期、持有人姓名、原始地址与解析/地理编码后的地址、`Approved`/`Declined` `status`，以及解释所发现每项问题的 `warnings` 列表。 **延迟。**提取基于大语言模型（LLM）：典型调用耗时 **5–15 秒**，多页 PDF 最长约为 **30 秒**。请配置**至少 45 秒**的客户端超时时间，切勿在调用完成前重试。 **工作原理。**证件（图像或 PDF，最大 15 MB；加密 PDF 需要 `document_password`）将被分类为特定证件类型和子类型（例如 `UTILITY_BILL` / `WATER_BILL`），并利用基于 LLM 的提取技术提取签发方、日期、持有人姓名和地址。地址会被解析并进行地理编码存入 `poa_parsed_address`。PDF/EXIF 取证功能会筛查篡改情况（例如数字签名后的修改、已知的 PDF 编辑器、覆盖文本操作、可疑的重新导出），并提示 `SUSPECTED_DOCUMENT_MANIPULATION` 或 `DOCUMENT_METADATA_MISMATCH`。如果某个文本字段被清空并以另一种字体重新输入，而文件本身没有保留其内容是否发生更改的证据，则会提示 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`。证件时效将根据 `poa_document_age_months` 进行核验，语言将根据 `poa_languages_allowed` 进行核验。如果您传入了 `expected_address`、`expected_country` 或 `expected_first_name`/`expected_last_name`，系统将交叉比对提取的值并标记不匹配项。 **决策逻辑。**除非至少有一个警告导致拒绝，否则 `status` 为 `Approved`。硬性失败始终会导致拒绝：`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`，以及 `UNABLE_TO_EXTRACT_ISSUE_DATE` 和 `POA_NAME_NOT_DETECTED`（在此 endpoint 上不可配置）。五个风险组可通过 `poa_*_action` 选项针对每次请求单独配置（`DECLINE` 或 `NO_ACTION`，默认均为 `DECLINE`）。`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 和 `UNPARSABLE_OR_INVALID_ADDRESS` 在此 endpoint 上仅作为信息提示，绝不会导致拒绝。完全无法处理的证件返回 `400`；可读取但存在问题的证件返回 `200` 并附带 `status: "Declined"`：请务必检查 `poa.status` 和 `poa.warnings`，而不仅仅是 HTTP 状态码。 **计费。**每次 `200` 响应消耗一个地址证明 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付该调用时，endpoint 会在进行任何证件处理之前返回 `403` 及额度不足错误。 **会话持久化（`save_api_request`，默认为 `true`）。**当为 `true` 时，调用将作为 API 类型的会话持久化保存：它会显示在 Business Console 中，上传的证件会被存储，返回的 `request_id` 是真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`（该决策还会额外展示此响应中省略的 `document_file` 和 `document_metadata` 取证信息），并触发 `status.updated` Webhook 事件。当为 `false` 时，不会存储任何内容，且 `request_id` 是一次性关联 UUID，后续无法查询。 **沙盒。**沙盒 API 密钥会跳过所有处理和计费：在请求验证通过后（格式错误的输入仍返回 `400`），endpoint 返回静态的 `Approved` 模拟 payload（虚构的“Sandbox Power Co.”电费账单），不会持久化保存会话，也不消耗任何额度。 **认证。**在 `x-api-key` 请求头中发送您应用的 API 密钥。缺失或无效的凭据返回 `403`（`{"detail": "You do not have permission to perform this action."}`），此 API 绝不返回 `401`。 **速率限制。**所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。 注意：`FUTURE_ISSUE_DATE` 和 `POOR_DOCUMENT_QUALITY` 存在于工作流会话中，但此独立 endpoint 绝不会产生这两项警告：在此处，签发日期为未来的证件不会被自动拒绝。 operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- 地址证明文件。允许的扩展名：`tiff`、`jpg`、`jpeg`、`png`、`pdf`、`webp`。最大上传大小：**15 MB**（超出将返回 `400` 拒绝）。支持多页 PDF（延迟可能更高）；加密的 PDF 需要提供 `document_password`。图片在处理前会自动压缩。 document_password: type: string description: >- 当 `document` 为加密 PDF 时用于解密的密码。发送未附带（或附带错误）密码的加密 PDF 将返回 `400`。 writeOnly: true expected_address: type: string description: >- 用于与证件核对的地址。系统会对该地址进行地理编码并与提取出的地址进行比对；不匹配（或预期地址无法进行地理编码/验证）将添加 `ADDRESS_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 控制。地理编码后的形式将在 `expected_details_formatted_address` / `expected_details_parsed_address` 中回显。 example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- 用于与证件核验的国家/地区（ISO 3166-1 代码，例如 `ARG` 或 `AR`）。与证件国家/地区不匹配会添加 `POA_COUNTRY_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 控制。 example: ARG expected_first_name: type: string description: >- 用于与 `name_on_document` 进行核验的名（支持音译的模糊匹配）。低于匹配阈值的分数会添加 `NAME_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 管控。 example: Sophia expected_last_name: type: string description: >- 用于与 `name_on_document` 比对的姓氏，与 `expected_first_name` 结合以计算匹配分数。 example: Martinez poa_languages_allowed: type: string description: >- 以逗号分隔的所接受证件语言的 ISO 639-1 代码列表（例如 `en,es,fr`）。省略或为空时，接受**所有 51 种受支持的语言**。使用列表之外语言的证件会添加 `UNSUPPORTED_DOCUMENT_LANGUAGE`（由 `poa_unsupported_language_action` 控制）；列表中包含未知代码将返回 `400` 以及完整的受支持代码集。 example: en,es poa_document_age_months: type: string description: >- 以逗号分隔的 `key:value` 对，用于按证件类型设置最大证件月龄 — 键：`utility_bill`、`bank_statement`、`government_issued_document`、`other_poa_document`；值：`1`–`120`，或 `-1` 表示无限制（不进行时效检查）。缺省时的默认值：`utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`。超出期限的证件将以 `POA_DOCUMENT_EXPIRED` 拒绝。**注意：**提供此字段时，请列出您接受的*所有*类型 — 未列出的类型将被视为不接受（提示信息 `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`），并跳过其时效检查。 example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 已接受但**目前未应用**：姓名不匹配警告（`NAME_MISMATCH_WITH_PROVIDED`）将转而遵循 `poa_address_mismatch_action`。请设置 `poa_address_mismatch_action` 以同时控制姓名和地址的不匹配行为。 poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 遇到文件完整性问题时的处理操作：实际上该 endpoint 仅生成 `DOCUMENT_METADATA_MISMATCH`。 poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 当怀疑证件被篡改（`SUSPECTED_DOCUMENT_MANIPULATION`）时的处理操作，例如 PDF 在数字签名后被修改、经由已知 PDF 编辑器处理、存在覆盖文本篡改或 EXIF 日期不一致。同时控制 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`（文件无法证明其是否发生过更改的重新录入文本字段）：`DECLINE` 同样予以拒绝，`NO_ACTION` 将其保留为警告。 poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 当证件语言不在 `poa_languages_allowed` 范围内（`UNSUPPORTED_DOCUMENT_LANGUAGE`）时采取的操作。 poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- 当提取的详细信息与 `expected_*` 字段不一致时采取的操作：`ADDRESS_MISMATCH_WITH_PROVIDED`、`NAME_MISMATCH_WITH_PROVIDED` 和 `POA_COUNTRY_MISMATCH_WITH_PROVIDED` 均遵循此操作。 poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: 当无法在证件上识别出签发公司/组织时的处理操作（`ISSUER_NOT_IDENTIFIED`）。 save_api_request: type: boolean default: true description: >- 为 `true`（默认）时，将此次调用持久化为 API 类型的会话：在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，通过 `status.updated` Webhook 发出通知，并存储上传的证件。为 `false` 时，不存储任何内容，且 `request_id` 仅为用于关联响应的临时 UUID。 example: true vendor_data: type: string description: >- 可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。 example: user-123 metadata: type: object additionalProperties: true description: >- 与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={"flow":"onboarding"}`），它将被解析为对象。 example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- 证件已处理。`poa.status` 为 `Approved` 或 `Declined`；检测到的每个问题都在 `poa.warnings` 中逐项列出。过期、不匹配或可疑的证件仍会返回 `200` 并附带 `status: "Declined"` — 请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。 content: application/json: examples: Approved: summary: 水电费账单已清晰读取，不进行预期详细信息检查 value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA 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: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - 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: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: 签发日期早于允许的 `poa_document_age_months` value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` 与 `name_on_document` 不匹配 value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- 当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。 poa: type: object properties: status: type: string enum: - Approved - Declined description: >- 没有警告判定为拒绝时为 `Approved`；否则为 `Declined`，`warnings` 列表说明了具体原因。 issuing_state: type: string nullable: true description: 从证件中提取的证件签发国家/地区 — 通常为 ISO 3166-1 alpha-3（例如 `ARG`）。 example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- 检测到的证件类别。`UNKNOWN` 表示该证件无法归类为可接受的地址证明，并会自动拒绝并附带 `INVALID_DOCUMENT_TYPE`。绝不为 null，分类失败将回退为 `UNKNOWN`。 document_subtype: type: string description: >- `document_type` 内更细粒度的分类，例如 `ELECTRICITY_BILL`、`WATER_BILL`、`GAS_BILL`、`INTERNET_BILL`、`PHONE_BILL`（公共事业账单）；`ACCOUNT_STATEMENT`、`CREDIT_CARD_STATEMENT`（银行对账单）；`TAX_ASSESSMENT`、`RESIDENCY_CERTIFICATE`（政府证件）。无法确定子类型时为 `UNKNOWN`。绝不为 null，分类失败时回退到 `UNKNOWN`。 example: WATER_BILL document_language: type: string nullable: true description: 检测到的证件语言（ISO 639-1）。 example: es issuer: type: string nullable: true description: 签发证件的企业或机构。若为 `null` 则会添加 `ISSUER_NOT_IDENTIFIED`。 example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- 证件签发日期（`YYYY-MM-DD`）。无法提取时为 `null` — 在该 endpoint 上会以 `UNABLE_TO_EXTRACT_ISSUE_DATE` 拒绝。 example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- 证件上印刷的明确到期/有效日期（如存在）。独立于 `poa_document_age_months` 年限检查。 poa_address: type: string nullable: true description: >- 与证件上印刷完全一致的地址。`null` 会自动拒绝并提示 `MISSING_ADDRESS_INFORMATION`。 poa_formatted_address: type: string nullable: true description: '`poa_address` 经过地理编码与规范化后的版本。' example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: 证件地址的结构化、经地理编码的细分。当地址无法解析时为 `null`。 properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: ISO 3166-1 alpha-2 国家/地区代码。 example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: 证件地址的地理编码坐标。 expected_details_address: type: string nullable: true description: 您发送的 `expected_address` 回显，或 `null`。 expected_details_formatted_address: type: string nullable: true description: '`expected_address` 的地理编码规范化版本；未提供或无法进行地理编码时为 `null`。' expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- `expected_address` 的完整地理编码结果（街道/城市/地区/国家/地区/邮政编码加上原始地理编码器输出以及 `is_verified` 标志）。未提供 `expected_address` 时为 `null`。 name_on_document: type: string nullable: true description: >- 从证件中提取的主要持有人姓名；若提供了 `expected_first_name`/`expected_last_name`，则会与其进行比对。在此 endpoint 上，为 `null` 时会因 `POA_NAME_NOT_DETECTED` 而拒绝。 example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: 证件特定的附加信息。银行字段在银行对账单上印有相应信息时填充；否则为 `null`。 properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: 证件上印有的联系电话号码。 additional_names: type: array items: type: string description: 在证件上找到的其他持有人姓名（例如联名账户持有人、原账户名称）。 warnings: type: array description: >- 完全通过审核时为空。每个条目说明一项检测到的风险；包含 `log_type: "error"` 的条目会将 `status` 设置为 `Declined`。 items: type: object properties: risk: type: string description: >- 机器可读的风险代码。始终拒绝：`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`，以及 `UNABLE_TO_EXTRACT_ISSUE_DATE` 和 `POA_NAME_NOT_DETECTED`（在此 endpoint 上固定为拒绝）。由请求选项控制：`NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED`（`poa_address_mismatch_action`）、`POOR_DOCUMENT_QUALITY`（此 endpoint 从不生成）/ `DOCUMENT_METADATA_MISMATCH`（`poa_document_issues_action`）、`SUSPECTED_DOCUMENT_MANIPULATION` 和 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`（`poa_document_authenticity_action`）、`UNSUPPORTED_DOCUMENT_LANGUAGE`（`poa_unsupported_language_action`）、`ISSUER_NOT_IDENTIFIED`（`poa_issuer_not_identified_action`）。在此 endpoint 上仅供参考：`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`、`UNPARSABLE_OR_INVALID_ADDRESS`。 example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: 引发该警告的功能。在此 endpoint 上始终为 `PROOF_OF_ADDRESS`。 additional_data: type: object nullable: true additionalProperties: true description: >- 某些风险的额外上下文信息，例如 `POA_DOCUMENT_EXPIRED` 包含 `expiration_reason`（`printed_expiration` 或 `age_window`）、`document_type`、`document_subtype` 和 `issue_date`，此外在 `printed_expiration` 路径下包含 `expiration_date`，在 `age_window` 路径下包含 `max_age_months`；`SUSPECTED_DOCUMENT_MANIPULATION` 包含 `reason` 和 `detection_method`；`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` 包含 `reason`、`detection_method`（`unproven_text_replacement`）、`replaced_text`、`manipulated_regions` 和 `manipulated_blocks`。对大多数风险为 `null`。 log_type: type: string enum: - error - information description: >- 严重程度。`error` 警告会导致 `status` 变为 `Declined`；`information` 条目仅供参考，本身绝不会导致拒绝。（此 endpoint 不会产生 `warning`，其选项仅接受 `DECLINE` 或 `NO_ACTION`。） short_description: type: string description: 易于阅读的单行风险摘要。 long_description: type: string description: 风险的便于人类阅读的说明。 detected_codes: type: array description: >- 在证件的所有已处理页面中检测到的二维码和条形码。如果未找到任何码则为空。已定位但无法解码的二维码其 `parsed_payload: null`。 items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: 您发送的 `vendor_data` 回显，或 `null`。 metadata: type: object nullable: true additionalProperties: true description: 您发送的 `metadata` 对象回显，或 `null`。 created_at: type: string format: date-time description: 响应生成时的 ISO 8601 时间戳（UTC）。 '400': description: >- 验证或处理错误。字段级问题返回 DRF 的标准外层结构（每个出错字段对应一个消息数组）。加密 PDF 问题返回 `{"detail": ...}`。提取流水线无法处理的证件返回 `{"error": ["Error extracting POA information"]}`。 content: application/json: examples: Missing document: summary: 表单数据中未包含 `document` value: document: - No file was submitted. Unsupported file extension: summary: 文件扩展名不在 tiff/jpg/jpeg/png/pdf/webp 范围内 value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: 上传内容超过 15 MB 限制 value: document: - File size should not exceed 15 MB Encrypted PDF: summary: 上传的 PDF 未提供所需密码 value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` 无法解密 PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` 包含不受支持的代码' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: '`poa_document_age_months` 的值超出 1–120 / -1 范围' value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: 提取流水线无法处理该证件 value: error: - Error extracting POA information '403': description: >- 权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{"detail": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何证件处理之前返回 `403` 及 `{"error": ...}`。 content: application/json: examples: Missing or invalid API key: summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销 value: detail: You do not have permission to perform this action. Not enough credits: summary: 组织余额不足以支付本次调用 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。 content: application/json: examples: Write rate limit exceeded: summary: 当前分钟内的写入请求超过 300 次 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: 检测到的符号系统，例如 `QR_CODE`、`CODE_128`、`EAN_13`、`DATA_MATRIX` 或 `PDF_417`。 page_number: type: integer minimum: 1 description: 从 1 开始的页码。 position: type: array nullable: true description: 在渲染页面的像素坐标中检测到的多边形。当没有可靠的位置可用时为 `null`。 items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: 边界框的左边缘（以渲染页面的像素为单位）。 'y': type: integer nullable: true description: 边界框的顶部边缘（以渲染页面像素为单位）。 width: type: integer nullable: true description: 渲染页面像素中的边界框宽度。 height: type: integer nullable: true description: 渲染页面像素中的边界框高度。 page_width: type: integer description: 渲染页面的宽度（以像素为单位）。 page_height: type: integer description: 渲染页面的高度（以像素为单位）。 raw_payload: type: string description: 原始解码器 payload（base64 字符串形式，如可用）；否则为空字符串。 parsed_payload: nullable: true description: 解码后的字符串或结构化值。当定位到代码但无法解码时为 `null`。 responses: DocumentProcessingBusy: description: >- 当前正在处理的证件过多，因此本次上传未被处理：未存储任何内容，且未消耗尝试次数。请在 `Retry-After` 指定的秒数后再次发送相同文件。请根据 `code` 进行分支判断，而非根据消息文本。 headers: Retry-After: description: 再次发送相同请求前需等待的秒数。 schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.