> ## 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. # 数据模型 (Data Models) > Didit 各类报告对象的标准 JSON Schema 规范，涵盖 NFC 验证、身份证件验证、活体检测、人脸比对、AML 筛查、IP、地址证明、电话验证、邮箱验证、KYB 公司登记及关键人员等结构。 ## 概述 每个针对具体功能的报告均遵循 `service-didit-verification` 中定义的 V3 序列化器结构。同一对象出现在三个位置，因此您在此处看到的架构是这些位置之间唯一的真实信息来源： * `GET /v3/session/{sessionId}/decision/`：每个功能均作为复数形式的数组返回（`id_verifications[]`、`nfc_verifications[]`、`liveness_checks[]`、`face_matches[]`、`poa_verifications[]`、`phone_verifications[]`、`email_verifications[]`、`aml_screenings[]`、`ip_analyses[]`、`database_validations[]`、`questionnaire_responses[]`、`signatures[]`、`bank_verifications[]`（请参阅[银行验证方式](https://docs.didit.me/zh/core-technology/bank-verification/verification-methods.md#在结果中读取验证方法)），以及 KYB 对应的 `registry_checks[]`、`document_verifications[]`、`key_people_checks[]`）。 * Webhook payload（`status.updated`、`data.updated`）：在 `decision` 外层结构中使用相同的格式。 * 独立 API：单对象响应（人脸搜索、年龄估算、生物识别认证）复用相同的字段集。 > [!NOTE] > > V3 引入了多实例工作流：每个功能对象都包含一个 `node_id`，用于将报告锚定到生成它的工作流图谱节点。V2 endpoint（单数形式的 `kyc`、`face`、`aml` 等）保持向后兼容，但仅返回第一个实例。 ## 常见字段 每个报告对象都会公开以下字段： | 字段 | 类型 | 描述 | | - | - | - | | `status` | string | 功能级生命周期状态：[状态枚举](#状态枚举参考)中的值之一。来源：`common/config/choices.py:FeatureStatusChoices`（第 343-348 行）。父会话的顶层 `status` 使用更广泛的会话枚举（`StatusChoices`，第 106-117 行）。 | | `node_id` | string \| null | 工作流图谱节点标识符。针对 V3 多实例工作流填充；对于旧版单功能会话为 `null`。 | | `warnings` | [警告对象](#警告对象)数组 | 针对此功能和 `node_id` 过滤的风险信号。由 `Session.get_logs(...)`（`sessions/models/session.py:1611`）返回。 | 媒体字段（`portrait_image`、`front_image`、`document_file`，…）是具有有限有效期的预签名 URL，请及时下载它们，而不是持久保存该 URL。示例中将其显示为 `https:///...`。 ## 警告对象 每个 `warnings[]` 数组中都会返回。架构来自 `logs/serializers/log.py:8-65`（`LogV3Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `feature` | string (enum) | 否 | 发出警告的功能。取值来自 `LogWarningChoices`（`common/config/choices.py:190-204`）：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACEMATCH`、`PROOF_OF_ADDRESS`、`PHONE`、`EMAIL`、`AML`、`LOCATION`、`DATABASE_VALIDATION`、`QUESTIONNAIRE`、`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`。 | `"ID_VERIFICATION"` | | `risk` | string | 否 | 稳定的风险代码（例如 `DOCUMENT_EXPIRED`、`LOW_LIVENESS_SCORE`）。取值来自 `logs/choices.py:RiskChoices`。用作描述表的键。 | `"DOCUMENT_EXPIRED"` | | `additional_data` | object \| null | 是 | 风险专属上下文（例如分数阈值、匹配字段）。格式因风险代码而异。 | `{ "score": 42.1, "threshold": 70 }` | | `log_type` | string (enum) | 否 | `error`、`warning`、`information` 之一。来自 `LogTypeChoices`（`common/config/choices.py:207-210`）。 | `"error"` | | `short_description` | string | 否 | 人类可读的风险标签。来自 `logs/choices.py:RISK_SHORT_DESCRIPTIONS`。 | `"Document expired"` | | `long_description` | string | 否 | 适合展示给终端用户的较长人类可读解释。来自 `logs/choices.py:RISK_LONG_DESCRIPTIONS`。 | `"The document's expiration date has passed, rendering it no longer valid for use."` | | `node_id` | string \| null | 是 | 触发该警告对应的工作流图谱节点。对于没有 `node_id` 的旧版 V2 日志为 `null`。 | `"first_id_verification"` | ```json theme={null} { "feature": "ID_VERIFICATION", "risk": "DOCUMENT_EXPIRED", "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.", "node_id": "first_id_verification" } ``` ## 报告对象 其余部分涵盖每个功能的报告对象。H3 标题文本保持稳定，以便其他文档进行深度链接。 ### 身份证件验证 针对用户提交的每份 KYC/身份证件返回。在 `GET /v3/session/{sessionId}/decision/` 中显示为 `id_verifications[]`，并出现在 V2 响应的 `kyc` 字段中。代码来源：`kyc/serializers/kyc.py:383-414`（`IDVerificationV3Serializer`，继承位于 `kyc/serializers/kyc.py:320-380` 的 `IDVerificationV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见 [状态枚举](#状态枚举参考)。 | `"Approved"` | | `document_type` | string | 是 | 人类可读的证件类别（`Passport`、`Identity Card`、`Driver's License`、`Residence Permit`、`Health Insurance Card`、`Tax Card`、`Social Security Card`、`Work Permit`、`Visa`、`Public Service Card`、`Birth Certificate`、`Firearm License`、`Other`）。代码来源：`DOC_TYPE_MAPPING`（`common/config/choices.py:1275-1289`）。 | `"Passport"` | | `document_subtype` | string | 是 | 来自 Didit 证件注册库的证件子类型代码，并根据工作流证件设置接受的类型进行过滤。特定地区的证件包含地区信息。完整代码列表：[证件子类型](https://docs.didit.me/zh/core-technology/id-verification/document-subtypes-id-verification.md)。 | `"QUEENSLAND_DRIVER_LICENSE_GENERIC"` | | `document_number` | string | 是 | OCR 提取的证件号码。 | `"AB1234567"` | | `personal_number` | string | 是 | OCR 提取的个人/国民身份证件号。 | `"99999999R"` | | `portrait_image` | string (URL) | 是 | 人脸裁剪图的预签名 URL。 | `"https:///.../portrait.jpg?..."` | | `front_image` | string (URL) | 是 | 清理后的证件正面预签名 URL。 | `"https:///.../front.jpg?..."` | | `front_video` | string (URL) | 是 | 正面拍摄视频的预签名 URL（可用时提供）。 | `"https:///.../front.mp4?..."` | | `back_image` | string (URL) | 是 | 清理后的证件背面预签名 URL。 | `"https:///.../back.jpg?..."` | | `back_video` | string (URL) | 是 | 背面拍摄视频的预签名 URL。 | `null` | | `full_front_image` | string (URL) | 是 | 未裁剪（完整画面）的正面拍摄图像。 | `"https:///.../full_front.jpg?..."` | | `full_back_image` | string (URL) | 是 | 未裁剪（完整画面）的背面拍摄图像。 | `null` | | `front_image_camera_front` | string (URL) | 是 | 拍摄证件正面时同时由前置摄像头拍摄的图像。 | `null` | | `back_image_camera_front` | string (URL) | 是 | 拍摄证件背面时同时由前置摄像头拍摄的图像。 | `null` | | `front_image_camera_front_face_match_score` | float (0-100) | 是 | 证件人像与前置摄像头拍摄图像之间的相似度。 | `null` | | `back_image_camera_front_face_match_score` | float (0-100) | 是 | 与上述相同，但对应背面拍摄。 | `null` | | `document_selfie_face_matches` | array | 是 | 与证件拍摄期间拍摄的自拍照相匹配的历史会话或人脸黑名单条目。条目格式与 `liveness_checks[].matches` 相同。未运行搜索时为 `null`，无匹配项时为 `[]`。 | `null` | | `front_image_quality_score` | object | 是 | 正面图像质量指标：分值 0-100（`focus_score`、`brightness_score`、`resolution_score`、`overall_score`），以及 `brightness_issue`（`ok`、`too_dark`、`too_bright`）和 `is_document_fully_visible`（布尔值）。 | `{ "focus_score": 91.0, "overall_score": 88.5 }` | | `back_image_quality_score` | object | 是 | 格式与 `front_image_quality_score` 相同。 | `null` | | `date_of_birth` | string (YYYY-MM-DD) | 是 | OCR 提取的出生日期。 | `"1990-05-12"` | | `age` | integer | 是 | 提取时计算出的周岁年龄。 | `35` | | `expiration_date` | string (YYYY-MM-DD) | 是 | 证件到期日期。 | `"2032-05-11"` | | `date_of_issue` | string (YYYY-MM-DD) | 是 | 证件签发日期。 | `"2022-05-11"` | | `issuing_state` | string (ISO 3166-1 alpha-3) | 是 | 签发国家/地区代码。 | `"ESP"` | | `issuing_state_name` | string | 是 | 本地化的签发国家/地区名称。 | `"Spain"` | | `first_name` | string | 是 | OCR 提取的名字。 | `"María"` | | `last_name` | string | 是 | OCR 提取的姓氏。 | `"García López"` | | `full_name` | string | 是 | 规范化全名（由服务商提供）。 | `"María García López"` | | `gender` | string | 是 | `M`、`F` 或服务商提供的其他值。 | `"F"` | | `address` | string | 是 | OCR 提取的原始地址行。 | `"Calle Mayor 1, 28001 Madrid"` | | `formatted_address` | string | 是 | 地理编码/格式化地址（可解析时）。 | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `parsed_address` | object | 是 | 结构化、经地理编码的地址：`street_1`、`street_2`、`city`、`region`、`country`、`postal_code`、`address_type`、`formatted_address`、`document_location`（`{latitude, longitude}`）、`raw_results`、`is_best_match`。代码来源：`kyc/utils/address.py:147-197`。 | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }` | | `place_of_birth` | string | 是 | OCR 提取的出生地点。 | `"Madrid"` | | `marital_status` | string | 是 | 可提取时提供。 | `null` | | `nationality` | string (ISO 3166-1 alpha-3) | 是 | OCR 提取的国籍。 | `"ESP"` | | `extra_fields` | object | 是 | 标准架构未涵盖的特定证件类型字段（例如驾照准驾车型）。 | `{ "DL Class": "B" }` | | `mrz` | object | 是 | 存在时解析的 MRZ 字段（`document_number`、`birth_date`、`expiry_date`、`surname`、`given_names`……）。 | `{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }` | | `extra_files` | array of strings (URL) | 否 | 任何额外上传文件的预签名 URL。 | `[]` | | `matches` | array of objects | 否 | 跨会话证件匹配项。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`。`front_image_url` 为预签名 URL。 | `[]` | | `verification_method` | string | 否 | 产生该行记录的[身份证件验证方法](https://docs.didit.me/zh/core-technology/id-verification/verification-methods.md)：`document`、`id_lookup` 或 `wallet`。对于拍照上传的证件始终为 `document`，包括在其他方法出现之前创建的所有会话。 | `"id_lookup"` | | `assurance` | string | 否 | 由 `verification_method` 派生的可信度等级：`documentary`、`data_match` 或 `cryptographic`。 | `"data_match"` | | `wallet_provider` | string \| null | 是 | 当由钱包生成该行记录时的目录钱包 ID（`mitid`、`bankid_se`、`itsme`……），否则为 `null`。 | `"mitid"` | | `fallback_from` | object \| null | 是 | 非证件方式结束证件步骤的原因：`{ method, reason, action }`。在核验或钱包登录失败时设置：当国家/地区的切换策略为 `decline` 时设置在已拒绝的记录行（`action: "decline"`）；当策略为 `fallback_to_document` 时设置在用户继续进行的证件验证上（`action: "fallback_to_document"`）。若未记录到更早的非证件方式失败，则为 `null`。 | `{ "method": "id_lookup", "reason": "no_match", "action": "decline" }` | | `id_lookup` | object \| null | 是 | 数据源证据，仅在 `verification_method` 为 `id_lookup` 时存在：`source`（查询的具体数据源：在大多数国家/地区为政府登记库，在部分国家/地区为征信机构或居住记录档案）、`checked_at`、`attempts`、`max_attempts`、`outcome`（`match`、`partial_match`、`no_match`、`provider_error`、`format_rejected`）、`comparison[]`（`{ field, label, provided, record, result }`；`field` 为 `identification_number`、`full_name`、`date_of_birth`、`address` 之一，`result` 为 `match`、`partial` 或 `no_match`；早期版本可能包含带有 `error` 的 `provider` 行）、`source_errors[]`（当前预发布环境：单独的数据源诊断信息；确认生产环境上线情况）、`registry_portrait`（预签名 URL，仅适用于返回照片的数据源）以及 `face_match_score`。 | 见下文 | | `wallet_verification` | object \| null | 是 | 凭证证据，仅在 `verification_method` 为 `wallet` 时存在：`provider`、`provider_name`、`issuing_authority`、`issuing_country`、`credential_type`、`level_of_assurance`（`low`、`substantial`、`high`）、`verified_at`、`signature_valid`、`attributes`（钱包共享的内容）、`portrait`（当钱包共享照片时的预签名 URL）以及 `face_match_score`。 | 见下文 | | `document_liveness` | object \| null | 是 | 按欺诈类型（`portrait_replace`、`printed_copy`、`screen_replay`）划分的证件活体分数，无论是否触发警告都会上报。每项包含：`score`（0-100，越高 = 越可能是真实证件；取两面中的较低值，即决策所采用的值）、`front`、`back`、`decline_threshold`、`review_threshold`、`bucket`（`approve`、`review`、`decline` 或 `null`）。阈值和分桶在评估时保存；当历史评估凭证不可用时，这三者均为 `null`，而存储的分数仍然可见。未运行检查时为 `null`。请参阅[证件活体分数](https://docs.didit.me/zh/core-technology/id-verification/report-id-verification.md#证件活体检测评分)。仅限 V3。 | `{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_id_verification"` | | `warnings` | array | 否 | 请参阅[警告对象](#警告对象)。 | `[]` | | `region` | string | 是 | 签发国家/地区的地区或州/省（若证件中已标明）。 | `"CA"` | | `extracted_data` | object | 是 | 展示给用户供其核对的证件提取数据快照，与确认后的值一并保存以便进行比对。当未要求用户核对时为 `null`。 | | | `barcodes` | 对象数组 | 否 | 从证件条形码中读取的数据，每个条形码对应一项，包含 `type`、`position`、`data`、`data_raw` 和 `side`。若无条形码则为 `[]`。 | `[]` | ```json theme={null} { "status": "Approved", "document_type": "Passport", "document_subtype": "PASSPORT_GENERIC", "document_number": "AB1234567", "personal_number": "99999999R", "portrait_image": "https:///.../portrait.jpg?signature=...", "front_image": "https:///.../front.jpg?signature=...", "front_video": null, "back_image": "https:///.../back.jpg?signature=...", "back_video": null, "full_front_image": "https:///.../full_front.jpg?signature=...", "full_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": 91.0, "brightness_score": 88.0, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 95.0, "overall_score": 88.5 }, "back_image_quality_score": null, "date_of_birth": "1990-05-12", "age": 35, "expiration_date": "2032-05-11", "date_of_issue": "2022-05-11", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "María", "last_name": "García López", "full_name": "María García López", "gender": "F", "address": "Calle Mayor 1, 28001 Madrid", "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" }, "place_of_birth": "Madrid", "marital_status": null, "nationality": "ESP", "extra_fields": {}, "mrz": { "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA", "birth_date": "900512", "expiry_date": "320511" }, "extra_files": [], "matches": [], "node_id": "first_id_verification", "verification_method": "document", "assurance": "documentary", "wallet_provider": null, "fallback_from": null, "id_lookup": null, "wallet_verification": null, "document_liveness": { "portrait_replace": { "score": 96.46, "front": 96.46, "back": 98.2, "decline_threshold": 35, "review_threshold": 70, "bucket": "approve" }, "printed_copy": { "score": 91.2, "front": 91.2, "back": 93.7, "decline_threshold": 35, "review_threshold": 77, "bucket": "approve" }, "screen_replay": { "score": 99.9, "front": 99.9, "back": 99.5, "decline_threshold": 30, "review_threshold": 70, "bucket": "approve" } }, "warnings": [] } ``` 采用非证件方式时的同一对象。仅与方法相关的键会发生变化：证件读取所填充的全部内容将改由登记库记录或钱包属性填充，不适用的键则为 `null`。 ```json theme={null} { "status": "Approved", "issuing_state": "ZAF", "first_name": "Thabo", "last_name": "Mokoena", "full_name": "Thabo Mokoena", "date_of_birth": "1991-06-15", "personal_number": "9106155043088", "node_id": "first_id_verification", "verification_method": "id_lookup", "assurance": "data_match", "wallet_provider": null, "fallback_from": null, "id_lookup": { "source": "Department of Home Affairs", "checked_at": "2026-09-04T09:12:44Z", "attempts": 1, "max_attempts": 2, "outcome": "match", "comparison": [ { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" }, { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" }, { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" } ], "registry_portrait": "https:///.../registry_portrait.jpg?signature=...", "face_match_score": 96.4 }, "wallet_verification": null, "warnings": [] } ``` ```json theme={null} { "status": "Approved", "issuing_state": "DNK", "first_name": "Freja", "last_name": "Nielsen", "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "node_id": "first_id_verification", "verification_method": "wallet", "assurance": "cryptographic", "wallet_provider": "mitid", "fallback_from": null, "id_lookup": null, "wallet_verification": { "provider": "mitid", "provider_name": "MitID", "issuing_authority": "Danish Agency for Digital Government", "issuing_country": "DNK", "credential_type": "person_identification", "level_of_assurance": "substantial", "verified_at": "2026-09-04T09:12:44Z", "signature_valid": true, "attributes": { "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678" }, "portrait": null, "face_match_score": null }, "warnings": [] } ``` ### NFC 验证 针对身份证件的每次芯片读取返回：ICAO 9303 电子护照或 eID 芯片，或通过 JPKI 读取的日本个人编号卡（My Number Card，`chip_protocol: "jpki"`）。在 `GET /v3/session/{sessionId}/decision/` 中体现为 `nfc_verifications[]`（每个父级 KYC 记录对应一项）。代码源自：`kyc/serializers/epassport.py:121-139`（`NFCV3Serializer`，继承自 `kyc/serializers/epassport.py:83-118` 的 `NFCV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 请参阅[状态枚举](#状态枚举参考)。 | `"Approved"` | | `portrait_image` | string (URL) | 是 | 芯片提取的人脸图像预签名 URL。 | `"https:///.../nfc_portrait.jpg?..."` | | `signature_image` | string (URL) | 是 | 芯片提取的签名图像预签名 URL（若芯片中存有）。 | `null` | | `chip_data` | object | 是 | 从芯片数据组（Data Groups）解析并扁平化后的个人数据（`kyc/utils/epassport.py:165-212`）：`dgs`（读取的数据组）、`surname`、`name`、`country`、`nationality`、`birth_date`（`YYYY-MM-DD`）、`expiry_date`（`YYYY-MM-DD`）、`sex`（`M`/`F`）、`document_type`（MRZ 证件代码）、`document_number`、`optional_data`、MRZ 校验位（`birth_date_hash`、`expiry_date_hash`、`document_number_hash`、`optional_data_hash`、`final_hash`）、`mrz_string`、`mrz_type`（`TD1`/`TD2`/`TD3`）；此外，当芯片包含 DG11 时还包括 `place_of_birth` 和 `address`（以及针对非拉丁姓名的 `full_name` / `full_name_non_latin`），否则不存在这些键。跳过 NFC 步骤时为 `null`。 | `{ "document_number": "AB1234567", "name": "MARIA" }` | | `authenticity` | object | 是 | `{ sod_integrity, dg_integrity }`；JPKI 读取时为 `null`。`sod_integrity` 验证证件安全对象（SOD）签名是否可追溯至有效的签发国 CSCA（且 DSC 既未被吊销也未过期）；`dg_integrity` 验证各个数据组的哈希值是否与 SOD 匹配。两者均为 `true` 表示芯片真实且未被篡改。 | `{ "sod_integrity": true, "dg_integrity": true }` | | `certificate_summary` | object | 是 | 证件签名证书摘要（`kyc/utils/epassport.py:338-348`）：`issuer`、`subject`、`serial_number`（整数）、`not_valid_before`、`not_valid_after`（`YYYY-MM-DD HH:MM:SS`），以及一个 `validation` 对象 `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }`（`kyc/views/epassport.py:86`）。 | `{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_nfc"` | | `is_nfc_skipped` | boolean | 否 | 当此 NFC 步骤被明确跳过而非读取时为 `true`；`skip_reason` 说明了跳过原因。 | `false` | | `skip_reason` | string | 是 | 跳过该步骤的原因，仅在 `is_nfc_skipped` 为 `true` 时设置。取值为 `USER_SKIPPED`、`DOCUMENT_WITHOUT_CHIP`、`CHIP_CERTIFICATE_UNAVAILABLE`、`DEVICE_WITHOUT_NFC`、`INTEGRATION_WITHOUT_NFC_ACCESS`、`MRZ_KEY_UNAVAILABLE`、`JPKI_UNAVAILABLE` 之一；参见[跳过原因](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md#跳过原因)。决策 payload 还包含一个采用相同分类体系的会话级 `nfc_skip_reason`，涵盖在创建任何报告之前就被绕过的 NFC 步骤。 | `null` | | `chip_protocol` | string | 否 | 芯片的读取方式：`icao`（ICAO 9303 电子护照或 eID 芯片）或 `jpki`（日本个人编号卡 My Number Card）。对于 `jpki`，`portrait_image`、`signature_image`、`chip_data`、`authenticity` 和 `certificate_summary` 为 `null`。在跳过的步骤中也会设置。 | `"icao"` | | `jpki` | object | 是 | 个人编号卡读取所证明的内容：`certificate_types`、`chain_valid`、`signature_valid`、`revocation_status`（`good`、`revoked` 或 `unchecked`）、`ca_generation`、`certificate_expires_at`、`certificates[]`、`attributes`（来自签名证书的姓名、出生日期、性别和地址）、`attributes_match_ocr` 以及 `mismatched_attributes`。绝不包含证书本身、其序列号或签名。对于 ICAO 芯片、跳过的步骤以及未读取任何卡片就关闭的步骤，该值为 `null`。参见[JPKI 字段](https://docs.didit.me/zh/core-technology/nfc-verification/report-nfc-verification.md#jpki-字段)。 | `null` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | ```json theme={null} { "status": "Approved", "portrait_image": "https:///.../nfc_portrait.jpg?signature=...", "signature_image": null, "chip_data": { "dgs": ["DG1", "DG2", "DG11"], "surname": "GARCIA LOPEZ", "name": "MARIA", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-12", "expiry_date": "2032-05-11", "sex": "F", "document_type": "P", "document_number": "AB1234567", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "3", "optional_data_hash": "", "final_hash": "8", "mrz_string": "P/.../reference.jpg?..."` | | `video_url` | string (URL) | 是 | 活体检测视频的预签名 URL（仅限主动模式）。 | `"https:///.../liveness.webm?..."` | | `age_estimation` | float | 是 | 参考图像中最大人脸的估算年龄（周岁）。 | `34.2` | | `matches` | array of objects | 否 | 跨会话人脸匹配结果。每项包含：`{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`。`source` 为 `session`、`imported`、`list_entry` 或 `retained_template`。保留模板匹配包含 `vendor_user_id`、`vendor_data` 和 `biometric_template_id`；其会话、图像、身份详情、状态和 API 服务字段均为 `null`。 | `[]` | | `face_quality` | float (0-100) | 是 | 被动活体人脸质量评分（归一化为百分比）。 | `87.50` | | `face_luminance` | float (0-100) | 是 | 被动活体人脸亮度评分（从 0-255 归一化为百分比）。 | `54.12` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_liveness"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | ```json theme={null} { "status": "Approved", "method": "PASSIVE", "score": 92.41, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": 34.2, "matches": [], "face_quality": 87.50, "face_luminance": 54.12, "node_id": "first_liveness", "warnings": [] } ``` ### 人脸比对 每次人脸比对返回一次（通常为用户的活体人脸与证件人像比对）。在 `GET /v3/session/{sessionId}/decision/` 中体现为 `face_matches[]`。源码：`face/serializers/face.py:367-389`（`FaceMatchV3Serializer`，继承位于 `face/serializers/face.py:323-364` 的 `FaceMatchV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `score` | float (0-100) | 是 | 相似度，保留 2 位小数。当服务商仅返回 `unmatched_faces[].Confidence` 时，转换为 `100 - confidence`。 | `97.83` | | `source_image_session_id` | string (UUID) | 是 | 其存储的人像提供源（参考）图像的会话，在基于人像的流程（生物识别认证，或在创建会话时提供的人像）中设置。当参考图像来自同一会话的证件人像时为 `null`。 | `null` | | `source_image` | string (URL) | 是 | 源（参考）图像的预签名 URL，通常是证件人像，或生物识别认证流程中的存储人像。 | `"https:///.../source.jpg?..."` | | `target_image` | string (URL) | 是 | 活体检测期间捕获的目标（活体人脸）图像的预签名 URL。 | `"https:///.../target.jpg?..."` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_face_match"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | | `face_coverage` | object | 是 | 捕获的图像中 `eyes`、`mouth` 和 `face` 是否被遮挡。每个区域包含 `covered`、`calibrated` 和 `visibility_score`；`calibrated: false` 表示存在阴影证据，但不会因此触发警告。仅由 `GET /v3/session/{sessionId}/decision/` 返回，绝不出现在 Webhook payload 中。 | `{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }` | ```json theme={null} { "status": "Approved", "score": 97.83, "source_image_session_id": null, "source_image": "https:///.../source.jpg?signature=...", "target_image": "https:///.../target.jpg?signature=...", "node_id": "first_face_match", "warnings": [] } ``` ### 人脸搜索 由独立的人脸搜索 API（`POST /v3/face-search/`）返回。人脸搜索绝不会以复数数组形式出现在 `/v3/session/{sessionId}/decision/` 中 — 当通过 `save_api_request=true` 持久化时，该会话会在其中显示为 `features[]` 中的一个 `FACE_SEARCH` 条目，以及一个携带已存储 `matches` 的 `liveness_checks[]` 项。源码：`apis/serializers/face_search.py:8-79`（包装 `FaceSearchDetailsSerializer` 的 `FaceSearchResponseSerializer`）；匹配字典构建于 `face/utils/utils.py:869-884`。 顶层响应： | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `request_id` | string (UUID) | 否 | 当 `save_api_request=true` 时的持久化会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。 | `"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"` | | `face_search` | object | 否 | 搜索详情 payload — 参见下方字段。 | — | | `vendor_data` | string | 是 | 来自请求中回传的 `vendor_data`。 | `null` | | `metadata` | object | 是 | 来自请求中回传的 `metadata`。 | `null` | | `created_at` | string (ISO 8601) | 否 | 服务端请求时间戳。 | `"2026-06-12T01:04:42.763237+00:00"` | `face_search` 对象： | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时为 `Declined`；否则为 `Approved` — 仅凭重复匹配绝不会拒绝（`apis/views/face_search.py:242-248`）。 | `"Approved"` | | `total_matches` | integer | 否 | `matches[]` 中返回的匹配数量（0–5）。 | `1` | | `matches` | array of [人脸搜索匹配对象](#人脸搜索匹配对象) | 否 | 高于相似度下限的最多 5 个匹配项，按相似度降序排列（当 `search_type=blocklisted_or_approved` 时黑名单条目排在最前）。 | `[…]` | | `user_image` | object | 否 | 提交图片的检测结果：`{ entities: [{ bbox, confidence }], best_angle }` — 每个检测到的人脸对应一个实体。 | `{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }` | | `warnings` | array of objects | 否 | 该独立 API 的精简版警告结构 — 无 `node_id`。序列化器契约声明了 `{ risk, additional_data, log_type, short_description, long_description }`（`apis/serializers/face_search.py:49-54`）；运行时 payload 还携带 `feature`，始终为 `"LIVENESS"`（`apis/views/face_search.py:332-341`）。 | `[]` | #### 人脸搜索匹配对象 | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `session_id` | string (UUID) | 是 | 匹配的验证会话。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。 | `"a3f2a6f1-…"` | | `session_number` | integer | 是 | 控制台中易读的匹配会话编号；对于非会话匹配为 `null`。 | `1024` | | `similarity_percentage` | float (0-100) | 否 | 提交的人脸与匹配人脸之间的相似度。 | `96.42` | | `source` | string (enum) | 否 | 匹配人脸的录入来源：`session`（验证会话或已保存的独立调用）、`imported`（直接上传到用户资料的人脸）、`list_entry`（附加到名单的人脸）、`retained_template`（在源会话被删除后保留的无图像[生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)）。 | `"session"` | | `vendor_data` | string | 是 | 匹配会话的 `vendor_data`，对于 `imported` 和 `retained_template` 匹配则为关联用户的该数据。 | `"user-12345"` | | `vendor_user_id` | string (UUID) | 是 | 关联的用户。对于 `list_entry` 匹配以及没有关联用户的会话为 `null`。 | `"2f7c1a9e-…"` | | `biometric_template_id` | string (UUID) | 是 | 匹配的保留模板。仅对 `retained_template` 匹配设置；可用于 `GET`/`DELETE /v3/biometric-templates/{id}/`。 | `null` | | `verification_date` | string (ISO 8601) | 是 | 捕获匹配人脸的时间，或保留 `retained_template` 的时间；对于 `list_entry` 匹配为 `null`。 | `"2024-11-04T09:14:02Z"` | | `user_details` | object | 是 | 匹配会话的证件验证提取出的 `{ full_name, document_type, document_number }`；对于 `imported` 匹配仅设置 `full_name`；当不存在身份数据时为 `null`，且对于 `retained_template` 匹配始终为 `null`。 | `{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }` | | `match_image_url` | string (URL) | 是 | 匹配用户的参考人脸 — 当 `save_api_request=true` 时为预签名 URL，否则为原始存储路径。对于不包含图像的 `retained_template` 匹配始终为 `null`。 | `"https:///.../matched.jpg?..."` | | `status` | string | 是 | 匹配会话的验证状态（参见[状态枚举](#状态枚举参考)）；对于非会话匹配为 `null`。 | `"Approved"` | | `is_blocklisted` | boolean | 否 | 匹配的人脸是否位于您的人脸黑名单中。对于 `retained_template` 匹配始终为 `false`；被列入黑名单的人脸会单独报告为 `list_entry` 匹配。 | `false` | | `is_allowlisted` | boolean | 否 | 匹配的人脸是否位于您的某个白名单中。 | `false` | | `api_service` | string (enum) | 是 | 匹配会话的大写独立 API 类型（例如 `PASSIVE_LIVENESS`、`FACE_MATCH`）；对于工作流会话和非会话匹配为 `null`。 | `null` | ```json theme={null} { "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f", "session_number": 1024, "similarity_percentage": 96.42, "source": "session", "vendor_data": "user-12345", "verification_date": "2024-11-04T09:14:02Z", "user_details": { "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }, "match_image_url": "https:///.../matched.jpg?signature=...", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null } ], "user_image": { "entities": [ { "bbox": [40, 40, 120, 120], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } ``` ### AML 筛查 按被筛查实体返回。在 KYC 和 KYB 会话的 `GET /v3/session/{sessionId}/decision/` 中均显示为 `aml_screenings[]`。源码：`aml/serializers/aml.py:63-85`（`AMLV3Serializer`，继承位于 `aml/serializers/aml.py:28-60` 的 `AMLV2Serializer`）。 | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `total_hits` | integer | 否 | 筛查命中数量（始终存在，默认值为 `0`）。 | `2` | | `entity_type` | string (enum) | 是 | `person` 或 `company`（`EntityTypeChoices`，`common/config/choices.py:675-677`）。 | `"person"` | | `hits` | array of objects | 否 | 每个命中项对应一个条目。关键字段：`id`、`caption`、`match`（布尔值）、`target`（布尔值 \| null — 实体是否为该名单条目的直接目标）、`match_score`（float 0-100 身份置信度）、`risk_score`（float 0-100 实体风险）、`score`（已废弃的 0-1 float）、`datasets[]`（例如 `PEP`、`PEP Level 1`-`4`、`Sanctions`、`Adverse Media`、`Warnings and Regulatory Enforcement`、`Fitness and Probity`）、`properties`（姓名、别名、出生日期等）、`features`、`url`、`first_seen`、`last_seen`、`rca_name`、`risk_view`、`score_breakdown`、`pep_matches`、`sanction_matches`、`warning_matches`、`adverse_media_matches`、`adverse_media_details`、`linked_entities`、`additional_information` 以及 `review_status`（`Unreviewed`、`Confirmed Match`、`False Positive`、`Inconclusive` — 可通过更新 AML 命中状态 endpoint 进行编辑，`AMLHitStatusChoices`）。 | `[…]` | | `score` | float (0-100) | 是 | 综合筛查分数，即未标记为 `False Positive` 的命中项中的最高 `risk_score`（`aml/services/aml.py:832-842`）；当所有命中项均为误报时为 `0`。计算完成前为 `null`。 | `42.7` | | `screened_data` | object | 是 | 发送至筛查的数据快照：`full_name`、`nationality`、`date_of_birth`、`document_number`。 | `{ "full_name": "María García López", "date_of_birth": "1990-05-12" }` | | `is_ongoing_monitoring_enabled` | boolean | 否 | 该实体是否订阅了持续监控重新筛查服务。 | `false` | | `next_ongoing_monitoring_bill_date` | string (YYYY-MM-DD) | 是 | 当启用持续监控时，计算为 `last_aml_bill_date + 365 days`。这是一个**计费**日期，而非筛查日期。 | `null` | | `last_ongoing_screening_at` | string (ISO 8601) | 是 | 持续监控最近一次完成对该记录重新筛查的时间，无论结果是否发生变化。从未重新筛查时为 `null`；绝不回填。 | `"2026-09-12T04:03:11Z"` | | `last_ongoing_screening_datasets_updated_at` | string (ISO 8601) | 是 | 提供商针对该次筛查报告的最新 AML 数据集更新时间。未报告数据集日期时为 `null`；绝不估算。 | `null` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_aml"` | | `warnings` | array | 否 | 参见 [警告对象](#警告对象)。 | `[]` | ```json theme={null} { "status": "In Review", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "Q7XW3-aml-hit-1", "caption": "Maria Garcia Lopez", "match": true, "target": true, "match_score": 86.4, "risk_score": 42.7, "datasets": ["PEP Level 2"], "properties": { "name": ["María García López", "M. García"], "alias": ["Maria Garcia"], "birthDate": ["1990-05-12"] }, "url": "https://example.org/registry/entities/Q7XW3", "first_seen": "2023-11-02T00:00:00Z", "last_seen": "2026-05-01T00:00:00Z", "review_status": "Unreviewed" } ], "score": 42.7, "screened_data": { "full_name": "María García López", "date_of_birth": "1990-05-12", "nationality": "ES", "document_number": "AB1234567" }, "is_ongoing_monitoring_enabled": false, "next_ongoing_monitoring_bill_date": null, "last_ongoing_screening_at": null, "last_ongoing_screening_datasets_updated_at": null, "node_id": "first_aml", "warnings": [] } ``` ### IP 分析 针对每个捕获的网络位置返回。在 KYC 和 KYB 会话中均作为 `ip_analyses[]` 出现在 `GET /v3/session/{sessionId}/decision/` 中。来源：`kyc/serializers/location.py:196-243`（`IPAnalysisSerializerV3`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见 [状态枚举](#状态枚举参考)。 | `"Approved"` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_ip_analysis"` | | `device_brand` | string | 是 | 从用户代理解析出的设备品牌。 | `"Apple"` | | `device_model` | string | 是 | 设备型号。 | `"iPhone"` | | `browser_family` | string | 是 | 浏览器系列。 | `"Mobile Safari"` | | `os_family` | string | 是 | 操作系统系列。 | `"iOS"` | | `platform` | string | 是 | 平台大类（`mobile`、`desktop`、`tablet`）。 | `"mobile"` | | `device_fingerprint` | string | 是 | 每台设备稳定的指纹哈希。 | `"f2a3…"` | | `ip_country` | string | 是 | 从 IP 解析出的国家/地区名称。 | `"Spain"` | | `ip_country_code` | string (ISO 3166-1 alpha-2) | 是 | 从 IP 解析出的国家/地区代码。 | `"ES"` | | `ip_state` | string | 是 | 从 IP 解析出的地区/省/州。 | `"Comunidad de Madrid"` | | `ip_city` | string | 是 | 从 IP 解析出的城市。 | `"Madrid"` | | `latitude` | float | 是 | 从 IP 解析出的纬度。 | `40.4168` | | `longitude` | float | 是 | 从 IP 解析出的经度。 | `-3.7038` | | `ip_address` | string | 是 | 捕获的 IP 地址。 | `"203.0.113.42"` | | `isp` | string | 是 | ISP 名称。 | `"Telefonica de Espana"` | | `organization` | string | 是 | 组织名称（通常与 ISP 相同）。 | `"Telefonica de Espana"` | | `is_vpn_or_tor` | boolean | 是 | 当 IP 属于 VPN、代理或 Tor 出口节点时为 `true`。 | `false` | | `is_data_center` | boolean | 是 | 当 IP 属于已知的托管/数据中心 ASN 时为 `true`。 | `false` | | `time_zone` | string | 是 | IANA 时区名称。 | `"Europe/Madrid"` | | `time_zone_offset` | string | 是 | UTC 偏移量。 | `"+02:00"` | | `ip` | object | 否 | `{ location, distance_from_id_document, distance_from_poa_document }`。`location = { latitude, longitude }`。距离单位为公里，若任一方缺失则为 `null`。 | `{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }` | | `id_document` | object | 否 | `{ location, distance_from_ip, distance_from_poa_document }`。根据 `issuing_state` 和解析出的地址确定的证件位置。 | `{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }` | | `poa_document` | object | 否 | `{ location, distance_from_ip, distance_from_id_document }`。地址证明（POA）中的地址（已进行地理编码）。 | `{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }` | | `matches` | array of objects | 否 | 跨会话 IP/设备匹配。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`。`match_type` 为 `ip_address` 或 `device_fingerprint`；`match_source` 为 `ip_address`、`persistent_id`、`legacy_fp` 或 `recovered_high`（恢复的匹配项还会附带 `recovery_similarity`、`tls_ja4_corroborated`、`recovery_gate_reason`）。上限为 5 个 IP + 5 个设备匹配。 | `[]` | | `warnings` | array | 否 | 参见 [警告对象](#警告对象)。 | `[]` | | `browser_version`, `os_version` | string | 是 | 来自用户代理的浏览器和操作系统版本。 | `"17.4"` | | `user_agent`, `accept_language` | string | 是 | 浏览器发送的用户代理字符串和 `Accept-Language` 请求头。 | `"en-US,en;q=0.9"` | | `session_identifier`, `session_age_ms` | string, integer | 是 | 步骤运行所在的浏览会话及其已持续的时间（毫秒）。 | `48210` | | `coords_accuracy` | float | 是 | 设备报告的坐标精度半径（米）。 | `35.0` | | `raw_device_data` | object | 是 | 为该步骤收集的原始设备信号。 | `{}` | ```json theme={null} { "status": "Approved", "node_id": "first_ip_analysis", "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Comunidad de Madrid", "ip_city": "Madrid", "latitude": 40.4168, "longitude": -3.7038, "ip_address": "203.0.113.42", "isp": "Telefonica de Espana", "organization": "Telefonica de Espana", "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+02:00", "ip": { "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }, "id_document": { "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }, "poa_document": { "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }, "matches": [], "warnings": [] } ``` ### 位置验证 针对每个[位置验证](https://docs.didit.me/zh/core-technology/location-verification/overview.md)步骤返回。在 `GET /v3/session/{sessionId}/decision/` 中显示为 `geolocation_checks[]`：每个步骤一个条目，即其已接受的尝试。`geolocation_attempts[]` 列出每个步骤的每次尝试，按时间由早到晚排序。对于不包含该步骤的工作流，两者均为 `null`。来源：`GeolocationDecisionSerializer`。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `node_id` | string | 是 | 生成该结果的工作流节点。 | `"geolocation_1"` | | `status` | string | 否 | 参见 [状态枚举](#状态枚举参考)。 | `"Declined"` | | `outcome` | string | 是 | 本次尝试的结果：`verified`、`low_accuracy`、`accuracy_undetermined`、`stale`、`approximate`、`denied`、`restricted`、`unavailable`、`timeout`、`mock_detected`、`outside_geofence`、`in_blocked_area`、`anonymizer_detected`、`skipped`、`replay_rejected` 或 `unsupported_client`。 | `"outside_geofence"` | | `permission` | string | 是 | 系统授予的权限：`granted_precise`、`granted_approximate`、`denied`、`restricted`、`unavailable`、`timeout`、`dismissed` 或 `not_requested`。 | `"granted_precise"` | | `latitude`, `longitude` | float | 是 | WGS84 坐标。无定位时为 `null`。 | `48.8566` | | `accuracy_m` | float | 是 | 不确定性半径（以米为单位）。 | `35.0` | | `accuracy_confidence` | string | 是 | `p95`、`p68` 或 `unspecified`。 | `"p95"` | | `measured_at`, `age_seconds` | datetime, integer | 是 | 设备获取定位的时间，以及到 Didit 接收时经过的秒数。 | `2` | | `source`, `platform`, `sdk_version` | string | 是 | 定位来源、生成定位的客户端及其 SDK 版本。 | `"browser"` | | `is_mock`, `produced_by_accessory` | boolean | 是 | 平台报告的欺骗攻击证据。`null` 表示未报告。 | `null` | | `integrity` | string | 否 | `attested`、`not_attested`、`failed`、`unsupported`（Web）或 `not_determined`。 | `"unsupported"` | | `country_code`, `region_code`, `city` | string | 是 | 定位解析出的地点。 | `"FR"` | | `geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas` | object, boolean, string, arrays | 是 | 国家/地区及区域结果。 | `{ "enabled": true, "result": "outside" }` | | `position_source`, `anonymizers` | string, object | 是 | 该步骤获取位置的来源，以及 VPN、代理、Tor、欺骗攻击和模拟器信号。 | `"device_and_ip"` | | `ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches` | number, boolean, integer | 是 | 与 IP 位置和存档地址的比对结果。 | `12.4` | | `attempts` | integer | 否 | 该步骤内此次尝试的编号。 | `3` | | `consent` | object | 是 | 用户接受的通知的 `accepted_at`、`version` 和 `locale`。 | | | `warnings` | [警告对象](#警告对象) 数组 | 否 | 该步骤的 `LOCATION_*` 警告。在添加了 `received_at` 和 `created_at` 的 `geolocation_attempts[]` 中不存在。 | `[]` | 所有字段和示例请参见[位置验证报告](https://docs.didit.me/zh/core-technology/location-verification/report-location-verification.md)。 ### 地址证明 按提交的每个地址证件返回。在 `GET /v3/session/{sessionId}/decision/` 中显示为 `poa_verifications[]`。来源：`poa/serializers/poa.py:212-227`（`POAV3Serializer`，继承位于 `poa/serializers/poa.py:173-209` 的 `POAV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见 [状态枚举](#状态枚举参考)。 | `"Approved"` | | `issuing_state` | string (ISO 3166-1 alpha-3) | 是 | 证件签发机构的国家/地区代码。 | `"ESP"` | | `document_type` | string | 否 | 来自 `PoaDocumentTypeChoices`（`common/config/choices.py:868-873`）的高级别类型：`UTILITY_BILL`、`BANK_STATEMENT`、`GOVERNMENT_ISSUED_DOCUMENT`、`OTHER_POA_DOCUMENT`。默认回退至 `UNKNOWN`，永不为 `null`。 | `"UTILITY_BILL"` | | `document_subtype` | string | 否 | 来自 `PoaDocumentSubtypeChoices` 的子类型代码（例如 `ELECTRICITY_BILL`、`WATER_BILL`、`ACCOUNT_STATEMENT`）。默认回退至 `UNKNOWN`，永不为 `null`。 | `"ELECTRICITY_BILL"` | | `issuer` | string | 是 | 签发机构名称。 | `"Iberdrola"` | | `issue_date` | string (YYYY-MM-DD) | 是 | 证件签发日期。 | `"2026-04-15"` | | `expiration_date` | string (YYYY-MM-DD) | 是 | 证件上印刷的到期日期（如存在）。 | `null` | | `poa_address` | string | 是 | OCR 提取的原始地址。 | `"Calle Mayor 1, 28001 Madrid"` | | `poa_formatted_address` | string | 是 | 地理编码/格式化后的地址。 | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `poa_parsed_address` | object | 是 | 结构化地址（`street_1`、`street_2`、`city`、`region`、`postal_code`、`country` (alpha-2)、`address_type`、`document_location` 等）。 | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }` | | `document_file` | string (URL) | 是 | 上传证件的预签名 URL。 | `"https:///.../poa.pdf?..."` | | `document_language` | string | 是 | 检测到的证件语言（ISO 639-1）。 | `"es"` | | `document_metadata` | object | 是 | 过滤后的元数据：`file_size`、`content_type`、`creation_date`、`modified_date`、`creator`、`producer`、`software`、`encryption`、`is_signed`、`is_tampered`、`signature_info`、`exif_original_date`、`exif_digitized_date`、`processed_by_known_editor`、`has_different_creation_mod_date`、`overlay_manipulation`。 | `{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }` | | `extra_fields` | object | 否 | 银行账户字段（`bank_account_number`、`bank_iban`、`bank_sort_code`、`bank_routing_number`、`bank_swift_bic`、`bank_branch_name`、`bank_branch_address`）、`document_phone_number`、`additional_names`，以及持久化在记录中的任何自定义键。 | `{ "bank_iban": null, "additional_names": [] }` | | `name_on_document` | string | 是 | 地址证明上显示的姓名。 | `"María García López"` | | `expected_details_address` | string | 是 | 客户在注册时填写的原样地址。 | `"Calle Mayor 1, Madrid"` | | `expected_details_formatted_address` | string | 是 | 地理编码后的预期地址。 | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `expected_details_parsed_address` | object | 是 | 结构化的预期地址。 | `{ "city": "Madrid", "postal_code": "28001" }` | | `name_match_score_expected_details` | float (0-100) | 是 | `name_on_document` 与创建会话时提供的姓名之间的模糊匹配度。 | `94.0` | | `name_match_score_id_verification` | float (0-100) | 是 | `name_on_document` 与验证通过的身份证件 `full_name` 之间的模糊匹配度。 | `100.0` | | `extra_files` | array of strings (URL) | 否 | 其他已上传文件的预签名 URL。 | `[]` | | `detected_codes` | array of objects | 否 | 在证件每个已处理页面上检测到的二维码和条形码：`type`、`page_number`（从 1 开始）、`position`（多边形）、`x`/`y`/`width`/`height`（边界框）、`page_width`/`page_height`、`raw_payload`（base64）、`parsed_payload`（解码后的值，定位到代码但无法解码时为 `null`）。未检测到任何代码时为空数组。 | `[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_poa"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | ```json theme={null} { "status": "Approved", "issuing_state": "ESP", "document_type": "UTILITY_BILL", "document_subtype": "ELECTRICITY_BILL", "issuer": "Iberdrola", "issue_date": "2026-04-15", "expiration_date": null, "poa_address": "Calle Mayor 1, 28001 Madrid", "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }, "document_file": "https:///.../poa.pdf?signature=...", "document_language": "es", "document_metadata": { "file_size": 184221, "content_type": "application/pdf", "creation_date": "2026-04-15T08:11:32Z", "modified_date": "2026-04-15T08:11:32Z", "creator": "Iberdrola Billing", "producer": "Adobe PDF Library 15.0", "software": null, "encryption": null, "is_signed": true, "is_tampered": false, "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" }, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": 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": [] }, "name_on_document": "María García López", "expected_details_address": "Calle Mayor 1, Madrid", "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" }, "name_match_score_expected_details": 94.0, "name_match_score_id_verification": 100.0, "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": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx", "parsed_payload": "https://iberdrola.es/factura/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": "MDA5OTgxMDAwNDI=", "parsed_payload": "0099810042" } ], "node_id": "first_poa", "warnings": [] } ``` ### 电话验证 针对每次电话验证尝试返回。在 KYC 和 KYB 会话的 `GET /v3/session/{sessionId}/decision/` 中显示为 `phone_verifications[]`。来源：`phone/serializers/phone.py:251-266`（`PhoneV3Serializer`，继承自 `phone/serializers/phone.py:103-248` 的 `PhoneV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `phone_number_prefix` | string | 否 | E.164 国家/地区前缀（带 `+`）。 | `"+34"` | | `phone_number` | string | 否 | 不带前缀的用户号码。 | `"612345678"` | | `full_number` | string | 否 | 完整的 E.164 号码（`phone_number_prefix + phone_number`）。 | `"+34612345678"` | | `country_code` | string (ISO 3166-1 alpha-2) | 是 | 号码所属国家/地区。 | `"ES"` | | `country_name` | string | 是 | 本地化的国家/地区名称。 | `"Spain"` | | `carrier` | object | 否 | `{ name, type }`，其中 `type` 为 `LineTypeChoices` 的取值之一（`common/config/choices.py:648-667`）：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate`、`satellite`、`pager`、`payphone`、`voice_mail`、`unknown` 以及其他线路类型。 | `{ "name": "Movistar", "type": "mobile" }` | | `is_disposable` | boolean | 否 | 当运营商将该号码标记为临时/一次性号码时为 `true`。 | `false` | | `is_virtual` | boolean | 否 | 当 `carrier.type` 为 `voip`、`isp`、`vpn` 之一时为 `true`。 | `false` | | `verification_method` | string | 否 | 用于投递 OTP 的渠道（`whatsapp`、`sms`……）。读取自最后一次发送尝试的 `actual_channel`（回退至请求的 `channel`，然后回退至 `sms`）。 | `"whatsapp"` | | `verification_attempts` | integer | 否 | OTP 发送尝试总次数（初次发送加上重发）。 | `1` | | `verified_at` | string (ISO 8601) | 是 | 成功输入 OTP 的时间戳。 | `"2026-05-17T10:14:02Z"` | | `lifecycle` | array of objects | 否 | 按时间顺序排列的事件：发送尝试、投递回调、代码校验以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `PhoneEventChoices`。 | `[…]` | | `matches` | array of objects | 否 | 跨会话电话号码匹配项。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。 | `[]` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_phone"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | | `phone_intelligence` | object | 是 | 电话情报信号。仅在为该号码运行了情报附加组件时存在。 | | | `phone_social` | object | 是 | 该号码的社交足迹。仅在运行了社交足迹附加组件时存在。 | | ```json theme={null} { "status": "Approved", "phone_number_prefix": "+34", "phone_number": "612345678", "full_number": "+34612345678", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Movistar", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2026-05-17T10:14:02Z", "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-05-17T10:13:51Z", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.02 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-05-17T10:13:52Z", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-05-17T10:14:02Z", "details": { "code_tried": "482917", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-05-17T10:14:02Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "first_phone", "warnings": [] } ``` ### 邮箱验证 针对每次邮箱验证尝试返回。在 KYC 和 KYB 会话的 `GET /v3/session/{sessionId}/decision/` 中显示为 `email_verifications[]`。来源：`email_verification/serializers/email.py:149-164`（`EmailV3Serializer`，继承自 `email_verification/serializers/email.py:38-146` 的 `EmailV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `email` | string | 否 | 提交的邮箱地址。 | `"maria.garcia@example.com"` | | `is_breached` | boolean | 否 | 当该邮箱出现在已知数据泄露事件中时为 `true`。 | `false` | | `breaches` | array of objects | 否 | 当 `is_breached` 为 `true` 时的单次泄露详情：`{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`。 | `[]` | | `is_disposable` | boolean | 否 | 当该邮箱属于一次性邮箱提供商时为 `true`。 | `false` | | `is_undeliverable` | boolean | 否 | 当 SMTP 投递探测显示该收件箱不接收邮件时为 `true`。 | `false` | | `verification_attempts` | integer | 否 | OTP 校验尝试总次数。 | `1` | | `verified_at` | string (ISO 8601) | 是 | 成功输入 OTP 的时间戳。 | `"2026-05-17T10:15:22Z"` | | `lifecycle` | array of objects | 否 | 按时间顺序排列的事件：发送尝试、代码校验以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `EmailEventChoices`。 | `[…]` | | `matches` | array of objects | 否 | 跨会话邮箱匹配项。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。 | `[]` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_email"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | | `email_intelligence` | object | 是 | 邮箱情报信号。仅在为该地址运行了情报附加组件时存在。 | | | `email_social` | object | 是 | 该地址的社交足迹。仅在运行了社交足迹附加组件时存在。 | | ```json theme={null} { "status": "Approved", "email": "maria.garcia@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-05-17T10:15:22Z", "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-05-17T10:15:11Z", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-05-17T10:15:22Z", "details": { "code_tried": "739204", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-05-17T10:15:22Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "first_email", "warnings": [] } ``` ### 数据库核验 针对基于用户提交数据运行的每次数据库查询返回。在 `GET /v3/session/{sessionId}/decision/` 中显示为 `database_validations[]`。来源：`database_validation/serializers/database_validation.py:21-142`（`DatabaseValidationV3Serializer`，继承自 `DatabaseValidationV2Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `issuing_state` | string (ISO 3166-1 alpha-3) | 是 | 查询的登记机构所属国家/地区。 | `"ESP"` | | `validation_type` | string (enum) | 否 | 结果的证实方式：`one_by_one`（单一服务结果）、`two_by_two`（两个或多个不同服务独立完全匹配该身份号码）或 `not_enabled`（核验器已跳过或无提供商响应 — 明确的 `no_match` 仍会生成 `one_by_one`）。绝不为 `null`。来源：`DatabaseValidationChoices`（`common/config/choices.py:1097-1100`）。 | `"one_by_one"` | | `screened_data` | object | 否 | 提交给登记机构的数据。文件字段（`selfie`、`cnh_qr_code_image`、`document_image`）在读取时生成预签名 URL。 | `{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }` | | `validations` | array of objects | 否 | 产生匹配的每个目录服务对应一项条目。每个条目可包含 `service_id`、`service_name`、`validation`（提供商判定对象）、`outcome_code`、`outcome_detail` 和 `source_data`（清洗后的公民档案：`full_name`、`gender`、`date_of_birth`、`photo`（预签名 URL）、`signature`（预签名 URL）等）。 | `[…]` | | `errors` | array of objects | 是 | 查询失败时的各服务错误；为空时该键会被完全省略。每个条目是上游服务的错误对象加上生成该错误对象的 `service_id`。 | `[]` | | `match_type` | string (enum) | 是 | 所查询服务之间的综合匹配判定：`full_match`、`partial_match` 或 `no_match`（`DatabaseValidationMatchTypeChoices`，`common/config/choices.py:1103-1106`）。评估前为 `null`。 | `"full_match"` | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `node_id` | string \| null | 是 | 工作流节点标识符 (V3)。 | `"first_db_validation"` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | ```json theme={null} { "issuing_state": "ESP", "validation_type": "one_by_one", "screened_data": { "document_number": "99999999R", "date_of_birth": "1990-05-12", "first_name": "María", "last_name": "García López" }, "validations": [ { "service_id": "esp_dni", "service_name": "Spain - DNI/NIE verification", "validation": { "is_valid": true, "match_score": 100 }, "outcome_code": "MATCH", "outcome_detail": "All identifiers match the registry record.", "source_data": { "full_name": "María García López", "gender": "F", "date_of_birth": "1990-05-12", "photo": "https:///.../registry_photo.jpg?signature=...", "signature": null } } ], "match_type": "full_match", "status": "Approved", "node_id": "first_db_validation", "warnings": [] } ``` ### 问卷响应 每次提交问卷时返回。在 KYC 和 KYB 会话的 `GET /v3/session/{sessionId}/decision/` 中以 `questionnaire_responses[]` 形式出现。来源：`questionnaires/serializers/questionnaire.py:591-597`（`QuestionnaireResponseV3Serializer`，继承自 `questionnaires/serializers/questionnaire.py:520-588` 中的 `QuestionnaireResponseSerializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `questionnaire_id` | string (UUID) | 否 | 所作答的问卷版本标识符。 | `"6a0f1c2c-…"` | | `title` | string | 否 | 在控制台中设置的问卷名称。 | `"Customer risk profile"` | | `description` | string | 是 | 问卷描述。 | `"Short risk-profile questions."` | | `languages` | array of strings | 否 | 问卷发布的语言代码。 | `["en", "es"]` | | `default_language` | string | 否 | 回退语言代码。 | `"en"` | | `is_active` | boolean | 否 | 此问卷版本是否处于活跃状态。 | `true` | | `is_simple_questionnaire` | boolean | 否 | 当问卷没有分支逻辑（扁平列表）时为 `true`。 | `true` | | `questionnaire_group_id` | string (UUID) | 否 | 同一问卷的不同版本之间共享的标识符。 | `"a7c2c2c2-…"` | | `version` | integer | 否 | 活跃模板的版本号。 | `3` | | `status` | string | 否 | `Approved`、`In Review`、`Not Finished` 之一（问卷级别的拒绝会映射到 `In Review`）。 | `"Approved"` | | `published_at` | string (ISO 8601) | 是 | 模板的发布时间。 | `"2026-01-12T11:00:00Z"` | | `sections` | array of objects | 否 | 应用图谱遍历和可见性过滤后的有序章节。每个章节为 `{ title, description, items[] }`（标题/描述来自起始的 `SECTION_HEADER`，已预先翻译）。每个条目是一个表单元素（`uuid`、`value`（节点 ID）、`element_type`、`is_required`、`title`、`description`、`placeholder`、`choices`、`max_files`、`required_if`、`repeatable_config`，以及一个 `answer` 字段 — 未作答时为 `null`，在 `HEADING`/`PARAGRAPH`/`SEPARATOR` 布局条目上省略）。文件回答包含 `{ files: [, …] }`。 | `[…]` | | `node_id` | string \| null | 是 | 工作流节点标识符 (V3)。 | `"first_questionnaire"` | ```json theme={null} { "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9", "title": "Customer risk profile", "description": "Short risk-profile questions.", "languages": ["en", "es"], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9", "version": 3, "status": "Approved", "published_at": "2026-01-12T11:00:00Z", "sections": [ { "title": "Source of funds", "description": null, "items": [ { "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9", "value": "q_source_of_funds", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "What is your main source of funds?", "description": null, "placeholder": null, "choices": [ { "label": "Salary", "value": "salary" }, { "label": "Business income", "value": "business" }, { "label": "Investments", "value": "investments" } ], "max_files": 1, "required_if": null, "repeatable_config": null, "answer": { "value": "salary" } } ] } ], "node_id": "first_questionnaire" } ``` ### 电子签名 针对[电子签名](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md)步骤的每位签署人返回。仅当工作流包含该步骤时，在 KYC 和 KYB 会话的 `GET /v3/session/{sessionId}/decision/` 中以 `signatures[]` 形式出现。与其他报告对象不同，其 `status` 代表签署阶段，结果在 `verdict` 中，且其 `warnings[]` 条目为 `{ code, node_id }`，而非[警告对象](#警告对象)。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `id` | string (UUID) | 否 | 签署人的签名。在证据和验证路由中用作 `signature_id`。 | `"0e6c2a8e-…"` | | `node_id` | string | 否 | 工作流节点标识符。 | `"feature_signature"` | | `status` | string | 否 | 签署阶段：`intro`、`review`、`code`、`signing`、`signed` 或 `declined`。仅 `signed` 表示文件已签署。 | `"signed"` | | `verdict` | string | 否 | `Not Finished`、`Approved`、`In Review` 或 `Declined`。 | `"Approved"` | | `level` | string | 否 | `simple`（默认）或 `aes`。`qes` 为附加组件，目前暂不可用。 | `"aes"` | | `format` | string | 否 | Simple 签名对应 `pdf`，高级签名 (AES) 对应 `pades`。 | `"pades"` | | `profile` | string | 是 | 高级 (AES) 签名签署完成后为 `PAdES-B-LT`，否则为 null。 | `"PAdES-B-LT"` | | `signer` | object | 否 | `{ name, capacity, company, role, roles, identity_session_id }`。`capacity` 可以是 `self` (KYC) 或 `company` (KYB)。 | `{ "name": "Jane Doe", "capacity": "self", … }` | | `identity_used` | object | 否 | `{ session_id, kyc_id, verified, expected_name }`：签名所依赖的已核验身份。对于无已核验身份的 Simple 签名，该项为空。 | `{ "verified": true, … }` | | `certificate` | object | 是 | `{ issuer, issued_to, serial, valid_from, valid_until }`。签署完成前为 `null`，且 Simple 签名始终为 `null`。 | `{ "serial": "5A3F9C21", … }` | | `confirmation` | object | No | `{ channel, destination, confirmed_at, attempts }`。`destination` 已脱敏；`attempts` 统计输入的验证码次数，包含正确的一次。简易签名无需验证码，因此 `channel` 和 `destination` 为 `null`。 | `{ "channel": "email", … }` | | `timestamp` | object | Yes | `{ time, qualified, valid }`。对于 AES，`qualified` 始终为 `false`。签名完成前为 `null`，简易签名始终为 `null`。 | `{ "qualified": false, … }` | | `documents` | array of objects | No | `{ id, uuid, title, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }`。`status` 为 `signed`、`declined`、`not_signed` 或 `not_reached`。`mode` 为 `fields` 或 `read_and_agree`。`source_format` 为 `pdf` 或 `docx`；`conversion` 描述原始 Word 文件，对于 PDF 则为 `null`。 | `[…]` | | `documents[].fields` | array of objects | No | 证件上每个字段的 `{ key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason }`。`value` 为字符串、复选框对应的布尔值，或对于已应用的签名或姓名首字母则为 `true`。无字段的证件此项为空。 | `[…]` | | `adopted_signature` | object | Yes | `{ method, font, adopted_at }`：签署人采用的签名和姓名首字母。`method` 为 `typed` 或 `drawn`；`font` 为键入签名的手写样式。采用前为 `null`。 | `{ "method": "drawn", … }` | | `electronic_signature_consent_at` | string (ISO 8601) | Yes | 签署人同意以电子方式签署证件的时间。当任一证件包含字段时设置。 | `"2026-11-03T10:41:40Z"` | | `evidence_file` | string | Yes | 签署完成后证据 PDF 的路径。 | `"/v3/session/…/evidence/?signature_id=…"` | | `warnings` | array of objects | No | `{ code, node_id }`，其中 `code` 为 `SIGNATURE_DECLINED`、`SIGNATURE_OTP_FAILED`、`SIGNATURE_NAME_MISMATCH`、`SIGNATURE_IDENTITY_NOT_VERIFIED`、`SIGNATURE_DOCUMENT_CHANGED` 之一。 | `[]` | | `validation` | object | Yes | `{ valid, checked_at, documents[] }`：对已签署证件的最新密码学检查。签名完成前为 `null`。当无法确认签名结果时为 `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }`。 | `{ "valid": true, … }` | | `declined_at` | string (ISO 8601) | Yes | 签署人拒绝的时间。 | `null` | | `declined_action` | string | No | 该步骤的 `signature_declined_action`。 | `"REVIEW"` | | `signed_at` | string (ISO 8601) | Yes | 证件签署完成的时间。 | `"2026-11-03T10:42:24Z"` | | `expires_at` | string (ISO 8601) | No | 签名链接失效的时间。 | `"2026-11-10T10:30:00Z"` | | `email_sent_at` | string (ISO 8601) | Yes | 通过邮件向签署人发送已签署副本的时间。 | `"2026-11-03T10:42:30Z"` | | `email_unavailable_reason` | string | Yes | 当请求了邮件副本但未发送的原因。 | `null` | | `ip_address` | string | Yes | 签署人索取验证码时的地址。 | `"203.0.113.10"` | | `place` | string | Yes | 未采集：始终为 `null`。 | `null` | | `place_unavailable_reason` | string | Yes | `not_collected`。 | `"not_collected"` | [电子签名报告](https://docs.didit.me/zh/core-technology/electronic-signature/report-electronic-signature.md)提供了完整示例和所有嵌套字段。 ### 年龄估算 由独立的年龄估算 API（`POST /v3/age-estimation/`）返回。响应在 `age_estimation` 外层对象下包含 [`Liveness check`](#活体检测) 结构的子集（`status`、`method`、`score`、`age_estimation`、`warnings`），外加仅独立接口拥有的 `user_image` 人脸检测块；它**不**包含 `reference_image`、`video_url`、`matches`、`face_quality` 或 `face_luminance`。在工作流会话中不存在单独的数组，估算的年龄在 `GET /v3/session/{sessionId}/decision/` 中作为 `liveness_checks[].age_estimation` 呈现。来源：`apis/serializers/age_estimation.py:50-55`（`AgeEstimationResponseSerializer`），外层对象组装位于 `apis/views/age_estimation.py:138-174`。 | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `request_id` | string (UUID) | No | 当 `save_api_request=true`（默认值）时为持久化的会话 ID；否则为临时的关联 UUID。 | `"3b1f1e2c-…"` | | `age_estimation` | object | No | 结果外层对象：`status`（`Approved` / `Declined`）、`method`（始终为 `PASSIVE`）、`score`（活体得分 0-100，可为 null）、`age_estimation`（最大人脸的预测年龄（岁），可为 null）、`user_image`（包含每个人脸 `age`、`bbox` `[x_min, y_min, x_max, y_max]`、`confidence`、`gender` 的 `entities[]`；外加 `best_angle`）、`warnings[]`。 | `{ … }` | | `vendor_data` | string | Yes | 请求中回传的 `vendor_data`。 | `null` | | `metadata` | object | Yes | 请求中回传的 `metadata`。 | `null` | | `created_at` | string (ISO 8601) | No | 服务端请求时间戳。 | `"2026-05-17T10:22:13.512941+00:00"` | ```json theme={null} { "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9", "age_estimation": { "status": "Approved", "method": "PASSIVE", "score": 94.10, "age_estimation": 28.7, "user_image": { "entities": [ { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-05-17T10:22:13.512941+00:00" } ``` ### 生物识别认证 生物识别认证运行标准 KYC 中使用的相同活体检测 + 人脸比对流水线，但配置为将采集到的人脸与现有用户的参考图像进行比对，而不是与刚通过 OCR 识别的证件头像进行比对。没有专门的序列化器：`GET /v3/session/{sessionId}/decision/` 在 `liveness_checks[]` 和 `face_matches[]` 下返回标准的 [活体检测](#活体检测) 和 [人脸比对](#人脸比对) 对象。该会话的工作流配置为 `workflow_type = "biometric_authentication"`（`WorkflowTypeChoices`，`common/config/choices.py:636`）。 | 字段 | 类型 | 可为 null | 描述 | 示例 | | - | - | - | - | - | | `liveness_checks` | array of [活体检测](#活体检测) | No | 认证尝试的活体检测结果。 | `[ { "status": "Approved", … } ]` | | `face_matches` | array of [人脸比对](#人脸比对) | No | 与已登记参考图像的比对结果。`source_image_session_id` 设置为该会话自身的 `session_id`：参考人脸（提供的 `portrait_image`，或者在省略 `portrait_image` 时通过 `vendor_data` 复用的已存储人脸）记录在认证会话本身中（`face/views/face.py:656-659`）。 | `[ { "status": "Approved", "source_image_session_id": "…", … } ]` | | `status` | string | 否 | 顶层会话状态（参见[状态枚举](#状态枚举参考)）。 | `"Approved"` | ```json theme={null} { "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "status": "Approved", "liveness_checks": [ { "status": "Approved", "method": "PASSIVE", "score": 95.10, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": null, "matches": [], "face_quality": 91.20, "face_luminance": 53.10, "node_id": "biometric_auth_liveness", "warnings": [] } ], "face_matches": [ { "status": "Approved", "score": 98.42, "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "source_image": "https:///.../source.jpg?signature=...", "target_image": "https:///.../target.jpg?signature=...", "node_id": "biometric_auth_face_match", "warnings": [] } ] } ``` ### KYB 公司登记 在 KYB 工作流中针对每个经公司登记确认的公司返回。在用于企业会话的 `GET /v3/session/{sessionId}/decision/` 中显示为 `registry_checks[]`。来源：`kyb/serializers/kyb.py:939-964`（`RegistryCheckV3Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见[状态枚举](#状态枚举参考)。 | `"Approved"` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_registry"` | | `data_resolved` | boolean | 否 | 当公司登记数据获取已完成（或 `is_from_registry` 为 `false`，表示数据为手动输入）时为 `true`。 | `true` | | `company` | object | 否 | 完整公司 payload — 参见下文的[公司对象](#公司对象)。 | `{ … }` | | `ownership_structure` | object | 是 | 公司登记证明的股权结构表：`shareholders[]` 和 `beneficial_owners[]`，每个所有者包含其登记身份、持股比例和规范的 `shareholding`。 | `{ "shareholders": [...], "beneficial_owners": [] }` | | `warnings` | array | 否 | 参见[警告对象](#警告对象)。 | `[]` | #### 公司对象 来自 `kyb/serializers/kyb.py:220-321`（`KYBCompanyResponseSerializer`）。 | 字段 | 类型 | 可为空 | 描述 | | - | - | - | - | | `uuid` | string (UUID) | 否 | 内部公司标识符。 | | `node_id` | string \| null | 是 | 工作流节点标识符。 | | `status` | string | 否 | 功能状态（`FeatureStatusChoices`）。 | | `registry_status` | string | 是 | 来自公司登记的公司状态（`active`、`dissolved` 等）。 | | `data_resolved` | boolean | 否 | 与父对象上的定义相同。 | | `company_name` | string | 是 | 注册公司名称。 | | `registration_number` | string | 是 | 注册号。 | | `country_code` | string (ISO 3166-1 alpha-2) | 是 | 注册成立国家/地区。 | | `region` | string | 是 | 适用的 ISO 3166-2 行政区划（例如 `US-CA`）。 | | `company_type` | string | 是 | 法律组织形式（`LLC`、`SL` 等）。 | | `incorporation_date` | string (YYYY-MM-DD) | 是 | 注册成立日期。 | | `registered_address` | string | 是 | 注册法定地址。 | | `tax_number` | string | 是 | 税号 / 增值税标识符。 | | `risk_level` | string | 是 | 提供商给出的风险评级。 | | `verification_status` | string | 是 | 内部验证状态枚举。 | | `is_from_registry` | boolean | 否 | 当来源于公司登记（相对于手动输入）时为 `true`。 | | `fetch_status` | string | 是 | `pending`、`resolved`、`failed`。 | | `alternative_names` | string | 是 | 逗号分隔的其他商用名称。 | | `nature_of_business` | string | 是 | 自由文本格式的商业活动描述。 | | `registered_capital` | string | 是 | 人类可读字符串格式的注册资本。 | | `registered_capital_amount` | string (decimal) | 是 | 解析后的注册资本金额。 | | `registered_capital_currency` | string (ISO 4217) | 是 | 货币代码。 | | `website` | string (URL) | 是 | 公司网站。 | | `email` | string | 是 | 公开联系邮箱。 | | `phone` | string | 是 | 公开联系电话。 | | `legal_entity_identifier` | string | 是 | 法人机构识别码（LEI，如可用）。 | | `location_of_registration` | string | 是 | 登记机关 / 地区。 | | `vat_number` | string | 是 | 为公司提交的增值税号。 | | `vat_validation_status` | string | 否 | 验证增值税号或 `tax_number`（当没有增值税号时）的结果：`valid`、`invalid`、`format_valid`、`invalid_format`、`could_not_validate` 或 `not_applicable`。参见[增值税号与税号核验](https://docs.didit.me/zh/business-verification/company-data.md#vat-号码与税号验证)。 | | `vat_validated_number` | string | 是 | 数据源所记录的经过核验的号码。 | | `vat_validation_source` | string | 是 | 判定该状态的数据源：`eu_vies`、`pl_vat_white_list`、`no_brreg`、`ch_uid_register`、`br_receita_federal`、`co_rues`、`cr_hacienda`、`ec_sri`、`py_dnit` 或 `format_rules`。 | | `vat_validated_name` | string | 是 | 在数据源登记的名称（当数据源未披露时为空）。 | | `vat_validated_address` | string | 是 | 在数据源登记的地址（未披露时为空）。 | | `vat_checked_at` | string (ISO 8601) | 是 | 核验的时间戳；未运行核验时为 `null`。 | | `financial_summary` | object | 是 | 公司登记提供的最新财务摘要快照（如提供）。 | | `officers` | array of objects | 否 | 适用于 B2C 的管理人员列表：`{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`。 | | `beneficial_owners` | array of objects | 否 | 适用于 B2C 的 UBO 列表：`{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`。 | | `addresses` | array of objects | 是 | 来自公司登记的各地址详情。 | | `industries` | array of objects | 是 | SIC/NAICS 风格的行业分类。 | | `accounts` | array of objects | 是 | 已提交账目元数据。 | | `registry_data` | object | 是 | Didit 归一化的登记详情（股权结果、控制台修正、没有独立字段的登记事实）。非稳定契约。 | | `user_provided_data` | object | 是 | 用户编辑字段的快照。 | | `confirmed_by_user_at` | string (ISO 8601) | 是 | 用户确认提取数据的时间戳。 | | `last_console_edit_at` | string (ISO 8601) | 是 | 上次在控制台编辑的时间戳。 | | `is_editable` | boolean | 否 | 当来自登记的数据仍可被终端用户编辑时为 `true`。 | ```json theme={null} { "status": "Approved", "node_id": "first_registry", "data_resolved": true, "company": { "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9", "node_id": "first_registry", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "Sante Clinics SL", "registration_number": "B12345678", "country_code": "ES", "region": null, "company_type": "SL", "incorporation_date": "2018-03-22", "registered_address": "Calle Mayor 1, 28001 Madrid, Spain", "tax_number": "B12345678", "risk_level": "low", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "Sante Clinics", "nature_of_business": "Medical clinic operations", "registered_capital": "EUR 50,000", "registered_capital_amount": "50000.00", "registered_capital_currency": "EUR", "website": "https://santeclinics.com", "email": "info@santeclinics.com", "phone": "+34911223344", "legal_entity_identifier": null, "location_of_registration": "Registro Mercantil de Madrid", "vat_number": "ESB12345678", "vat_validation_status": "valid", "vat_validated_name": "SANTE CLINICS SL", "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID", "vat_checked_at": "2026-05-17T10:11:05Z", "financial_summary": null, "officers": [ { "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "designation": "Administrador único", "role": "Director", "nationality": "ESP", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…" } ], "beneficial_owners": [ { "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "first_name": "María", "last_name": "García López", "entity_type": "person", "roles": ["UBO"], "ownership_min_shares": "75.00", "ownership_max_shares": "75.00", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "effective_ownership_percent": 75.0 } ], "addresses": [], "industries": [], "accounts": [], "registry_data": {}, "user_provided_data": {}, "confirmed_by_user_at": "2026-05-17T10:11:02Z", "last_console_edit_at": null, "is_editable": false }, "ownership_structure": null, "warnings": [] } ``` ### KYB 证件 按收集 KYB 支持性证件的节点返回。在用于企业会话的 `GET /v3/session/{sessionId}/decision/` 中显示为 `document_verifications[]` — 每个 `node_id` 一个条目，其中 `items[]` 列出每个上传的证件。来源：`kyb/serializers/kyb.py:1053-1068`（`DocumentVerificationV3Serializer`）；每个项目的结构遵循 `kyb/serializers/kyb.py:811-851`（`KYBDocumentResponseSerializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 该节点所有证件的汇总状态：仅当流水线中的所有证件均已通过时为 `Approved`；若有任何证件被拒绝则为 `Declined`；其他情况下为 `In Review`；待处理时为 `Not Finished`。参见 [Status 枚举](#状态枚举参考)。 | `"Approved"` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_kyb_documents"` | | `items` | [KYB 证件项对象](#kyb-证件项对象) 数组 | 否 | 每个已上传或要求的证件对应一个条目。 | `[…]` | | `groups` | object | 否 | 按证件分组的计数：`{ : { total, approved, pending, declined, in_review, other, missing } }`。 | `{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }` | | `required_groups` | 字符串数组 | 否 | 工作流配置所要求的证件分组。 | `["incorporation_certificate", "shareholder_register"]` | | `warnings` | array | 否 | 参见 [警告对象](#警告对象)。 | `[]` | #### KYB 证件项对象 | 字段 | 类型 | 可为空 | 描述 | | - | - | - | - | | `uuid` | string (UUID) | 否 | 内部证件标识符。 | | `document_type` | string | 是 | 高层级分组（`incorporation_certificate`、`shareholder_register` 等）。 | | `document_subtype` | string | 是 | 提供商特定的子类型。 | | `document_group` | string | 是 | `document_type` 的镜像（为清晰起见保留的别名）。 | | `file_url` | string (URL) | 是 | 清理后文件的预签名 URL。 | | `original_filename` | string | 是 | 上传时的原始文件名。 | | `file_size` | integer | 是 | 文件大小（以字节为单位）。 | | `status` | string | 否 | 单项证件状态（`FeatureStatusChoices`）。 | | `created_at` | string (ISO 8601) | 否 | 上传时间戳。 | | `cross_check_result` | object | 是 | 与公司登记/其他证件交叉比对的判定结果。 | | `document_metadata` | object | 是 | 与 POA 的 `document_metadata` 相同的过滤后元数据结构。 | | `description` | string | 是 | 审核员或系统提供的描述。 | | `is_requested` | boolean | 否 | 当工作流要求此证件时为 `true`。 | | `ocr_data` | object | 是 | 可用时的 OCR 提取字段。 | | `is_console_upload` | boolean | 否 | 当证件由控制台审核员上传时为 `true`（不计入汇总判定）。 | | `is_confirmed` | boolean | 否 | 当审核员已明确确认该证件时为 `true`。 | ```json theme={null} { "status": "Approved", "node_id": "first_kyb_documents", "items": [ { "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9", "document_type": "incorporation_certificate", "document_subtype": "registro_mercantil_extract", "document_group": "incorporation_certificate", "file_url": "https:///.../incorporation.pdf?signature=...", "original_filename": "incorporation_certificate.pdf", "file_size": 256412, "status": "Approved", "created_at": "2026-05-17T10:08:00Z", "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true }, "document_metadata": { "file_size": 256412, "content_type": "application/pdf", "is_signed": true, "is_tampered": false }, "description": null, "is_requested": true, "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" }, "is_console_upload": false, "is_confirmed": true } ], "groups": { "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }, "required_groups": ["incorporation_certificate", "shareholder_register"], "warnings": [] } ``` ### KYB 关键人员 在 KYB 工作流中按关键人员节点返回。在企业会话的 `GET /v3/session/{sessionId}/decision/` 中显示为 `key_people_checks[]`。源码来源：`kyb/serializers/kyb.py:967-1050`（`KeyPeopleCheckV3Serializer`）。 | 字段 | 类型 | 可为空 | 描述 | 示例 | | - | - | - | - | - | | `status` | string | 否 | 参见 [Status 枚举](#状态枚举参考)。 | `"Approved"` | | `node_id` | string \| null | 是 | 工作流节点标识符（V3）。 | `"first_key_people"` | | `registry` | object | 否 | 从公司登记中提取的 `{ officers[], beneficial_owners[] }`。高级管理人员遵循 `KYBPersonResponseSerializer`（`kyb/serializers/kyb.py:533-645`）；实际受益人遵循 `KYBBeneficialOwnerResponseSerializer`（`kyb/serializers/kyb.py:648-788`，增加了 `date_of_birth`、`country_of_birth`、`email`、`company_name`、`registration_number`、`entity_type`、`roles`、`ownership_min_shares`、`ownership_max_shares`、`child_beneficial_owners`、`effective_ownership_percent`）。两者均包含针对每个主体的 AML + KYC 扩充信息（`aml_status`、`kyc_status`、`kyc_session_url`、`kyc_session_id`、`verification_workflow_type`、`verification_workflow_id`、`verification_workflow_label`、`verification_workflow_features`、`didit_internal_id`、`kyc_document_type`、`kyc_nationality`、`kyc_liveness_passed`、`kyc_verified_at`、`kyc_aml_categories`、`kyc_notification_sent_at`）。 | `{ "officers": [...], "beneficial_owners": [...] }` | | `submitted` | object | 否 | `{ parties[] }`：企业通过关键人员流程确认/提交的条目（`source=USER` 的 `BusinessParty` 行）。每个主体遵循 `BusinessPartySubmissionResponseSerializer`（`kyb/serializers/party.py:146-194`）：`uuid`、`entity_type`、`source`、`name`、`first_name`、`last_name`、`company_name`、`registration_number`、`email`、`nationality`、`phone_number`、`date_of_birth`、`position`、`custom_fields`、`is_active`、`is_skipped`、`requires_verification`、`roles[]`（`{ role, ownership_percent, voting_percent }`）、`kyc_session_id`、`kyc_session_status`、`kyc_session_url`、`kyc_session_deleted`、`kyb_sub_session_id`、`kyb_sub_session_status`、`kyb_sub_session_url`、`kyb_sub_session_deleted`、`verification_workflow_type`、`verification_workflow_id`、`verification_workflow_label`、`verification_workflow_features`、`didit_internal_id`。`kyc_session_deleted` / `kyb_sub_session_deleted` 标记已被删除的子会话：其状态保持冻结在删除前的状态，因链接无法再解析，对应的 `*_session_url` 返回 `null`，且该主体不再阻塞父会话（检查结果将降级为 `In Review`）。可通过 [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](https://docs.didit.me/zh/sessions-api/update-data#跳过关键人员) 进行清除。 | `{ "parties": [...] }` | | `ubo_kyc_summary` | object | 是 | 已关联 KYC 的活跃实际受益人汇总计数：`{ total, approved, flagged, pending }`。当没有活跃实际受益人关联 KYC 时为 `null`。 | `{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }` | | `warnings` | array | 否 | 参见 [警告对象](#警告对象)。 | `[]` | ```json theme={null} { "status": "Approved", "node_id": "first_key_people", "registry": { "officers": [ { "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "designation": "Administrador único", "role": "Director", "nationality": "ESP", "appointment_date": "2018-03-22", "termination_date": null, "is_active": true, "address": "Calle Mayor 1, 28001 Madrid", "aml_status": "Approved", "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "verification_workflow_type": "kyc", "verification_workflow_id": "11111111-1111-1111-1111-111111111111", "verification_workflow_label": "KYB officer KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" } ], "didit_internal_id": "user-12345", "kyc_document_type": "Passport", "kyc_nationality": "ESP", "kyc_liveness_passed": true, "kyc_verified_at": "2026-05-17T10:10:11Z", "kyc_aml_categories": [], "kyc_notification_sent_at": "2026-05-15T08:00:00Z" } ], "beneficial_owners": [] }, "submitted": { "parties": [ { "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9", "entity_type": "person", "source": "USER", "name": "María García López", "first_name": "María", "last_name": "García López", "company_name": null, "registration_number": null, "email": "maria.garcia@example.com", "nationality": "ESP", "phone_number": null, "date_of_birth": "1990-05-12", "position": "Administrador único", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null } ], "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "kyc_session_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "verification_workflow_type": "kyc", "verification_workflow_id": "11111111-1111-1111-1111-111111111111", "verification_workflow_label": "KYB officer KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" } ], "didit_internal_id": "user-12345" } ] }, "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 }, "warnings": [] } ``` ## 决策层级字段 这些字段位于 `GET /v3/session/{sessionId}/decision/` 响应及 Webhook 的 `decision` 内部，与功能数组并列。 | 字段 | 类型 | 可为空 | 说明 | | - | - | - | - | | `status_override` | object | 是 | 审核员手动设置 `status` 后的 `{ overridden_at, automatic_status }`；当状态为自动判定时为 `null`。 | | `decision_trace` | object | 否 | 状态的达成过程：`status`、`decided_by`（`manual`、`automatic` 或 `investigator`）、`decided_at`、`automatic_status`、`terminal_node_id`、`actor`、`warning_counts` 以及 `status_warnings`。 | | `linked_records` | object | 是 | `same_face`、`earlier_verifications` 和 `networks` 摘要；无内容展示时为 `null`。 | | `biometric_retention` | object | 否 | `{ jurisdictions, deletes_at }`。`deletes_at` 为该会话的实时生物特征数据被删除的日期，尚未适用具体日期时为 `null`。 | | `database_validation_not_performed_reason` | object | 是 | 解释为何已配置的数据库核验未产生结果的 `{ code, message }`。 | | `assignee`、`waiting_since`、`sla_due_at` | object、datetime | 是 | 处理该会话的 Console 审核员及其审核计时器；除非会话处于 `In Review` 状态，否则该计时器为 `null`。 | | `shared_from_session`、`shared_from_session_number` | UUID、integer | 是 | 导入会话的源会话。 | | `sandbox_scenario` | string | 是 | 创建沙盒会话时所使用的场景。 | | `fraud_check` | object | 是 | Fraud Check API 结果；对其余所有会话均为 `null`。 | | `full_session_video`、`full_session_video_recorded_at` | URL、datetime | 是 | 录像及其录制时间。仅在您的组织启用了完整会话视频录制时返回。 | 有关如何读取这些字段，请参阅[获取会话](https://docs.didit.me/zh/sessions-api/retrieve-session.md#状态、决策追踪与审核字段)。 ## 生物识别同意 每个用户验证决策和会话 Webhook 都包含一个单一的 `biometric_consent` 对象（非数组）：说明该会话是否需要明确的生物识别同意、原因以及该答复的证据。当会话从未被评估时（例如不含人脸采集的工作流），该字段为 `null`。来源：`BiometricConsentDecisionSerializer`（`sessions/serializers/biometric_consent.py`）。何时出现此步骤以及各种情况的具体含义，请参阅[生物识别同意](https://docs.didit.me/zh/getting-started/biometric-consent.md)。 没有记录值的字段为 `null`，绝不会是空字符串。 | 字段 | 类型 | 说明 | | - | - | - | | `required` | boolean | 该会话是否必须收集明确的生物识别同意。绝不会变回 `false`。 | | `trigger` | string (enum) \| null | 为什么需要同意，或它是如何被满足的：`declared_state`、`ip_state`、`ip_unknown`、`document_issuer`、`forced`（应用的模式为 Always）、`customer_collected`（您在创建会话时发送了 `biometric_consent`）。在不需要时为 `null`。 | | `status` | string (enum) | `not_required`、`pending`（需要，但尚未给出）、`given`、`declined`（已记录拒绝；目前没有 Didit 界面提供拒绝选项）。 | | `given_at` | string (ISO 8601) \| null | 给出同意的时间。对于 `customer_collected`，为您发送的 `given_at`。 | | `declined_at` | string (ISO 8601) \| null | 记录拒绝的时间。 | | `text_version` | string \| null | 用户做出答复或您发送的同意文本的版本 ID。 | | `text_hash` | string \| null | 所显示确切文本（按其显示的语言）的 SHA-256（十六进制）。 | | `locale` | string \| null | 显示文本所用的语言。 | | `policy_url` | string \| null | 该步骤链接的生物识别数据政策。 | | `step` | string \| null | 用户做出答复时会话所在的工作流步骤（例如 `LIVENESS`）。 | | `node_id` | string \| null | 用户做出答复时会话所在的工作流图谱节点。 | | `ip_address` | string \| null | 做出答复的地址。 | | `ip_country_code` | string \| null | 答复 IP 的 ISO 3166-1 alpha-2 国家/地区代码。 | | `ip_state` | string \| null | 答复 IP 的 ISO 3166-2 细分代码（例如 `US-IL`）。 | | `ip_city` | string \| null | 答复 IP 的城市。 | | `user_agent` | string \| null | 答复请求的用户代理。 | | `detected_ip_address` | string \| null | 上次评估该要求时检测到的用户地址。当用户在另一台设备上做出答复时，可能与 `ip_address` 不同。 | | `detected_country_code` | string \| null | 检测到的 IP 的 ISO 3166-1 alpha-2 国家/地区代码。 | | `detected_state` | string \| null | 检测到的 IP 的 ISO 3166-2 细分代码。 | | `detected_city` | string \| null | 检测到的 IP 的城市。 | | `declared_state` | string \| null | 您申报的 ISO 3166-2 细分代码：`user_state`，或 `expected_details` 中美国地址的州。 | | `document_state` | string \| null | 签发该身份证件的 ISO 3166-2 细分代码，在证件采集时读取。 | | `jurisdictions` | array of string | 其生物识别法律涵盖该用户的美国州（USPS 代码，例如 `IL`）。当证据表明该用户在美国但未知具体州时为 `US`。若均不适用则为空。 | | `retention_months` | integer \| null | `jurisdictions` 中最短的生物特征保留期限（以月为单位）。若均不适用则为 `null`。 | | `reason` | string (enum) \| null | `BIOMETRIC_CONSENT_UNSUPPORTED_SDK`：需要同意，但低于 4.10.0 版本的原生 SDK（或未上报其版本的 SDK）在未执行该步骤的情况下采集了人脸；`status` 保持为 `pending`，如果用户稍后在托管流程中同意，则变为 `given`。`BIOMETRIC_CONSENT_DECLINED`：记录了拒绝（会替代 SDK 原因）。在其他情况下为 `null`，且在会话不需要同意时始终为 `null`。 | | `decline_reason` | string \| null | 当记录的拒绝导致会话终止时为 `BIOMETRIC_CONSENT_DECLINED`，否则为 `null`。 | | `face_data_deleted_at` | string (ISO 8601) \| null | 拒绝导致删除会话的人脸图像、视频和人脸模板的时间。除非记录了拒绝，否则为 `null`。 | 在伊利诺伊州由低于 4.10.0 版本的原生 SDK 提供服务、并在未执行该步骤的情况下采集了自拍照的会话： ```json theme={null} { "required": true, "trigger": "ip_state", "status": "pending", "given_at": null, "declined_at": null, "text_version": null, "text_hash": null, "locale": null, "policy_url": null, "step": null, "node_id": null, "ip_address": null, "ip_country_code": null, "ip_state": null, "ip_city": null, "user_agent": null, "detected_ip_address": "203.0.113.42", "detected_country_code": "US", "detected_state": "US-IL", "detected_city": "Chicago", "declared_state": null, "document_state": null, "jurisdictions": ["IL"], "retention_months": 36, "reason": "BIOMETRIC_CONSENT_UNSUPPORTED_SDK", "decline_reason": null, "face_data_deleted_at": null } ``` 使用出口位于美国境外的 VPN、并在托管流程中表示同意的用户： ```json theme={null} { "required": true, "trigger": "declared_state", "status": "given", "given_at": "2026-10-13T18:31:07.412000Z", "declined_at": null, "text_version": "bio-consent-2026-10-12", "text_hash": "9b2f0c5e4d8a7f61c3e2b4a5d6f7081923a4b5c6d7e8f90a1b2c3d4e5f6a7b8c", "locale": "en", "policy_url": "https://didit.me/legal/biometric-data-policy", "step": "LIVENESS", "node_id": "feature_liveness_1", "ip_address": "198.51.100.23", "ip_country_code": "ES", "ip_state": "ES-M", "ip_city": "Madrid", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1", "detected_ip_address": "198.51.100.23", "detected_country_code": "ES", "detected_state": "ES-M", "detected_city": "Madrid", "declared_state": null, "document_state": null, "jurisdictions": ["IL"], "retention_months": 36, "reason": null, "decline_reason": null, "face_data_deleted_at": null } ``` ## 状态枚举参考 两个相关的值空间共用 `status` 字段名。本页中的每个功能报告对象均使用功能级枚举；父会话的顶层 `status` 则使用更广泛的会话枚举。 ### 功能级状态 供每个报告对象的 `status` 字段使用。来源：`common/config/choices.py:343-348`（`FeatureStatusChoices`）。 | 值 | 含义 | | - | - | | `Not Finished` | 该功能已配置，但用户尚未完成。 | | `Approved` | 该功能通过了所有检查。 | | `Declined` | 该功能未通过至少一项硬性检查（参见带有 `log_type: "error"` 的 `warnings[]`）。 | | `In Review` | 该功能触发了软性未通过信号，正在等待人工审核（参见带有 `log_type: "warning"` 的 `warnings[]`）。 | | `Resub Requested` | 审核员已要求用户重新提交该功能。 | 当其对应步骤超时时，电话验证、邮箱验证和身份证件验证还可能呈现 `Expired`（`PhoneStatusChoices` 见 `common/config/choices.py:377-382`，`EmailStatusChoices` 见 `common/config/choices.py:434-439`）。 ### 会话级状态 供父会话的顶层 `status` 使用。来源：`common/config/choices.py:106-117`（`StatusChoices`）。 | 值 | 含义 | | - | - | | `Not Started` | 会话已创建，但用户尚未开始。 | | `In Progress` | 用户已开始流程；结果尚未最终确定。 | | `Approved` | 会话通过了所有检查。 | | `Declined` | 会话未通过至少一项硬性检查。 | | `In Review` | 会话正在等待人工审核。 | | `Expired` | 会话在完成前已过期。 | | `Abandoned` | 用户在未完成流程的情况下离开。 | | `Kyc Expired` | KYC 的有效期已过（用于重新验证流程）。 | | `Resubmitted` | 用户在先前被拒绝后重新提交；该会话已被较新的会话取代。 | | `Awaiting User` | 系统正在等待用户端操作（例如输入 OTP）。 | > [!TIP] > > 会话的终止状态值为 `Approved`、`Declined`、`In Review`、`Expired`、`Kyc Expired` 和 `Abandoned`。即使单个功能仍处于 `In Review` 状态，会话也可以得出其总体决策。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.