> ## 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. # NFC 验证报告：芯片数据与真实性 > 了解如何解读 Didit 的 NFC / 电子护照报告：状态、芯片数据、证书真实性、在 API 响应中的位置以及示例 payload。 ## 概述 **NFC 验证报告**记录了 Didit 从电子护照、电子身份证或其他 ICAO 9303 电子证件的 NFC 芯片中读取并核验的内容。它包括芯片的个人资料、密码学完整性检查（SOD 和数据组哈希），以及签发国家/地区使用的证件签名者证书（DSC）摘要。 该报告在用户完成工作流中的 NFC 步骤后生成。Didit 会在用户设备上读取芯片的数据组（Data Group），对照签发国家/地区的 CSCA 证书验证证件安全对象（SOD）签名，对照 SOD 签名的值检查每个数据组哈希，并将芯片的 MRZ 与从证件可见表面 OCR 识别出的 MRZ 进行交叉比对。 日本个人番号卡（My Number Card）则通过 JPKI 读取（`chip_protocol: "jpki"`）：其报告在 `jpki` 下包含证书、签名、吊销和持有人数据检查，而 ICAO 字段保持为 `null`。请参阅 [日本个人番号卡（JPKI）](#日本个人番号卡-jpki)。 每份报告都带有独立的 `status`（独立于整体会话状态），反映 NFC 这一单一步骤的处理结果： * **Approved**（已通过）：芯片已成功读取，且触发的警告中没有任何一项被配置为将该步骤路由至审核或拒绝。 * **In Review**（审核中）：至少触发了一项其配置操作为 **Review**（审核）的警告（例如，当未验证芯片操作设置为 Review 时触发的 `NFC_CHIP_NOT_VERIFIED` 或 `NFC_TRUST_ANCHOR_MISSING`，或者采用默认操作的 `JPKI_REVOCATION_UNCHECKED`）。 * **Declined**（已拒绝）：至少触发了一项其配置操作为 **Decline**（拒绝）的警告（例如，当数据不一致操作设置为 Decline 时触发的 `NFC_AND_OCR_DATA_NOT_SAME`）。 * **Not Finished**：用户未完成 NFC 步骤；芯片读取已放弃或设备不支持 NFC。 * **Resub Requested**：审核员要求用户重新提交；该报告将被新的尝试所取代。 ## 在 API 响应中的位置 NFC 报告包含在 `nfc_verifications[]` 数组中，且**始终是一个 JSON 数组**，绝不是单一的 `nfc` 对象。当工作流多次运行 NFC（例如升级流程）时，会出现多个条目；每个条目都带有自己的 `node_id`。 * **会话决策 API**：在 `GET /v3/session/{sessionId}/decision/` 顶层显示为 `nfc_verifications[]`。请参阅[获取会话决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。 * **Webhooks**：一旦 NFC 步骤生成数据，`status.updated` payload 就会包含相同的 `nfc_verifications[]` 数组。请参阅 [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)。 * **独立 NFC**：有关直接提交芯片数据，请参阅 [NFC 概述](https://docs.didit.me/zh/core-technology/nfc-verification/overview.md)。 如果您的工作流包含被跳过或绕过的 NFC 步骤，决策 payload 还会带有一个顶层的 `nfc_skip_reason` 字段，明确说明跳过的原因：证件无芯片、签发国家/地区的证书不可用、设备没有 NFC 读取器、验证在没有原生 SDK 的情况下运行（浏览器无法访问 NFC）、无法从 MRZ 派生芯片访问密钥、个人番号卡无法通过 JPKI 读取，或者用户选择跳过。对于超出该分类的情况，它将保持为 `null`，最常见的是用户在尝试过程中放弃（报告状态为 `Not Finished`）或会话中 NFC 仍处于挂起状态。有关确切取值，请参阅[跳过原因](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md#跳过原因)。 > [!NOTE] > > 旧版文档曾提及单一的 `nfc` 字段。该结构在 v3 决策 endpoint 上**并不存在**；它仅出现在明确固定为 V2 Webhook 的目标中，并且在此类目标中还包含 `chip_protocol` 和 `jpki`。请始终读取 `response.nfc_verifications[0]` 并遍历该数组。 ## 模式 权威的逐字段模式请参阅[数据模型](https://docs.didit.me/zh/reference/data-models.md#nfc-验证)参考页面。以下字段与该权威模式保持一致。 | 字段 | 类型 | 说明 | | - | - | - | | `status` | `"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"` | NFC 步骤状态（详见上文说明）。 | | `node_id` | string \| null | 生成此报告的工作流图节点。用于在多步骤工作流中区分两次不同的 NFC 检查。 | | `is_nfc_skipped` | boolean | 当该 NFC 步骤被明确跳过而非读取时为 `true`。 | | `skip_reason` | string \| null | 步骤被跳过的原因 — 仅在 `is_nfc_skipped` 为 `true` 时设置。其值与会话级的 `nfc_skip_reason` 相同；参见[跳过原因](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md#跳过原因)。 | | `chip_protocol` | `"icao"` \| `"jpki"` | 芯片读取方式。`icao`：ICAO 9303 电子护照或电子身份证芯片。`jpki`：日本个人编号卡（My Number Card），其结果位于 `jpki` 下；此时下方的 ICAO 字段（`portrait_image`、`signature_image`、`chip_data`、`authenticity`、`certificate_summary`）为 `null`。在跳过的步骤上也会设置。 | | `jpki` | object \| null | 个人编号卡读取所证明的内容；参见 [JPKI 字段](#jpki-字段)。对于 ICAO 芯片、跳过的步骤以及未读取任何卡片即关闭的步骤，该值为 `null`。 | | `portrait_image` | string (signed URL) \| null | 从芯片中提取的头像照片（DG2）。短期有效的预签名链接 — 请及时下载；如需获取新 URL，请重新拉取决策结果。 | | `signature_image` | string (signed URL) \| null | 芯片中的持卡人签名图像（DG7，如果存在）。同样具有短期预签名的特性。 | | `chip_data` | object \| null | 解析自芯片的个人身份数据的扁平对象。成功读取后始终存在：`dgs`（读取的数据组列表）、`surname`、`name`、`country`、`nationality`、`birth_date`（`YYYY-MM-DD`）、`expiry_date`（`YYYY-MM-DD`）、`sex`（`M`/`F`）、`document_type`（MRZ 证件代码，例如 `P`）、`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`）；否则这些键将**不存在**，而不是 null。在跳过 NFC 步骤时为 `null`。 | | `authenticity` | object \| null | ICAO 被动认证结果，见下文。对于 JPKI 读取，该值为 `null`。 | | `authenticity.sod_integrity` | boolean | 当 SOD 签名可链接到有效的签发国家/地区 CSCA 且 DSC 既未被吊销也未过期时为 `true`。 | | `authenticity.dg_integrity` | boolean | 当每个数据组的哈希值与 SOD 签署的值一致时为 `true`。值为 `false` 表示芯片数据遭到篡改或读取不完整。 | | `certificate_summary` | object \| null | 签署此芯片的 DSC 摘要：`issuer`、`subject`、`serial_number`、`not_valid_before`、`not_valid_after`（时间戳格式为 `YYYY-MM-DD HH:MM:SS`），以及包含各项单独检查结果的 `validation` 对象（`csca_verified`、`csca_missing`、`dsc_revoked`、`dsc_expired`、`csca_expired`）。当 DSC 的签发 CSCA 信任锚点不可用时，`csca_missing` 为 `true`。当无法加载 SOD 或步骤被跳过时为 `null`。 | | `warnings[]` | array | 模块级警告，每项包含 `feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description` 和 `node_id` — 参见 [NFC 警告](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md)。 | ## 状态值 | 状态 | 含义 | 下游影响 | | - | - | - | | `Approved` | 芯片已读取且未触发配置为审核（Review）或拒绝（Decline）操作的警告 — 包括触发了警告但其配置的操作为“无操作（No action）”的情况。 | 算作一次成功的 NFC 检查；其本身不会将检查会话推入人工审核。 | | `In Review` | 触发了配置操作为审核的警告（取决于您的设置，可能包括 `SKIPPED_NFC_VALIDATION`、`NFC_CHIP_NOT_VERIFIED`、`NFC_TRUST_ANCHOR_MISSING`、`NFC_AND_OCR_DATA_NOT_SAME` 或某个 `JPKI_*` 警告）。 | 会话也将变更为 `In Review`，直至审核员进行处理。 | | `Declined` | 触发了配置操作为拒绝的警告。 | 会话被拒绝，除非工作流中存在另一条已通过的分支满足条件。 | | `Not Finished` | 用户放弃了 NFC 步骤、设备缺少 NFC 支持或芯片读取未完成。 | NFC 分支未产生结果；请检查工作流的回退配置。 | | `Resub Requested` | 审核员请求重新提交该步骤。 | 用户重试后，新的尝试记录将替换此报告。 | > [!NOTE] > > 两项证书警告（`DSC_CERTIFICATE_REVOKED`、`DSC_CERTIFICATE_EXPIRED`）仅供参考：它们会出现在 `warnings[]` 中，但本身绝不会改变 NFC 的 `status`。完整行为矩阵请参阅 [NFC 警告](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md)。 ## 示例 ### Approved — 芯片已读取且密码学验证有效 ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": "https:///.../epassport/_face.jpg?signature=...", "signature_image": "https:///.../epassport/_signature.jpg?signature=...", "chip_data": { "dgs": ["DG1", "DG2", "DG7", "DG11"], "surname": "DOE", "name": "JOHN", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-15", "expiry_date": "2030-01-01", "sex": "M", "document_type": "P", "document_number": "AAB000123", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "3", "optional_data_hash": "", "final_hash": "4", "mrz_string": "P/.../epassport/_face.jpg?signature=...", "signature_image": null, "chip_data": { "dgs": ["DG1", "DG2"], "surname": "DOE", "name": "JOHN", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-15", "expiry_date": "2030-01-01", "sex": "M", "document_type": "P", "document_number": "AAB000254", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "6", "optional_data_hash": "", "final_hash": "6", "mrz_string": "P [!WARNING] > > 通过 JPKI 读取个人番号卡的功能尚未在生产环境中启用。在此之前，个人番号卡将跳过 NFC 步骤，跳过原因为 `JPKI_UNAVAILABLE`。 ### JPKI 字段 | 字段 | 类型 | 描述 | | - | - | - | | `jpki.certificate_types` | array of `"user_authentication"` \| `"signature"` | 读取到的卡片证书。`user_authentication`（4 位 PIN 码）始终会被读取；当 NFC 节点的 `jpki_request_attributes` 设置开启（默认开启）时，会读取 `signature`（签名 PIN 码）。 | | `jpki.chain_valid` | boolean | 当每个证书均链接到对应类型的 JPKI 证书颁发机构、处于有效期内且属于该类型的个人番号卡证书时，返回 `true`。 | | `jpki.signature_valid` | boolean | 当卡片对一次性质询生成的所有签名均验证通过时，返回 `true`。卡片仅在输入 PIN 码后才会签名，因此这证明了持卡人持有卡片并知晓 PIN 码。 | | `jpki.revocation_status` | `"good"` \| `"revoked"` \| `"unchecked"` | `good`：所有证书均确认未被吊销。`revoked`：证书已被吊销，例如卡片已挂失。`unchecked`：无法获取吊销状态应答，因此无法排除卡片已被吊销的可能性；绝不视为 `good`。仅在证书链和签名均有效后才会核查吊销状态。 | | `jpki.ca_generation` | string \| null | 签发这些证书的 JPKI 证书颁发机构的代次，例如 `"2023"`。当没有证书链接到该机构时为 `null`。 | | `jpki.certificate_expires_at` | string (ISO 8601) \| null | 读取到的证书中最早的到期时间。 | | `jpki.certificates[]` | array | 每个读取到的证书对应一个条目：`type`、`chain_valid`、`signature_valid`、`ca_generation`、`not_valid_before`、`not_valid_after` 以及 `failure`。当证书链有效时 `failure` 为 `null`，否则为 `unreadable_certificate`、`untrusted_issuer`、`expired`、`not_yet_valid`、`wrong_policy`（非该类型的个人番号卡证书）或 `key_usage` 之一。 | | `jpki.attributes` | object \| null | 签名证书链有效后从中获取的持卡人数据：`full_name`（登记姓名，通常为日文字符）、`date_of_birth`（`YYYY-MM-DD`）、`gender`（`M`、`F` 或 `null`）、`address`，以及 `name_substitute_characters` / `address_substitute_characters`（用于标记因超出标准字符集而被替代字符替换的字符；若无则为 `null`）。当未请求签名证书或其证书链无效时为 `null`。 | | `jpki.attributes_match_ocr` | boolean \| null | 当属性与同一张卡片照片中读取的数据匹配时为 `true`；任一项不一致时为 `false`（`JPKI_AND_OCR_DATA_NOT_SAME`）；无法进行比对时为 `null`，包括 `attributes` 为 `null` 的情况。 | | `jpki.mismatched_attributes` | array of string | 与照片数据不一致的属性列表（`full_name`、`date_of_birth`、`gender`、`address`），绝不包含其具体数值。 | 报告绝不包含证书本身、证书序列号、签名或卡片的 12 位个人番号（My Number），NFC 步骤绝不会读取该号码。 ### 示例: 个人番号卡读取 ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": null, "signature_image": null, "chip_data": null, "is_nfc_skipped": false, "skip_reason": null, "chip_protocol": "jpki", "jpki": { "certificate_types": ["user_authentication", "signature"], "chain_valid": true, "signature_valid": true, "revocation_status": "good", "ca_generation": "2023", "certificate_expires_at": "2029-05-15T14:59:59Z", "certificates": [ { "type": "user_authentication", "chain_valid": true, "signature_valid": true, "ca_generation": "2023", "not_valid_before": "2024-06-03T01:12:40+00:00", "not_valid_after": "2029-05-15T14:59:59+00:00", "failure": null }, { "type": "signature", "chain_valid": true, "signature_valid": true, "ca_generation": "2023", "not_valid_before": "2024-06-03T01:12:40+00:00", "not_valid_after": "2029-05-15T14:59:59+00:00", "failure": null } ], "attributes": { "full_name": "山田 太郎", "date_of_birth": "1990-05-15", "gender": "M", "address": "東京都千代田区千代田1番1号", "name_substitute_characters": null, "address_substitute_characters": null }, "attributes_match_ocr": true, "mismatched_attributes": [] }, "authenticity": null, "certificate_summary": null, "warnings": [] } ] } ``` 如果在读取时吊销核查不可用，在默认设置下，同一报告将显示 `revocation_status: "unchecked"`，附带 `JPKI_REVOCATION_UNCHECKED` 警告，且 `status: "In Review"`。参见 [NFC 警告](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md#日本个人编号卡-jpki)。 ## 安全说明 NFC 芯片数据由签发机构签名，因此带有 `sod_integrity: true` 和 `dg_integrity: true` 的已通过报告是 Didit 所能提供的最高强度的身份凭证。请将签名的图像 URL（`portrait_image`、`signature_image`）视为短期有效：请及时下载并且不要公开缓存它们 — 当您需要获取新链接时，请重新请求决策。 ## 相关内容 * [NFC 警告](https://docs.didit.me/zh/core-technology/nfc-verification/warnings-nfc-verification.md) — 完整的警告枚举、产生原因及补救措施。 * [Webhooks](https://docs.didit.me/zh/integration/webhooks.md) — 监听 `status.updated` 事件以接收 NFC 报告。 * [数据模型 — NFC 验证](https://docs.didit.me/zh/reference/data-models.md#nfc-验证) — 包含所有字段的权威模式规范。 * [支持的证件](https://docs.didit.me/zh/core-technology/nfc-verification/supported-documents-nfc-verification.md) — Didit 可通过 NFC 读取的电子证件。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.