NFC 验证警告与错误代码

概述

NFC 报告中的警告会标记 Didit 在读取和验证芯片时观察到的所有情况。它们会记录在 nfc_verifications[] 每个条目的 warnings[] 数组中（参见 NFC 报告），且 feature 设置为 "NFC"。每个条目均遵循通用的警告对象结构：feature、risk、additional_data、log_type、short_description、long_description、node_id。每个警告包含三个层级：

risk 代码：您可以在代码中进行匹配的稳定标识符（如下列代码所示）。
log_type：information、warning 或 error 之一。它取决于您在工作流中为该风险配置的操作：无操作 → information，审核 → warning，拒绝 → error。
决策影响：相同的配置操作还会决定 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 风险，每个风险都有其单独的设置。两项证书风险（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`）。

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 无法读取个人编号卡。

只有当客户端到达 NFC 步骤并明确跳过该步骤时（通常为 USER_SKIPPED，或在扫描时发现读取器不可用而导致的 DEVICE_WITHOUT_NFC），才会存在 NFC 报告及其 SKIPPED_NFC_VALIDATION 警告。如果 NFC 步骤在提供之前就已被绕过 — 无芯片证件、缺少证书、未报告 NFC 功能、无法读取 MRZ 密钥、JPKI 不可用 — 则不会创建任何报告或警告，原因仅显示在会话级别的 nfc_skip_reason 字段中，不会影响会话状态。

配置

三项工作流设置控制 NFC 警告的路由方式。每一项都可以设置为无操作、审核或拒绝：

跳过 NFC 操作（skip_nfc_action）— 适用于 SKIPPED_NFC_VALIDATION。仅在启用 allow_nfc_skip 时才会向用户提供跳过选项。
未验证芯片操作（unverified_chip_action）— 同时适用于 NFC_CHIP_NOT_VERIFIED 和 NFC_TRUST_ANCHOR_MISSING，因此会话状态行为保持一致，同时风险代码说明验证失败的原因。
数据不一致操作（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)。

通过 JPKI 读取个人编号卡的功能尚未在生产环境中启用。在该功能启用之前，个人编号卡将跳过 NFC 步骤，跳过原因为 JPKI_UNAVAILABLE，且不会引发这些风险中的任何一种。

示例

审核中 — 芯片无法验证

{
  "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 不一致

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_AND_OCR_DATA_NOT_SAME",
    "additional_data": {
      "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
      "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
    },
    "log_type": "error",
    "short_description": "NFC and OCR data not same",
    "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
    "node_id": "nfc_primary"
  }
]
}

在此处，数据不一致操作被设置为 Decline，因此该警告带有 log_type: "error"，且 NFC 报告的状态为 Declined。请注意，ocr_mrz 是 MRZ 行数组，而 nfc_mrz 是芯片中单个拼接的 MRZ 字符串。

审核中: 无吊销结果的个人编号卡

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "JPKI_REVOCATION_UNCHECKED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "My Number Card revocation status not checked",
    "long_description": "The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.",
    "node_id": "nfc_primary"
  }
]
}

在此处，jpki_revocation_unchecked_action 保持其默认值 Review，因此该警告带有 log_type: "warning"，且 NFC 报告的状态为 In Review。卡片本身已通过验证：jpki.chain_valid 和 jpki.signature_valid 均为 true。

警告类型

每项风险都会根据您应用的配置分配严重程度。这三种严重程度分别为：

身份认证

验证

监控

平台

NFC 验证警告与错误代码

概述

产生的警告

精确描述字符串

跳过原因

配置

日本个人编号卡 (JPKI)

示例

审核中 — 芯片无法验证

已拒绝 — 芯片 / OCR 不一致

审核中: 无吊销结果的个人编号卡

警告类型

相关内容

​概述

​产生的警告

​精确描述字符串

​跳过原因

​配置

​日本个人编号卡 (JPKI)

​示例

​审核中 — 芯片无法验证

​已拒绝 — 芯片 / OCR 不一致

​审核中: 无吊销结果的个人编号卡

​警告类型

​相关内容

概述

产生的警告

精确描述字符串

跳过原因

配置

日本个人编号卡 (JPKI)

示例

审核中 — 芯片无法验证

已拒绝 — 芯片 / OCR 不一致

审核中: 无吊销结果的个人编号卡

警告类型

相关内容