> ## 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 인증 보고서**는 전자여권, 전자 신분증 또는 기타 ICAO 9303 전자 문서 등의 NFC 칩에서 Didit이 읽고 검증한 내용을 담고 있습니다. 여기에는 칩의 인적 사항 데이터, 암호학적 무결성 검사(SOD 및 Data Group 해시), 발급 국가에서 사용한 문서 서명자 인증서(DSC) 요약 정보가 포함됩니다. 이 보고서는 사용자가 워크플로에서 NFC 단계를 완료한 후 생성됩니다. Didit은 사용자 기기에서 칩의 Data Group을 읽고, 발급 국가의 CSCA 인증서와 대조하여 문서 보안 객체(SOD) 서명을 검증하며, SOD가 서명한 값과 각 Data Group 해시를 대조하고, 문서의 인쇄면에서 OCR로 추출한 MRZ와 칩의 MRZ를 상호 대조합니다. 일본 마이넘버카드는 대신 JPKI를 통해 판독됩니다(`chip_protocol: "jpki"`). 해당 보고서에는 `jpki` 아래에 인증서, 서명, 폐기 및 명의인 데이터 검사가 포함되며, ICAO 필드는 `null`로 유지됩니다. 자세한 내용은 [일본 마이넘버카드(JPKI)](#일본-마이넘버카드-jpki)를 참고하세요. 각 보고서는 전체 세션 상태와 무관하게 NFC 단계만의 처리 결과를 반영하는 자체 `status`를 가집니다. * **승인됨** — 칩을 성공적으로 읽었으며, 발생한 경고 중 해당 단계를 검토 또는 거부로 라우팅하도록 구성된 경고가 없습니다. * **검토 중** — 구성된 작업이 **검토**인 경고가 하나 이상 발생했습니다(예: 미검증 칩에 대한 작업이 검토로 설정된 경우의 `NFC_CHIP_NOT_VERIFIED` 또는 `NFC_TRUST_ANCHOR_MISSING`, 기본 작업이 적용된 `JPKI_REVOCATION_UNCHECKED`). * **거부됨** — 구성된 작업이 **거부**인 경고가 하나 이상 발생했습니다(예: 데이터 불일치 작업이 거부로 설정된 경우의 `NFC_AND_OCR_DATA_NOT_SAME`). * **완료되지 않음** — 사용자가 NFC 단계를 완료하지 않았습니다. 칩 판독이 중단되었거나 기기가 NFC를 지원하지 않았습니다. * **재제출 요청됨** — 검토자가 사용자에게 재제출을 요청했습니다. 이 보고서는 새로운 시도로 대체됩니다. ## API 응답에서 표시되는 위치 NFC 보고서는 `nfc_verifications[]` 배열 내에 제공되며, 단일 `nfc` 객체가 아닌 **항상 JSON 배열** 형태로 전달됩니다. 워크플로에서 NFC를 두 번 이상 실행하는 경우(예: 스텝업 플로우) 여러 항목이 나타날 수 있으며, 각 항목은 고유한 `node_id`를 가집니다. * **세션 결정 API** — `GET /v3/session/{sessionId}/decision/`의 최상위 수준에서 `nfc_verifications[]`로 나타납니다. [세션 결정 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)를 참고하세요. * **Webhook** — `status.updated` payload에는 NFC 단계에서 데이터가 생성된 후 동일한 `nfc_verifications[]` 배열이 포함됩니다. [Webhook](https://docs.didit.me/ko/integration/webhooks.md)을 참고하세요. * **독립형 NFC** — 직접 칩을 제출하는 방식에 대해서는 [NFC 개요](https://docs.didit.me/ko/core-technology/nfc-verification/overview.md)를 참고하세요. 워크플로에 생략되거나 우회된 NFC 단계가 포함된 경우, 결정 payload의 최상위 수준에 정확한 이유를 명시하는 `nfc_skip_reason` 필드도 함께 제공됩니다. 문서에 칩이 없음, 발급 국가의 인증서를 사용할 수 없음, 기기에 NFC 리더기가 없음, 네이티브 SDK 없이 인증이 실행됨(브라우저에서 NFC 접근 불가), MRZ에서 칩 액세스 키를 파생할 수 없음, 마이넘버카드를 JPKI를 통해 읽을 수 없음, 사용자가 건너뛰기를 선택함 등이 여기에 해당합니다. 해당 분류 체계에 속하지 않는 결과(가장 흔하게는 시도 중간에 중단한 사용자(보고서 상태 `Not Finished`) 또는 NFC가 아직 대기 중인 세션)의 경우 `null`로 유지됩니다. 정확한 값은 [건너뛰기 사유](https://docs.didit.me/ko/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/ko/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/ko/core-technology/nfc-verification/warnings-nfc-verification.md#건너뛰기-이유)를 참조하십시오. | | `chip_protocol` | `"icao"` \| `"jpki"` | 칩을 읽은 방법입니다. `icao`: ICAO 9303 전자여권 또는 전자 신분증 칩입니다. `jpki`: 일본 마이넘버카드로, 결과는 `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`). `csca_missing`은 DSC의 발급 CSCA 트러스트 앵커를 사용할 수 없는 경우 `true`입니다. SOD를 로드할 수 없거나 단계를 건너뛴 경우 `null`입니다. | | `warnings[]` | array | 모듈 수준의 경고 배열로, 각각 `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`를 포함합니다. [NFC 경고](https://docs.didit.me/ko/core-technology/nfc-verification/warnings-nfc-verification.md)를 참조하십시오. | ## 상태 값 | 상태 | 의미 | 후속 영향 | | - | - | - | | `Approved` | 칩을 읽었으며 Review 또는 Decline 작업이 트리거된 경고가 없습니다. 경고가 발생했으나 구성된 작업이 "작업 없음"인 경우도 포함됩니다. | 성공한 NFC 검사로 간주되며, 이것만으로 세션이 검토 중으로 전환되지 않습니다. | | `In Review` | 구성된 작업이 Review인 경고가 발생했습니다(설정에 따라 `SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` 또는 `JPKI_*` 경고 중 하나). | 검토자가 조치를 취할 때까지 세션도 `In Review`로 이동합니다. | | `Declined` | 구성된 작업이 Decline인 경고가 발생했습니다. | 워크플로를 충족하는 승인된 다른 분기가 없는 한 세션이 거부됩니다. | | `Not Finished` | 사용자가 NFC 단계를 중단했거나, 기기에서 NFC를 지원하지 않거나, 칩 읽기가 완료되지 않았습니다. | NFC 분기에서 결과를 생성하지 못했습니다. 워크플로 대체 수단을 확인하십시오. | | `Resub Requested` | 검토자가 이 단계의 재제출을 요청했습니다. | 사용자가 재시도하면 새로운 시도가 이 보고서를 대체합니다. | > [!NOTE] > > 두 가지 인증서 경고(`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`)는 정보성 경고입니다. `warnings[]`에 나타나지만 그 자체로 NFC `status`를 변경하지는 않습니다. 전체 동작 매트릭스는 [NFC 경고](https://docs.didit.me/ko/core-technology/nfc-verification/warnings-nfc-verification.md)를 참조하십시오. ## 예시 ### 승인됨 — 칩을 읽었으며 암호학적으로 유효함 ```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를 통한 마이넘버카드 읽기는 프로덕션 환경에서 아직 활성화되지 않았습니다. 활성화되기 전까지 마이넘버카드는 `JPKI_UNAVAILABLE` 건너뛰기 사유와 함께 NFC 단계를 건너뜁니다. ### JPKI 필드 | 필드 | 유형 | 설명 | | - | - | - | | `jpki.certificate_types` | array of `"user_authentication"` \| `"signature"` | 읽은 카드 인증서입니다. `user_authentication`(4자리 PIN)은 항상 읽으며, `signature`(서명용 PIN)는 NFC 노드의 `jpki_request_attributes` 설정이 켜져 있을 때(기본값) 읽습니다. | | `jpki.chain_valid` | boolean | 모든 인증서가 해당 유형의 JPKI 인증 기관(CA)으로 체인 연결되고, 유효 기간 내에 있으며, 해당 유형의 마이넘버카드 인증서인 경우 `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`), `attributes`가 `null`인 경우를 포함하여 비교할 수 없는 경우 `null`입니다. | | `jpki.mismatched_attributes` | 문자열 배열 | 사진 데이터와 일치하지 않는 속성(`full_name`, `date_of_birth`, `gender`, `address`) 목록이며, 해당 속성의 값은 포함되지 않습니다. | 보고서에는 인증서 자체, 일련번호, 서명, 또는 NFC 단계에서 전혀 읽지 않는 카드의 12자리 개인번호(마이넘버)가 절대 포함되지 않습니다. ### 예시: 마이넘버카드 읽기 ```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/ko/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/ko/core-technology/nfc-verification/warnings-nfc-verification.md) — 전체 경고 열거형, 원인 및 해결 방법. * [webhook](https://docs.didit.me/ko/integration/webhooks.md) — `status.updated` 이벤트를 수신하면 NFC 보고서를 받습니다. * [데이터 모델 — NFC 인증](https://docs.didit.me/ko/reference/data-models.md#nfc-인증) — 모든 필드가 포함된 표준 스키마. * [지원되는 문서](https://docs.didit.me/ko/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.