> ## 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 验证模块可能发出的各类警告，涵盖芯片读取跳过或未核验、OCR 与芯片不匹配及证书过期等，包含原因、严重程度与解决方法。 ## 概述 NFC 报告中的警告会标记 Didit 在读取和验证芯片时观察到的所有情况。它们会记录在 `nfc_verifications[]` 每个条目的 `warnings[]` 数组中（参见 [NFC 报告](https://docs.didit.me/zh/core-technology/nfc-verification/report-nfc-verification.md)），且 `feature` 设置为 `"NFC"`。每个条目均遵循通用的[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)结构：`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`。 每个警告包含三个层级： 1. **`risk` 代码**：您可以在代码中进行匹配的稳定标识符（如下列代码所示）。 2. **`log_type`**：`information`、`warning` 或 `error` 之一。它取决于您在工作流中为该风险配置的操作：**无操作** → `information`，**审核** → `warning`，**拒绝** → `error`。 3. **决策影响**：相同的配置操作还会决定 NFC 报告的 `status`：审核操作会将其变更为 `In Review`，拒绝操作会将其变更为 `Declined`。 有四个 NFC 风险支持以此方式配置（`SKIPPED_NFC_VALIDATION`、`NFC_CHIP_NOT_VERIFIED`、`NFC_TRUST_ANCHOR_MISSING`、`NFC_AND_OCR_DATA_NOT_SAME`），再加上五个 [Japan My Number Card](#日本个人编号卡-jpki) 风险，每个风险都有其单独的设置。两项证书风险（`DSC_CERTIFICATE_REVOKED`、`DSC_CERTIFICATE_EXPIRED`）**仅提供信息**：它们始终带有 `log_type: "information"`，且绝不会单独更改 NFC 状态。 以下是 NFC 模块生成的完整风险代码集。不存在其他 NFC 风险代码。 ## 产生的警告 | `risk` | 原因 | 严重程度 (`log_type`) | 是否影响状态？ | 处置建议 | | - | - | - | - | - | | `SKIPPED_NFC_VALIDATION` | 跳过了芯片读取：工作流允许跳过（`allow_nfc_skip`）且用户点击了跳过，或者客户端因无法读取 NFC 而跳过。确切原因记录在 `additional_data.skip_reason` 中（请参阅[跳过原因](#跳过原因)），并决定了警告的 `long_description`。 | 遵循**跳过 NFC 操作**设置（`skip_nfc_action`）：信息 / 警告 / 错误。 | 可配置：无操作、审核或拒绝。 | 如果您的策略要求使用 NFC，请将跳过操作设置为拒绝（或完全禁止跳过），并指导用户在支持 NFC 的设备上重试。否则，保留为“无操作”以回退至仅 OCR 验证。 | | `NFC_CHIP_NOT_VERIFIED` | 芯片已被读取，但由于已明确识别的信任锚缺失以外的原因，密码学验证失败。数据组哈希、SOD 签名或其他被动认证检查未能通过验证。 | 遵循**未验证芯片操作**设置（`unverified_chip_action`）。 | 可配置：无操作、审核或拒绝。 | 将其视为可能无效或被篡改的芯片。检查 `authenticity` 和 `certificate_summary.validation` 以了解具体哪项检查失败。 | | `NFC_TRUST_ANCHOR_MISSING` | 芯片的文档签名者证书（DSC）所属的国家签名证书颁发机构（CSCA）代次在 Didit 的信任库中不可用（`certificate_summary.validation.csca_missing` 为 `true`）。因此，Didit 无法建立 SOD 的信任链。 | 遵循**未验证芯片操作**设置（`unverified_chip_action`）。 | 可配置：无操作、审核或拒绝。 | 这是信任库覆盖不足，并非芯片被篡改的证据。通过您的后备检查审核该证件，并联系 Didit 支持团队提供签发国家/地区信息，以便对缺失的 CSCA 进行排查。 | | `NFC_AND_OCR_DATA_NOT_SAME` | 从芯片读取的 MRZ 与从证件可见面 OCR 识别出的 MRZ 不一致（在标准化并忽略 `<` 填充符后进行比对）。这是强烈的篡改信号。 | 遵循**数据不一致操作**设置（`inconsistent_data_action`），即控制身份证件验证数据一致性检查的同一设置。 | 可配置：无操作、审核或拒绝。 | 除非另有证明，否则应视为篡改；通常设置为拒绝。`additional_data` payload 包含 OCR MRZ 文本行（`ocr_mrz`，数组）和芯片 MRZ（`nfc_mrz`，单个字符串），供人工比对。 | | `DSC_CERTIFICATE_REVOKED` | 签署此芯片的文档签名者证书出现在签发国家/地区的证书吊销列表（CRL）中。 | 固定为 `information`。 | 否：本身绝不会改变 NFC 状态。 | 表明签名密钥可能已被泄露的强烈信号；如有需要，可通过您自己的逻辑将这些会话转入人工审核。请注意，芯片通常还会同时触发 `NFC_CHIP_NOT_VERIFIED`，该项是可配置的。 | | `DSC_CERTIFICATE_EXPIRED` | DSC 的有效期已过（`certificate_summary.validation.dsc_expired` 为 `true`）。 | 固定为 `information`。 | 否：本身绝不会改变 NFC 状态。 | 在较旧的证件中很常见。与吊销一样，过期的 DSC 也无法通过完整的 SOD 验证，因此会同时触发 `NFC_CHIP_NOT_VERIFIED` 并执行您配置的操作。 | | `JPKI_CERTIFICATE_INVALID` | 日本个人编号卡：从卡片读取的证书无法与该类型的 JPKI 认证机构建立证书链、超出有效期，或者不是该类型的个人编号卡证书。`additional_data.certificate_types` 列出了失败的证书；`jpki.certificates[].failure` 说明了原因。 | 遵循 `jpki_certificate_invalid_action`（默认拒绝）。 | 可配置：无操作、审核或拒绝。 | 视为无效或被篡改的卡片。过期的卡片证书也会落入此项：持卡人会在其所在的地方政府办理更新。 | | `JPKI_SIGNATURE_INVALID` | 日本个人编号卡：卡片对一次性挑战的签名无法通过其证书的验证，因此无法证明持有该卡片且知晓其 PIN 码。当 NFC 步骤在未读取任何卡片的情况下关闭时也会触发（此时 `additional_data.certificate_types` 为空）。 | 遵循 `jpki_signature_invalid_action`（默认拒绝）。 | 可配置：无操作、审核或拒绝。 | 切勿将读取结果作为证明。请要求用户使用实体卡重试。 | | `JPKI_CERTIFICATE_REVOKED` | 日本个人编号卡：吊销检查报告证书已被吊销，例如因为卡片挂失或持卡人的登记信息发生变更（`jpki.revocation_status` 为 `revoked`）。 | 遵循 `jpki_certificate_revoked_action`（默认拒绝）。 | 可配置：无操作、审核或拒绝。 | 切勿接受该卡片。 | | `JPKI_REVOCATION_UNCHECKED` | 日本个人编号卡：证书和签名已通过验证，但未获取到吊销状态结果（`jpki.revocation_status` 为 `unchecked`），因此无法排除卡片已被吊销的可能性。当证书链或签名已经验证失败时不会触发。 | 遵循 `jpki_revocation_unchecked_action`（默认审核）。 | 可配置：无操作、审核或拒绝。 | 请评估在没有吊销结果的情况下已验证卡片的价值，并相应地设置操作。 | | `JPKI_AND_OCR_DATA_NOT_SAME` | 日本个人编号卡：签名证书中的姓名、出生日期、性别或地址与同一张卡片照片中读取的数据不符。`additional_data.fields` 列出了不一致的属性，绝不会列出其具体值。 | 遵循 `jpki_inconsistent_data_action`（默认审核）。 | 可配置：无操作、审核或拒绝。 | 在做出决定之前，请比对 `jpki.attributes` 与身份证件验证数据。包含生僻字的姓名可能会有所不同，因为证书中可能包含替代字符（`jpki.attributes.name_substitute_characters`）。 | > [!NOTE] > > `SKIPPED_NFC_VALIDATION` 与 `NFC_CHIP_NOT_VERIFIED` 和 `NFC_TRUST_ANCHOR_MISSING` 互斥：只有在未跳过芯片读取时，才会评估芯片验证警告。这两个芯片验证警告之间也相互排斥。 ## 精确描述字符串 API 会针对每种风险返回以下精确的 `short_description` 和 `long_description` 字符串： | `risk` | `short_description` | `long_description` | | - | - | - | | `SKIPPED_NFC_VALIDATION` | 跳过 NFC 验证 | 视具体原因而定 — 请参阅[跳过原因](#跳过原因)。对于在跳过原因功能上线前记录的历史会话，将回退为“近场通信 (NFC) 芯片验证过程未完成，可能是由于技术问题或缺少 NFC 支持。”。 | | `NFC_CHIP_NOT_VERIFIED` | NFC 芯片未验证 | 近场通信 (NFC) 芯片未通过被动认证，原因非明确指出的缺少信任锚。芯片数据或签名可能无效或已被篡改。 | | `NFC_TRUST_ANCHOR_MISSING` | NFC 信任锚不可用 | 无法验证近场通信 (NFC) 芯片，因为签发国家/地区的国家签名证书颁发机构 (CSCA) 信任锚不可用。这是信任库覆盖范围存在缺口，而非芯片被篡改的证据。 | | `NFC_AND_OCR_DATA_NOT_SAME` | NFC 与 OCR 数据不一致 | 近场通信 (NFC) 芯片数据与 OCR 数据不匹配，表明证件可能被篡改或存在数据不一致。 | | `DSC_CERTIFICATE_REVOKED` | 证件签名者证书已吊销 | 用于对电子护照芯片数据进行签名的证件签名者证书 (DSC) 已被签发国家/地区的证书吊销列表 (CRL) 吊销，表明签名密钥可能已泄露。 | | `DSC_CERTIFICATE_EXPIRED` | 证件签名者证书已过期 | 用于对电子护照芯片数据进行签名的证件签名者证书 (DSC) 已过期，即证书已超过有效期。 | | `JPKI_CERTIFICATE_INVALID` | 个人编号卡证书无效 | 从个人编号卡芯片读取的证书无效：未链接到日本公钥基础设施 (JPKI) 认证机构、超出有效期，或者不是所请求类型的个人编号卡证书。 | | `JPKI_SIGNATURE_INVALID` | 个人编号卡签名无效 | 个人编号卡对一次性验证质询进行的签名未能通过卡片证书的验证，因此无法证明持有该卡并知晓其 PIN。 | | `JPKI_CERTIFICATE_REVOKED` | 个人编号卡证书已吊销 | 吊销检查报告显示从个人编号卡读取的证书已被吊销，例如由于卡片挂失或持卡人的登记信息发生变更。 | | `JPKI_REVOCATION_UNCHECKED` | 未检查个人编号卡吊销状态 | 个人编号卡的证书和签名已通过验证，但无法检查其吊销状态，因此无法排除卡片已被吊销的可能性。 | | `JPKI_AND_OCR_DATA_NOT_SAME` | 个人编号卡芯片与 OCR 数据不一致 | 个人编号卡签名证书中的姓名、出生日期、性别或地址与从卡片图像读取的数据 (OCR) 不匹配，表明可能存在证件冒用或数据不一致。 | ## 跳过原因 `SKIPPED_NFC_VALIDATION` 警告包含 `additional_data.skip_reason`，即七个固定代码之一，明确指出未运行 NFC 的具体原因（在存在跳过原因之前记录的会话中，`additional_data` 可能为 `null` — 处理历史决策时请将该字段视为可选）。相同的分类体系以 `nfc_skip_reason` 形式出现在决策 payload 的会话级别 — 包括根本无法运行 NFC 的会话（无芯片证件、Web 端集成），因此不存在任何 NFC 报告或警告。 | `skip_reason` | 含义 | `long_description` | | - | - | - | | `USER_SKIPPED` | 在兼容设备上提供了 NFC 选项，但用户选择跳过。 | 在兼容设备上提供了 NFC 芯片读取步骤，但用户选择跳过该步骤（工作流配置允许跳过）。 | | `DOCUMENT_WITHOUT_CHIP` | 证件设计中没有可读取的 NFC 芯片（非 ICAO 9303 电子证件）。 | 无法执行 NFC 验证，因为此证件没有可读取的 NFC 芯片：它不是 ICAO 9303 电子证件。 | | `CHIP_CERTIFICATE_UNAVAILABLE` | 芯片存在，但没有签发国家/地区的签名证书（CSCA）涵盖该证件的签发时期，因此无法验证签名。 | 无法执行 NFC 验证，因为涵盖此证件签发时期的签发国家/地区的签名证书（CSCA）不可用，因此无法验证芯片签名。 | | `DEVICE_WITHOUT_NFC` | 原生 SDK 报告手机没有可用的 NFC 读取器。 | 无法执行 NFC 验证，因为用户的设备报告其没有可用的 NFC 读取器。 | | `INTEGRATION_WITHOUT_NFC_ACCESS` | 验证在没有原生 SDK 的情况下运行（例如在 Web 浏览器中），无法访问手机的 NFC 读取器。 | 无法执行 NFC 验证，因为验证未通过原生移动端 SDK 运行，因此无法访问手机的 NFC 读取器（Web 浏览器无法读取 NFC 芯片）。 | | `MRZ_KEY_UNAVAILABLE` | 无法根据证件的 MRZ 派生芯片访问密钥（BAC/PACE 种子）。 | 无法执行 NFC 验证，因为无法根据证件的机读区（MRZ）派生芯片访问密钥。 | | `JPKI_UNAVAILABLE` | 该证件为日本个人编号卡（My Number Card），其芯片通过 JPKI 读取，但 JPKI 在本次验证中不可用：未启用，或应用的移动端原生 SDK 版本无法读取个人编号卡。在浏览器中验证的个人编号卡将获得 `INTEGRATION_WITHOUT_NFC_ACCESS`，在没有 NFC 功能的手机上验证将获得 `DEVICE_WITHOUT_NFC`，与其他芯片相同。 | 无法执行 NFC 验证，因为此个人编号卡需通过 JPKI 读取，而 JPKI 在本次验证中不可用：未启用，或应用的 SDK 无法读取个人编号卡。 | > [!NOTE] > > 只有当客户端到达 NFC 步骤并明确跳过该步骤时（通常为 `USER_SKIPPED`，或在扫描时发现读取器不可用而导致的 `DEVICE_WITHOUT_NFC`），才会存在 NFC 报告及其 `SKIPPED_NFC_VALIDATION` 警告。如果 NFC 步骤在提供之前就已被绕过 — 无芯片证件、缺少证书、未报告 NFC 功能、无法读取 MRZ 密钥、JPKI 不可用 — 则不会创建任何报告或警告，原因仅显示在会话级别的 `nfc_skip_reason` 字段中，不会影响会话状态。 ## 配置 三项工作流设置控制 NFC 警告的路由方式。每一项都可以设置为**无操作**、**审核**或**拒绝**： 1. **跳过 NFC 操作**（`skip_nfc_action`）— 适用于 `SKIPPED_NFC_VALIDATION`。仅在启用 `allow_nfc_skip` 时才会向用户提供跳过选项。 2. **未验证芯片操作**（`unverified_chip_action`）— 同时适用于 `NFC_CHIP_NOT_VERIFIED` 和 `NFC_TRUST_ANCHOR_MISSING`，因此会话状态行为保持一致，同时风险代码说明验证失败的原因。 3. **数据不一致操作**（`inconsistent_data_action`）— 适用于 `NFC_AND_OCR_DATA_NOT_SAME`。这是身份证件验证所使用的同一数据不一致设置。 两个 `DSC_CERTIFICATE_*` 风险没有操作设置 — 它们始终仅提供信息。日本个人编号卡风险还有另外五项设置，列在下一节中。 ## 日本个人编号卡 (JPKI) 日本个人编号卡通过 JPKI 而不是 ICAO 9303 读取（`chip_protocol: "jpki"`），因此上述 ICAO 风险绝不会针对该卡触发。其读取操作会引发以下五种风险，每种风险在 NFC 节点上都有对应的设置： | 设置 | 风险 | 默认值 | | - | - | - | | `jpki_certificate_invalid_action` | `JPKI_CERTIFICATE_INVALID` | 拒绝 | | `jpki_signature_invalid_action` | `JPKI_SIGNATURE_INVALID` | 拒绝 | | `jpki_certificate_revoked_action` | `JPKI_CERTIFICATE_REVOKED` | 拒绝 | | `jpki_revocation_unchecked_action` | `JPKI_REVOCATION_UNCHECKED` | 审核 | | `jpki_inconsistent_data_action` | `JPKI_AND_OCR_DATA_NOT_SAME` | 审核 | 跳过个人编号卡读取会引发 `SKIPPED_NFC_VALIDATION` 并遵循 `skip_nfc_action`，与其他芯片一样。有关读取工作原理，请参阅[日本个人编号卡 (JPKI)](https://docs.didit.me/zh/core-technology/nfc-verification/overview.md#日本个人编号卡（jpki）)。 > [!WARNING] > > 通过 JPKI 读取个人编号卡的功能尚未在生产环境中启用。在该功能启用之前，个人编号卡将跳过 NFC 步骤，跳过原因为 `JPKI_UNAVAILABLE`，且不会引发这些风险中的任何一种。 ## 示例 ### 审核中 — 芯片无法验证 ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_CHIP_NOT_VERIFIED", "additional_data": null, "log_type": "warning", "short_description": "NFC chip not verified", "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.", "node_id": "nfc_primary" }, { "feature": "NFC", "risk": "DSC_CERTIFICATE_EXPIRED", "additional_data": null, "log_type": "information", "short_description": "Document Signer Certificate expired", "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.", "node_id": "nfc_primary" } ] } ``` 在此处，未验证芯片操作被设置为 Review，因此 `NFC_CHIP_NOT_VERIFIED` 带有 `log_type: "warning"`，且 NFC 报告的状态为 `In Review`。DSC 已过期的条目仅供参考。 ### 已拒绝 — 芯片 / OCR 不一致 ```json theme={null} { "warnings": [ { "feature": "NFC", "risk": "NFC_AND_OCR_DATA_NOT_SAME", "additional_data": { "ocr_mrz": ["P