> ## 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：证件 OCR 与真伪鉴别 > Didit 支持 220+ 国家和地区、14,000+ 种证件的身份验证，涵盖真伪鉴别、OCR、MRZ，推理耗时低于 2 秒，按量付费，无需签订合同。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/id-verification/ 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/id-verification/: post: tags: - Standalone APIs summary: 身份证件验证（证件 OCR + 欺诈检查） description: >- 一次调用即可完成身份证件的 OCR 并运行证件防伪检查，返回提取的持有人字段、解析后的 MRZ、`Approved`/`Declined`/`In Review` 的 `status`，以及说明所发现每个问题的 `warnings` 列表。支持来自 220+ 个国家/地区的 14,000+ 种证件类型。 **工作原理。** 发送证件的 `front_image`（必填）；对于双面证件，还需发送 `back_image`。上传证件四角完整可见的未裁剪照片，服务会自动检测、对齐并裁剪证件，因此请勿预先裁剪。系统会自动对证件进行分类（您无需声明国家/地区或证件类型），通过 OCR 读取视觉区域，并解码 MRZ 及所有条形码。随后进行交叉核对，验证日期、数字格式和 MRZ 校验位，并将视觉区域与 MRZ 进行比对。当 `perform_document_liveness=true` 时，还会额外排查图像是否存在屏幕翻拍、复印件和肖像篡改。 **决策逻辑。** 除非至少有一个警告被判定为拒绝，否则 `status` 为 `Approved`。欺诈和硬性失败风险一律拒绝：`DOCUMENT_EXPIRED`、`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED`、`PUBLIC_DOCUMENT_IMAGE_DETECTED`，以及提取失败（`NAME_NOT_DETECTED`、`DATE_OF_BIRTH_NOT_DETECTED`、`DOCUMENT_NUMBER_NOT_DETECTED`）。（`PORTRAIT_IMAGE_NOT_DETECTED`、`INVALID_DATE` 和 `MRZ_NOT_DETECTED` 存在于工作流会话中，但此独立 endpoint 绝不会产生这些警告。当正面图像未能高置信度匹配已知的官方证件设计时，此处会返回 `COULD_NOT_DETECT_DOCUMENT_TYPE`，并拒绝该请求。）有三类风险组可通过 `invalid_mrz_action`、`inconsistent_data_action` 和 `expiration_date_not_detected_action` 按请求单独配置（`DECLINE` 或 `NO_ACTION`）。所有其他警告（例如 `POSSIBLE_DUPLICATED_USER`）仅供参考，本身绝不会导致拒绝。当 `perform_document_liveness=true`（默认值）且防伪检查未返回可用分数时（供应商失败、返回非 200，或返回 HTTP 200 且 `status="ERR"`），调用将返回 `200`，并将状态设为 `status: "In Review"`，同时附带 `DOCUMENT_LIVENESS_NOT_COMPUTED` 警告（`log_type: "warning"`），而非 `Approved`：未运行的检查不能作为证件真实的凭据。此升级逻辑不可配置，且绝不会推翻 `Declined` 判定；若 `perform_document_liveness=false`，则跳过该检查，状态如前所述取决于其余警告。完全无法处理的证件返回 `400` 及 `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`；可读取但存在问题的证件返回 `200` 及 `status: "Declined"`，请务必检查 `id_verification.status` 和 `id_verification.warnings`，而不仅仅是 HTTP 状态码。 **计费。** 每个 `200` 响应消耗一次身份证件验证 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付本次调用时，endpoint 会在进行任何图像处理之前返回 `403` 及额度不足错误。 **会话持久化（`save_api_request`，默认 `true`）。** 为 `true` 时，调用将作为 API 类型的会话持久化保存：它会显示在 Business Console 中，返回的 `request_id` 是真实的会话 ID，可传递给 `GET /v3/session/{sessionId}/decision/`，裁剪后的证件/肖像图像会被存储并以短时有效的媒体 URL（`https:///ocr/...`）返回，同时向您配置的 Webhook endpoint 发送 `status.updated` Webhook。为 `false` 时，不存储任何内容，`request_id` 为一次性关联 UUID，且 `portrait_image`/`front_image`/`back_image` 以 Base64 编码的 JPEG 字符串内联返回。 **沙盒。** 沙盒 API 密钥会跳过所有处理和计费：在请求验证通过后（格式错误的输入仍返回 `400`），endpoint 返回静态的 `Approved` 模拟 payload（虚构的“Sandbox User”美国身份证件），不持久化保存会话，也不消耗额度。 **认证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。凭证缺失或无效返回 `403`（`{"detail": "You do not have permission to perform this action."}`），此 API 绝不返回 `401`。 **速率限制。** 所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。 operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- 身份证件的正面。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`、`pdf`。最大上传大小：**10 MB**（超出限制的文件将被拒绝并返回 `400`）。PDF 在进行 OCR 之前会渲染为图像；加密的 PDF 需要提供 `front_image_password`。图像会自动压缩至约 0.5 MB 并应用 EXIF 方向矫正。请上传完整、未裁剪且证件四角均可见的拍摄件。 front_image_password: type: string description: >- 当 `front_image` 为加密 PDF 时用于解密的密码。发送未附带（或附带错误）密码的加密 PDF 将返回 `400`。 writeOnly: true back_image: type: string format: binary description: >- 证件背面：证件有背面时请务必发送（许多身份证件在背面带有 MRZ 或条形码；省略背面仅会在响应中使 MRZ 和背面字段保持为空，此 endpoint 不会触发缺少 MRZ 的警告）。格式和大小限制与 `front_image` 相同。省略时，响应中的 `back_image` 和背面字段为 `null`。 back_image_password: type: string description: 当 `back_image` 为加密 PDF 时用于解密的密码。 writeOnly: true perform_document_liveness: type: boolean default: true description: >- 对两张图像进行呈现欺诈筛查：屏幕重放（`SCREEN_CAPTURE_DETECTED`）、打印副本（`PRINTED_COPY_DETECTED`）以及肖像篡改（`PORTRAIT_MANIPULATION_DETECTED`）。出现上述任何一种情况都会自动拒绝。默认启用；设置为 `false` 可跳过欺诈筛查并减少延迟。启用后，若提供商未返回可用评分，响应结果为包含 `DOCUMENT_LIVENESS_NOT_COMPUTED` 警告的 `In Review`，而非 `Approved`。 example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- 已接受并验证（1–120），但**目前未被此 endpoint 应用**，绝不会因该字段生成 `MINIMUM_AGE_NOT_MET` 警告。请根据返回的 `date_of_birth`/`age` 执行年龄规则，或使用带有年龄限制的验证会话工作流。 expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 当无法读取到期日期时的处理操作（`EXPIRATION_DATE_NOT_DETECTED`）。默认为 `NO_ACTION`，因为许多证件上并未印有到期日期。注意：无论此选项如何设置，*已检测到且已过期*的到期日期始终会导致拒绝（`DOCUMENT_EXPIRED`）。 invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 当提取的 MRZ 未通过校验位验证（`MRZ_VALIDATION_FAILED`）时采取的操作。在此 endpoint 上，缺少 MRZ 不会触发警告。仅适用于带有 MRZ 的证件。此 endpoint 不支持 `REVIEW`，并会返回 `400`。 inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 当提取的数据存在内部不一致时的处理操作：`DATA_INCONSISTENT`、`MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`（目视区与 MRZ 不一致）或 `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`。 critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 当拍摄时关键打印字段（身份证件号码、姓名、出生日期或到期日期）被物理遮挡（`CRITICAL_FIELD_OCCLUSION_DETECTED`）时的处理操作。默认拒绝，与该 endpoint 的其他证件完整性风险相同：遮挡报告核对所需的号码属于涂抹证件的表现。无论哪种方式，被遮挡字段读取到的值都会从提取结果中丢弃，因此通常会伴随相应的 `*_NOT_DETECTED` 警告。该 endpoint 不支持 `REVIEW` 并会返回 `400`。 document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 当号码不符合其签发机构针对该证件类型所使用的格式（`DOCUMENT_NUMBER_FORMAT_MISMATCH`、`PERSONAL_NUMBER_FORMAT_MISMATCH`）时的处理操作。默认为 `NO_ACTION`，即报告警告而不改变状态。该 endpoint 不支持 `REVIEW` 并会返回 `400`。 preferred_characters: type: string enum: - latin - non_latin default: latin description: >- 印有拉丁和非拉丁文本（阿拉伯语、西里尔字母、中日韩字符等）的证件上姓名/地址字段的首选文字系统。`latin` 返回音译/拉丁值；`non_latin` 优先返回原生文字系统。 save_api_request: type: boolean default: true description: >- 为 `true`（默认）时，将此次调用持久化为 API 类型的会话，在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，通过 `status.updated` Webhook 发出通知，并将证件图像作为媒体 URL 返回。为 `false` 时，不存储任何内容，`request_id` 为临时 UUID，且图像以 base64 JPEG 字符串形式内联返回。 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: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- 证件已处理。`id_verification.status` 为 `Approved`、`Declined` 或 `In Review`；检测到的每个问题都在 `id_verification.warnings` 中逐项列出。当所请求的证件活体检查未产生可用结果时返回 `In Review`（`DOCUMENT_LIVENESS_NOT_COMPUTED`）。有问题的证件仍会返回 `200` 并附带 `status: "Declined"` — 请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID，图像字段为短期有效的媒体 URL；当 `save_api_request=false` 时，它们是内联的 Base64 JPEG 字符串。 content: application/json: examples: Approved: summary: 清晰读取双面身份证件（已保存 — 图像作为媒体 URL） value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: 仅上传过期身份证件正面 value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- 当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。 id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- 没有警告判定为拒绝且所请求的证件活体检测得出了可用结果时为 `Approved`；所请求的检测未得出可用结果（`DOCUMENT_LIVENESS_NOT_COMPUTED`）时为 `In Review`；有警告判定为拒绝时为 `Declined`，`warnings` 列表说明了具体原因。 document_type: type: string nullable: true description: >- 检测到的证件类型显示名称：`Identity Card`、`Passport`、`Driver's License`、`Residence Permit`、`Health Insurance Card` 或 `Tax Card`。当证件无法分类时为 `null`。 example: Identity Card document_subtype: type: string nullable: true description: 可用时提供更细粒度的子类型（例如 `ID_CARD_GENERIC`、`EPASSPORT`）。 example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: 某些证件上印制的次要个人/国民身份号码。 example: 20446581H portrait_image: type: string nullable: true description: >- 从证件中裁剪的头像照片。当 `save_api_request=true`（默认）时为短期有效的媒体 URL（`https:///ocr/...`）；当 `save_api_request=false` 时为内联 base64 编码的 JPEG 字符串。未检测到头像时为 `null`。 front_image: type: string nullable: true description: 证件正面的对齐裁剪图。保存后为媒体 URL，否则为内联 base64 JPEG。 back_image: type: string nullable: true description: 证件背面的对齐裁剪图。未上传 `back_image` 时为 `null`。 front_image_camera_front: type: string nullable: true description: 在此 endpoint 上始终为 `null`（仅在摄像头拍摄验证会话中填充）。 back_image_camera_front: type: string nullable: true description: 在此 endpoint 上始终为 `null`。 front_image_camera_front_face_match_score: type: number nullable: true description: 在此 endpoint 上始终为 `null`。 back_image_camera_front_face_match_score: type: number nullable: true description: 在此 endpoint 上始终为 `null`。 front_image_quality_score: type: object nullable: true description: 上传图像的采集质量诊断（如果未提供该面或评分失败则为 `null`）。所有分数范围均为 0–100。 properties: focus_score: type: number format: float description: 证件裁剪图像的清晰度（数值越高越清晰）。 brightness_score: type: number format: float description: 曝光质量（越高越好）。 brightness_issue: type: string nullable: true description: 曝光正常时为 `ok`，否则为检测到的问题（例如过暗/过亮）。 is_document_fully_visible: type: boolean nullable: true description: 证件的四个角是否全部位于画幅内。 resolution_score: type: number format: float description: 证件区域的有效分辨率。 overall_score: type: number format: float description: 综合质量分数。 back_image_quality_score: type: object nullable: true description: 上传图像的采集质量诊断（如果未提供该面或评分失败则为 `null`）。所有分数范围均为 0–100。 properties: focus_score: type: number format: float description: 证件裁剪图像的清晰度（数值越高越清晰）。 brightness_score: type: number format: float description: 曝光质量（越高越好）。 brightness_issue: type: string nullable: true description: 曝光正常时为 `ok`，否则为检测到的问题（例如过暗/过亮）。 is_document_fully_visible: type: boolean nullable: true description: 证件的四个角是否全部位于画幅内。 resolution_score: type: number format: float description: 证件区域的有效分辨率。 overall_score: type: number format: float description: 综合质量分数。 date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: 持有人年龄（岁），根据 `date_of_birth` 计算。 example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: 签发国家/地区（ISO 3166-1 alpha-3）。 example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M`、`F`，或在未打印在证件上/未检测到时为 `null`。' example: M address: type: string nullable: true description: 与证件上印刷完全一致的地址。 formatted_address: type: string nullable: true description: '`address` 的地理编码规范化版本。' place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: '`UNKNOWN`，除非证件上印有婚姻状况。' example: UNKNOWN nationality: type: string nullable: true description: 持有人国籍（ISO 3166-1 alpha-3）。 example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- 没有专用列的证件特定附加信息（例如西班牙身份证上的 `first_surname`/`second_surname`、驾驶证上的准驾车型）。 mrz: type: object description: >- 解析后的机读区。如果证件没有 MRZ 或无法读取，则为**空对象**（`{}`），在这种情况下，还请检查 `warnings` 列表。MRZ 内的日期使用原始的 `YYMMDD` 格式。 properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: 签发国家/地区（ISO 3166-1 alpha-3）。 example: ESP nationality: type: string description: 持有人国籍（ISO 3166-1 alpha-3）。 example: ESP birth_date: type: string description: 原始 MRZ 出生日期（`YYMMDD`）。 example: '800113' expiry_date: type: string description: 原始 MRZ 到期日期（`YYMMDD`）。 example: '320331' sex: type: string example: M document_type: type: string description: MRZ 证件类型代码（例如 `ID`、`P`）。 example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: 出生日期的 MRZ 校验位。 example: '9' expiry_date_hash: type: string description: 到期日期的 MRZ 校验位。 example: '8' document_number_hash: type: string description: 证件号码的 MRZ 校验位。 example: '3' final_hash: type: string description: 综合 MRZ 校验位。 example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: 非致命性 MRZ 解析警告。 errors: type: array items: type: string description: MRZ 校验位/解析错误。非空错误会表现为 `MRZ_VALIDATION_FAILED` 警告。 mrz_type: type: string description: MRZ 排版格式：`TD1`（身份证，3 行）、`TD2` 或 `TD3`（护照，2 行）。 example: TD1 mrz_string: type: string description: 读取的原始 MRZ 文本，行以 `\n` 分隔。 mrz_key: type: string description: 用于交叉核对的复合键（证件号码 + 校验位）。 parsed_address: type: object nullable: true description: '`address` 的结构化、经地理编码的细分。当证件未包含地址或无法解析时为 `null`。' properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: ISO 3166-1 alpha-2 国家/地区代码。 example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: 规范的地理编码地址字符串。 example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- 供高级使用者使用的原始地理编码 payload（`address_components`、`geometry.location`、`place_id` 等）。 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: 证件地址的地理编码坐标。 label: type: string nullable: true description: 地址读取自证件的哪个字段。 example: Spain Identity Card Address is_verified: type: boolean description: 地理编码是否确认了该地址的存在。 category: type: string nullable: true description: 地址类别（例如 `Residential`、`Commercial`）。 example: Residential warnings: type: array description: >- 完全通过审核时为空。每个条目说明一项检测到的风险；包含 `log_type: "error"` 的条目会将 `status` 设置为 `Declined`，而 `DOCUMENT_LIVENESS_NOT_COMPUTED`（`log_type: "warning"`）会将其设置为 `In Review`。 items: type: object properties: risk: type: string description: >- 机器可读的风险代码。始终拒绝的风险：`DOCUMENT_EXPIRED`、`MINIMUM_AGE_NOT_MET`、`PORTRAIT_IMAGE_NOT_DETECTED`、`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED`、`PUBLIC_DOCUMENT_IMAGE_DETECTED`、`INVALID_DATE`、`COULD_NOT_RECOGNIZE_DOCUMENT`（仅限 400，从不作为警告）、`DOCUMENT_NUMBER_NOT_DETECTED`、`COULD_NOT_DETECT_DOCUMENT_TYPE`、`NAME_NOT_DETECTED`、`DATE_OF_BIRTH_NOT_DETECTED`。由请求选项控制：`MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED`（`invalid_mrz_action`）、`DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`（`inconsistent_data_action`）、`EXPIRATION_DATE_NOT_DETECTED`（`expiration_date_not_detected_action`）。其他风险（例如 `POSSIBLE_DUPLICATED_USER`）仅供参考。当 `perform_document_liveness=true` 但伪造检测未返回可用分数时，会触发 `DOCUMENT_LIVENESS_NOT_COMPUTED`；它将 `status` 设置为 `In Review`。当证件正面无法以高置信度匹配已知的官方证件样式时（例如经过编辑或计算机生成的证件，或者尚未支持的样式），也会返回 `COULD_NOT_DETECT_DOCUMENT_TYPE`。 example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: 引发该警告的功能。在此 endpoint 上始终为 `ID_VERIFICATION`。 additional_data: type: object nullable: true additionalProperties: true description: >- 某些风险的额外上下文信息（例如 `POSSIBLE_DUPLICATED_USER` 包含 `duplicated_session_id`）；对大多数风险为 `null`。 log_type: type: string enum: - error - warning - information description: >- 严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning`（仅限 `DOCUMENT_LIVENESS_NOT_COMPUTED`，即所请求的防伪检查未生成可用分数时）会导致 `status` 变为 `In Review`；`information` 条目仅供参考，绝不会改变状态。 short_description: type: string description: 易于阅读的单行风险摘要。 long_description: type: string description: 风险的便于人类阅读的说明。 barcodes: type: array description: 从证件解码出的条形码（PDF417、QR 码等）。当证件没有条形码或无法读取时为空。 items: type: object properties: type: type: string description: 条形码类型（例如 `PDF417`、`QR_CODE`、`UNKNOWN`）。 position: type: object nullable: true additionalProperties: true description: 图像中条形码的位置（如有）。 data: type: string description: 解码后的 payload。 data_raw: type: string description: 原始（未解码）payload（如果不同）。 side: type: string nullable: true description: '`front` 或 `back`。' 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": "COULD_NOT_RECOGNIZE_DOCUMENT"}`。上传 PDF 还可能因“提交的 PDF 文件已损坏或无效。”或无页面错误而失败。 content: application/json: examples: Missing front image: summary: 表单数据中未包含 `front_image` value: front_image: - No file was submitted. Unsupported file extension: summary: 文件扩展名不在 tiff/jpg/jpeg/png/webp/pdf 范围内 value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: 上传内容超过 10 MB 限制 value: front_image: - File size should not exceed 10 MB Invalid option value: summary: 选项仅接受 DECLINE 或 NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: 上传的 PDF 未提供所需密码 value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`front_image_password` / `back_image_password` 无法解密 PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: 图像中无法检测到身份证件 value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: 上传的 PDF 无法转换为图像 value: error: Failed to convert front image PDF. '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/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) 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.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\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 java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.