NFC 验证报告：芯片数据与真实性

概述

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）。每份报告都带有独立的 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[]。请参阅获取会话决策。
Webhooks：一旦 NFC 步骤生成数据，status.updated payload 就会包含相同的 nfc_verifications[] 数组。请参阅 Webhooks。
独立 NFC：有关直接提交芯片数据，请参阅 NFC 概述。

如果您的工作流包含被跳过或绕过的 NFC 步骤，决策 payload 还会带有一个顶层的 nfc_skip_reason 字段，明确说明跳过的原因：证件无芯片、签发国家/地区的证书不可用、设备没有 NFC 读取器、验证在没有原生 SDK 的情况下运行（浏览器无法访问 NFC）、无法从 MRZ 派生芯片访问密钥、个人番号卡无法通过 JPKI 读取，或者用户选择跳过。对于超出该分类的情况，它将保持为 null，最常见的是用户在尝试过程中放弃（报告状态为 Not Finished）或会话中 NFC 仍处于挂起状态。有关确切取值，请参阅跳过原因。

旧版文档曾提及单一的 nfc 字段。该结构在 v3 决策 endpoint 上并不存在；它仅出现在明确固定为 V2 Webhook 的目标中，并且在此类目标中还包含 chip_protocol 和 jpki。请始终读取 response.nfc_verifications[0] 并遍历该数组。

模式

权威的逐字段模式请参阅数据模型参考页面。以下字段与该权威模式保持一致。

字段	类型	说明
`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` 相同；参见跳过原因。
`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 字段。对于 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 警告。

状态值

状态	含义	下游影响
`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`	审核员请求重新提交该步骤。	用户重试后，新的尝试记录将替换此报告。

两项证书警告（DSC_CERTIFICATE_REVOKED、DSC_CERTIFICATE_EXPIRED）仅供参考：它们会出现在 warnings[] 中，但本身绝不会改变 NFC 的 status。完整行为矩阵请参阅 NFC 警告。

示例

Approved — 芯片已读取且密码学验证有效

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_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<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Declined — OCR 与芯片不匹配

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_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<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "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"
        }
      ]
    }
  ]
}

日本个人番号卡 (JPKI)

日本个人番号卡（My Number Card）在原生 SDK 中通过 JPKI 进行读取：用户输入卡片 PIN 码，卡片对一次性质询进行签名（参见工作原理）。其报告的 chip_protocol: "jpki"，并在 jpki 下包含证据。portrait_image、signature_image、chip_data、authenticity 和 certificate_summary 均为 null，因为该卡片不包含 ICAO 数据。

通过 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 步骤绝不会读取该号码。

示例: 个人番号卡读取

{
  "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 警告。

安全说明

NFC 芯片数据由签发机构签名，因此带有 sod_integrity: true 和 dg_integrity: true 的已通过报告是 Didit 所能提供的最高强度的身份凭证。请将签名的图像 URL（portrait_image、signature_image）视为短期有效：请及时下载并且不要公开缓存它们 — 当您需要获取新链接时，请重新请求决策。

身份认证

验证

监控

平台

NFC 验证报告：芯片数据与真实性

概述

在 API 响应中的位置

模式

状态值

示例

Approved — 芯片已读取且密码学验证有效

Declined — OCR 与芯片不匹配

日本个人番号卡 (JPKI)

JPKI 字段

示例: 个人番号卡读取

安全说明

相关内容

​概述

​在 API 响应中的位置

​模式

​状态值

​示例

​Approved — 芯片已读取且密码学验证有效

​Declined — OCR 与芯片不匹配

​日本个人番号卡 (JPKI)

​JPKI 字段

​示例: 个人番号卡读取

​安全说明

​相关内容

概述

在 API 响应中的位置

模式

状态值

示例

Approved — 芯片已读取且密码学验证有效

Declined — OCR 与芯片不匹配

日本个人番号卡 (JPKI)

JPKI 字段

示例: 个人番号卡读取

安全说明

相关内容