> ## 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.

# 신분증 인증 경고 및 오류 코드

> Didit 신분증 인증 모듈이 생성하는 모든 경고를 안내합니다. 자동 거부 트리거, 위험 그룹, 불일치 및 위변조 코드의 원인과 해결 방법을 확인하세요.

## 개요

신분증 인증 보고서의 경고는 Didit이 문서를 판독하고 검증하는 과정에서 관찰한 모든 조건을 표시합니다. 경고는 `id_verifications[]`의 각 항목에 있는 `warnings[]` 배열에 포함되며([신분증 인증 보고서](https://docs.didit.me/ko/core-technology/id-verification/report-id-verification.md) 참조), [데이터 모델 — 경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체)에 설명된 형태(`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`)를 갖습니다.

모든 경고에는 세 가지 계층이 있습니다.

1. **`risk` 코드** — 코드에서 대조할 수 있는 안정적인 식별자입니다.
2. **`log_type`** — 평가 시점에 설정에서 해당 위험에 할당한 작업에 따라 결정됩니다. **거부 → `error`**, **검토 → `warning`**, 그 외 → `information`.
3. **결정에 미치는 영향** — 워크플로의 구성 가능한 위험 그룹에 의해 설정됩니다. 동일한 `risk` 코드라도 애플리케이션 구성 방식에 따라 **승인**, **검토** 또는 **거부**로 라우팅될 수 있습니다.

## 자동 거부 조건

워크플로에서 다음 위험은 항상 신분증 보고서(및 세션)를 `Declined` 상태로 만듭니다. 이 설정은 변경할 수 없습니다.

| 위험 | 트리거 |
| - | - |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 제출된 문서 유형이 애플리케이션의 허용 문서 목록에 없습니다. `additional_data`에 `issuing_state`, `document_type`, `document_subtype`, `document_region`, `document_region_with_subtype`이 포함되어 있으므로 워크플로에서 해당 문서를 정확히 활성화할 수 있습니다. |
| `DOCUMENT_EXPIRED` | 캡처 시점에 문서의 만료일이 지났습니다. |
| `PORTRAIT_IMAGE_NOT_DETECTED` | 문서에서 인물 사진 이미지를 찾을 수 없습니다. |
| `ID_DOCUMENT_IN_BLOCKLIST` | 문서가 애플리케이션의 차단 목록에 있는 항목과 일치합니다. |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | 문서 캡처 중에 전면 카메라로 촬영한 셀피가 얼굴 차단 목록의 얼굴과 일치합니다. |
| `AGE_BELOW_MINIMUM` | 적응형 연령 확인 워크플로 전용: 추출된 연령이 최소 연령 미만입니다. |
| `AGE_NOT_DETECTED` | 적응형 연령 확인 워크플로 전용: 문서에서 연령을 추출할 수 없습니다. |

**독립형 OCR API**의 경우 무조건 거부되는 항목 세트는 `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`입니다. 워크플로에서는 최소 연령이 구성 가능하며(기본값 거부), 세 가지 문서 라이브니스 위험은 임계값 기반으로 작동합니다(아래 참조).

해당 API에서는 구성 가능한 위험에 검토 판정 대신 `DECLINE` 또는 `NO_ACTION`을 요청 파라미터로 지정합니다. API가 반환할 수 있는 한 가지 검토 결과는 구성할 수 없습니다. 요청된 문서 라이브니스 검사에서 사용 가능한 점수가 산출되지 않으면 응답은 `DOCUMENT_LIVENESS_NOT_COMPUTED` 경고와 함께 `In Review`가 됩니다([문서 라이브니스](#문서-라이브니스-위변조) 참조).

| 요청 파라미터 | 위험 | 기본값 |
| - | - | - |
| `invalid_mrz_action` | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | `DECLINE` |
| `inconsistent_data_action` | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | `DECLINE` |
| `expiration_date_not_detected_action` | `EXPIRATION_DATE_NOT_DETECTED` | `NO_ACTION` |
| `critical_field_occlusion_action` | `CRITICAL_FIELD_OCCLUSION_DETECTED` | `DECLINE` |
| `document_or_personal_number_format_mismatch_action` | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` | `NO_ACTION` |

## 구성 가능한 인증 설정

Didit 콘솔에서 나머지 신분증 위험은 워크플로별(그래프 워크플로에서는 노드별)로 **승인**, **검토** 또는 **거부**로 라우팅할 수 있는 설정으로 그룹화됩니다:

| 그룹 | 위험 | 기본 작업 |
| - | - | - |
| **최소 연령** | `MINIMUM_AGE_NOT_MET` | 거부 |
| **최대 연령** | `MAXIMUM_AGE_EXCEEDED` | 거부 |
| **중복 사용자** | `POSSIBLE_DUPLICATED_USER` (문서 번호가 문서 허용 목록에 있는 경우 건너뜜) | 승인(정보) |
| **유효하지 않은 코드** | `QR_NOT_DETECTED`, `BARCODE_NOT_DETECTED`, `QR_VALIDATION_FAILED`, `BARCODE_VALIDATION_FAILED` | 승인(정보) |
| **유효하지 않은 MRZ** | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED` | 승인(정보) |
| **데이터 불일치** | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`, `DOCUMENT_SIDES_MISMATCH`, `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | 승인(정보) |
| **검증 실패** | `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT`, `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED` | 검토 |
| **예상 세부 정보 불일치** | `FULL_NAME_MISMATCH_WITH_PROVIDED`, `GENDER_MISMATCH_WITH_PROVIDED`, `DOB_MISMATCH_WITH_PROVIDED`, `COUNTRY_MISMATCH_WITH_PROVIDED`, `NATIONALITY_MISMATCH_WITH_PROVIDED`, `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | 검토 |
| **만료일 미감지** | `EXPIRATION_DATE_NOT_DETECTED` | 승인(정보) |
| **문서 또는 개인 번호 형식 불일치** | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` (하나의 공유 작업) | 검토 |
| **중요 필드 가림** | `CRITICAL_FIELD_OCCLUSION_DETECTED` | 검토 |
| **구문 분석되지 않은 주소** | `UNPARSED_ADDRESS` | 승인(정보) |
| **이미지 품질** | `IMAGE_TOO_BLURRY`, `IMAGE_TOO_DARK`, `IMAGE_TOO_BRIGHT` (위험당 하나의 작업) | 승인(정보) |
| **인물 사진이 없는 문서** | `DOCUMENT_HAS_NO_PORTRAIT` | 검토 |
| **무음 캡처의 중복된 얼굴** | `FRONT_CAMERA_DUPLICATED_FACE`, `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` (하나의 공유 작업) | 승인(정보) |
| **다른 이름의 무음 캡처 중복** | `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` (중복된 얼굴 결과를 더 엄격하게만 만들 수 있음) | 검토 |
| **다른 생년월일의 무음 캡처 중복** | `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` (중복된 얼굴 결과를 더 엄격하게만 만들 수 있음) | 검토 |

무음 캡처 중복 및 차단 목록 위험은 [문서 캡처 중 촬영된 셀피에 대한 얼굴 검색](https://docs.didit.me/ko/core-technology/face-search/overview.md#문서-촬영-중-캡처된-셀피)에서 비롯됩니다. 이 검색은 기본값인 **무음 캡처 얼굴 검색**(`document_selfie_face_search_enabled`)이 켜져 있고 라이브니스 단계에서 얼굴 검색이 꺼져 있지 않은 동안 실행되며, 그렇지 않으면 이 6가지 위험 중 어느 것도 발생하지 않습니다.

두 가지 신분증 위험군은 승인/검토/거부 토글 대신 **임계값 기반**으로 작동합니다:

* **문서 라이브니스** — `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`. 각 사기 유형에는 자체 거부 및 검토 임계값이 있습니다. 거부 임계값 미만 점수 → `error` + 거부됨, 검토 임계값 미만 점수 → `warning` + 검토 중, 그 외 → `information`.
* **카메라 간 얼굴 대조** — `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`, `document_selfie_portrait_match_decline_threshold` / `document_selfie_portrait_match_review_threshold`에 의해 제어됩니다.

### 문서 라이브니스 임계값 구성

워크플로 편집기에서 이러한 임계값은 신분증 인증 단계의 **위조** 탭에 있으며, 사기 유형별로 카드 하나씩 제공됩니다: **초상화 교체**, **인쇄본**, **화면 캡처**.

각 검사는 문서가 얼마나 진짜처럼 보이는지에 따라 `0`부터 `100`까지의 점수를 문서에 부여합니다. **점수가 높을수록 문서가 진짜일 가능성이 높습니다.** 카드의 두 값은 이 척도를 세 구간으로 나눕니다:

| 점수 | 결과 |
| - | - |
| **거부** 값 미만 | `error`, 세션이 거부됨 |
| **거부** 값 이상 및 **검토** 값 미만 | `warning`, 세션이 검토 중 상태가 됨 |
| **검토** 값 이상 | `information`, 검사 통과 |

어느 한 값을 올리면 검사가 더 엄격해집니다. 즉, 더 많은 세션이 그 위의 구간에 속하게 됩니다. 값을 낮추면 더 많은 세션이 통과합니다. 편집기에서는 거부 값이 검토 값을 초과할 수 없습니다. API를 통해 검토 값보다 높은 거부 값을 설정하면 검토 중 구간이 제거됩니다.

워크플로에서 값을 설정하지 않았을 때 사용되는 플랫폼 기본값:

| 사기 유형 | 거부 기준(미만) | 검토 기준(미만) | 워크플로 구성 키 |
| - | - | - | - |
| 초상화 교체 | `35` | `70` | `document_liveness_portrait_replace_decline_threshold`, `document_liveness_portrait_replace_review_threshold` |
| 인쇄본 | `35` | `77` | `document_liveness_printed_copy_decline_threshold`, `document_liveness_printed_copy_review_threshold` |
| 화면 캡처 | `30` | `70` | `document_liveness_screen_replay_decline_threshold`, `document_liveness_screen_replay_review_threshold` |

기본값에서 시작하여 한 번에 하나의 값씩 조정하세요. 각 카드에는 기본값과 **기본값으로 재설정** 버튼이 표시되므로 언제든지 기본값으로 되돌릴 수 있습니다. 또한 편집기는 다음과 같은 구성에 대해 경고합니다:

* **검토 값이 `100`인 경우.** 완벽한 점수만 통과하므로 거의 모든 세션이 검토 중으로 이동하거나 거부됩니다.
* **거부 값이 `100`인 경우.** 완벽한 점수만 거부를 피할 수 있으므로 거의 모든 세션이 거부됩니다.
* **두 값이 모두 `0`인 경우.** 어떤 점수에도 플래그가 지정되지 않으므로 검사가 실질적으로 꺼집니다.

두 값을 동일한 숫자로 설정하면 검토 중 구간이 제거됩니다. 해당 점수 미만은 거부되고 그 외의 모든 점수는 통과합니다.

동일한 문서에 대해 **인쇄본**과 **화면 캡처**가 모두 플래그를 지정하는 경우, `SCREEN_CAPTURE_DETECTED`만 보고됩니다.

카메라 간 얼굴 대조도 경계값에서 한 가지 차이점을 제외하고는 동일한 방식을 사용합니다. 즉, 검토 임계값과 동일한 점수는 계속 검토 중으로 이동합니다.

4가지 신분증 위험은 설정할 수 없으며 임계값을 기반으로 작동하지도 않습니다. `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST`는 항상 **검토**로 라우팅됩니다. 차단 목록의 얼굴과 유사하지만 일치 여부가 확정되지 않은 셀피는 사람이 판단해야 하며, 자동으로 거부되거나 무시되지 않습니다. `BARCODE_SIGNATURE_INVALID`도 항상 **검토**로 라우팅됩니다. 바코드에 포함된 발급 기관 서명이 암호학적 검증에 실패할 때만 트리거되므로, 위조가 입증된 신분증이 무시되는 설정은 없습니다. `DOCUMENT_BACK_SIDE_NOT_AVAILABLE`은 항상 **정보** 수준이며 결정에 영향을 미치지 않습니다. 제시된 신분증의 속성이 아니라 Didit 문서 카탈로그의 제한 사항을 보고하므로, 실제 소지자가 거부되거나 검토 대상으로 전달되는 설정은 없습니다.
`FRONT_CAMERA_CAPTURED_DOCUMENT`는 항상 **검토**로 라우팅됩니다.
신분증을 스캔하는 동안 촬영된 전면 카메라 프레임에 사람이 없고 신분증만 나타날 때만 트리거되므로, 누가 신분증을 들고 있었는지 알 수 없는 촬영 건은 항상 사람에게 전달됩니다.
신분증 촬영 셀피 대조(`is_document_selfie_portrait_match_enabled`)가 활성화되어 있을 때마다 확인됩니다.

## 생성되는 경고

`collect_ocr_logs`, 문서 캡처 흐름, `process_ocr_logs_and_get_status`를 기준으로 검증되었습니다. 아래의 짧은 설명은 API가 반환하는 정확한 `short_description` 문자열입니다.

### 문서 인식 및 품질

| 위험 | 짧은 설명 | 원인 | 심각도 |
| - | - | - | - |
| `COULD_NOT_RECOGNIZE_DOCUMENT` | Could not validate Document | 제출된 문서의 진위 여부나 유효성을 시스템에서 확인할 수 없습니다. 주로 이미지 품질이 낮거나 지원되지 않는 문서 유형인 경우에 해당합니다. 인식되지 않은 처리 실패의 대체 항목으로도 사용됩니다. | 구성 가능 — Invalid Validation, 기본값 검토 |
| `COULD_NOT_DETECT_DOCUMENT_TYPE` | Could not detect document type | 문서 앞면이 알려진 공식 문서 디자인과 높은 신뢰도로 일치하지 않거나, OCR 엔진이 문서 계열(여권 vs 신분증 vs 운전면허증)을 분류할 수 없습니다. 유효한 데이터가 포함되어 있지만 레이아웃이 어떠한 공식 디자인과도 일치하지 않는 문서(수정되었거나 컴퓨터로 생성된 문서 또는 아직 지원되지 않는 새로운 디자인)가 여기에 해당합니다. 이 경고가 발생하면 `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`은 표시되지 않습니다(유형을 알 수 없으므로 "지원되지 않음"은 모순되기 때문입니다). | 구성 가능 — Invalid Validation, 기본값 검토 |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Document not supported for your application | 인식된 문서 유형이 애플리케이션의 허용 목록에 없습니다. `additional_data`에 국가, 문서 유형, 하위 유형 및 지역별 하위 유형이 포함됩니다. | `error` — **자동 거부** |
| `DOCUMENT_EXPIRED` | Document expired | 캡처 시점: 문서의 만료일이 지났습니다(`error`, 자동 거부). 승인 후: 지속적인 만료 모니터링을 통해 승인된 문서의 날짜가 지나면 `log_type: "warning"`과 함께 이 경고가 추가되고 보고서 상태가 `Expired`로 변경됩니다. | 캡처 시 `error`, 모니터링 시 `warning` |
| `DOCUMENT_SIDES_MISMATCH` | Document sides mismatch | 앞면과 뒷면 이미지가 동일한 문서에 속하지 않습니다. | 구성 가능 — Data Inconsistency, 기본값 정보 |
| `DOCUMENT_BACK_SIDE_NOT_AVAILABLE` | Back side not available for this document | 워크플로에서 양면을 요청했고 앞면이 인식되었으나, Didit의 문서 카탈로그에 해당 문서의 뒷면이 등록되어 있지 않아 앞면만 수집할 수 있었습니다. 보고서의 증거 자료는 단면으로 제공됩니다. 제시된 문서 자체에는 문제가 없으며 소지자에게 재촬영을 요청하지 않고, 다시 스캔해도 뒷면을 추가할 수 없습니다. `additional_data`에는 인식된 `front_document_name`이 포함됩니다. | `information` — 결정에 영향을 주지 않음 |
| `PORTRAIT_IMAGE_NOT_DETECTED` | Portrait image not detected | 인물 사진이 포함되어야 하는 문서에서 인물 사진을 찾을 수 없습니다(사용자가 인물 사진이 없는 면을 먼저 업로드한 경우 지연됨). | `error` — **자동 거부** |
| `DOCUMENT_HAS_NO_PORTRAIT` | Document has no portrait | 인식된 문서 계열의 어느 면에도 인물 사진이 없습니다(일부 거주 허가증, 건강 카드, 등록증, 세무 카드 및 특정 운전면허증/신분증). 이는 문서 유형 자체의 카탈로그 수준 특성이며 이미지 품질 문제가 아닙니다. 문서를 다시 스캔해도 결과는 달라지지 않습니다. | 구성 가능 — Document Without Portrait, 기본값 검토 |
| `IMAGE_TOO_BLURRY` / `IMAGE_TOO_DARK` / `IMAGE_TOO_BRIGHT` | Document image is too blurry / too dark / too bright | 이미지 품질 게이트에서 업로드를 거부했습니다(사용자에게 재촬영 요청). `additional_data`에 실패한 `side`가 포함됩니다. 재촬영에 성공하면 이전 경고는 제거되며, 사용자가 완전히 차단되지 않도록 마지막 허용 시도에서는 게이트를 건너뜁니다. | 구성 가능 — 위험별 Image Quality 작업, 기본값 정보 |

> [!NOTE]
>
> 캡처 흐름은 `IMAGE_RESOLUTION_TOO_LOW`, `DOCUMENT_NOT_FULLY_VISIBLE`, `IMAGE_QUALITY_TOO_LOW`, `DOCUMENT_OCCLUSION_DETECTED`(손가락이나 물체가 인쇄된 텍스트를 물리적으로 가리고 있는 것으로 판단됨) 피드백 코드로도 업로드를 거부할 수 있습니다. 각 코드는 SDK에서 재촬영을 요청하며 보고서에 고유한 위험으로 기록되고 Image Quality 설정에 따라 처리 경로가 결정됩니다. `DOCUMENT_OCCLUSION_DETECTED`와 `IMAGE_QUALITY_TOO_LOW`는 단일 작업을 공유합니다. 이 항목들은 *캡처* 상태를 나타내므로 재촬영에 성공하면 경고가 지워집니다. 가려진 필드가 최종 결정에 영향을 미쳐야 하는지 여부는 아래의 무결성 검증 항목인 `CRITICAL_FIELD_OCCLUSION_DETECTED`에서 별도로 처리되며, 결정 시점에 발생하고 기본값은 검토입니다.

> [!TIP]
>
> 워크플로에서 문서의 인물 사진 대신 얼굴 대조를 신원 확인의 기준으로 삼는 경우, **Document Without Portrait**를 거부(Decline)로 설정하는 것을 권장합니다. 그렇지 않으면 인물 사진이 없는 문서 계열이 비교 대상 없이 얼굴 대조 단계로 넘어가게 됩니다.

### 필드 추출

| 위험 | 짧은 설명 | 원인 | 심각도 |
| - | - | - | - |
| `NAME_NOT_DETECTED` | First name and/or last name not detected | 이름 및/또는 성을 추출할 수 없습니다. 소지자가 법적으로 이름을 하나만 사용하는 경우(이름이 하나뿐인 국가이거나 MRZ 자체에 이름이 하나만 있는 경우)로서 하나 이상의 이름 값이 추출된 경우는 제외됩니다. | 구성 가능 — Invalid Validation, 기본값 검토 |
| `DATE_OF_BIRTH_NOT_DETECTED` | Date of birth not detected | 생년월일이 포함되어야 하는 문서에서 생년월일을 추출할 수 없습니다. | 구성 가능 — Invalid Validation, 기본값 검토 |
| `DOCUMENT_NUMBER_NOT_DETECTED` | Document number not detected | 문서 번호와 개인 번호 중 어느 것도 추출할 수 없습니다. | 구성 가능 — Invalid Validation, 기본값 검토 |
| `EXPIRATION_DATE_NOT_DETECTED` | Expiration date not detected | 만료일이 포함되어야 하는 문서에서 만료일을 추출할 수 없습니다. | 구성 가능 — Expiration Date Not Detected, 기본값 정보 |
| `INVALID_DATE` | Invalid Date | 문서의 날짜(생년월일 또는 만료일)를 유효한 날짜로 파싱할 수 없습니다. 현재 캡처 흐름에서는 저장된 경고 대신 업로드 중 재촬영 안내로 표시됩니다. 이 코드는 Invalid Validation 라우팅 그룹에 유지되며 이전 세션에 나타날 수 있습니다. | 구성 가능 — Invalid Validation, 기본값 검토 |
| `DOCUMENT_NUMBER_FORMAT_MISMATCH` | 신분증 번호 형식 불일치 | 신분증 번호가 이 신분증 유형에 설정된 예상 형식과 일치하지 않습니다. `additional_data`에 `expected_format` 및 `extracted_value`가 포함됩니다. | 구성 가능 — Format Mismatch, 기본값 Review |
| `PERSONAL_NUMBER_FORMAT_MISMATCH` | 개인 번호 형식 불일치 | 개인 번호가 이 신분증 유형에 설정된 예상 형식과 일치하지 않습니다. | 구성 가능 — Format Mismatch, 기본값 Review |
| `CRITICAL_FIELD_OCCLUSION_DETECTED` | 신분증의 중요 필드가 가려짐 | 가림 감지 검사에서 촬영본의 중요 인쇄 필드(식별 번호, 이름, 생년월일 또는 만료일)가 물리적으로 가려진 것으로 보고되었습니다. 이는 촬영 품질 신호가 아니라 신분증 무결성 신호입니다. 보고서 대조에 사용되는 바로 그 번호를 가리는 것은 수정되거나 변조된 신분증의 전형적인 모습입니다. 가려진 필드에서 읽은 값은 확인된 값으로 반환되지 않고 추출 데이터에서 제외되므로, 일반적으로 일치하는 `*_NOT_DETECTED` 위험이 이 경고와 함께 발생합니다. `additional_data`의 `covered_fields`에는 가려진 필드 이름이 포함되며, 이 중 하나가 `document_number` 또는 `personal_number`에 사용되는 경우 `covered_identifiers`도 포함됩니다. | 구성 가능 — Critical Field Covered, 기본값 Review |

### MRZ, QR, 바코드

MRZ의 신뢰성이 떨어지는 것으로 알려진 신분증 유형의 경우 세 가지 MRZ 위험이 모두 건너뛰어집니다.

| 위험 | 짧은 설명 | 원인 | 심각도 |
| - | - | - | - |
| `MRZ_NOT_DETECTED` | MRZ가 감지되지 않음 | MRZ가 있어야 하는 신분증에서 MRZ를 찾을 수 없습니다. | 구성 가능 — Invalid MRZ, 기본값 information |
| `MRZ_VALIDATION_FAILED` | MRZ가 유효하지 않음 | MRZ 체크섬/형식 검증에 실패했습니다. 주로 저품질 촬영본에서 발생하며, 변조를 나타낼 수도 있습니다. | 구성 가능 — Invalid MRZ, 기본값 information |
| `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | MRZ와 OCR로 추출된 데이터 간에 불일치가 있음 | MRZ 내용이 VIZ(시각 영역) OCR과 일치하지 않습니다. 변조 가능성이 있습니다. | 구성 가능 — Data Inconsistency, 기본값 information |
| `QR_NOT_DETECTED` | QR이 감지되지 않음 | QR 코드가 있어야 하는 신분증에서 QR 코드를 찾을 수 없습니다. | 구성 가능 — Invalid Code, 기본값 information |
| `QR_VALIDATION_FAILED` | QR 검증 실패 | QR 내용을 신분증의 나머지 부분과 대조하여 검증할 수 없습니다. | 구성 가능 — Invalid Code, 기본값 information |
| `BARCODE_NOT_DETECTED` | 바코드가 감지되지 않음 | 바코드가 있어야 하는 신분증에서 바코드를 찾을 수 없습니다. | 구성 가능 — Invalid Code, 기본값 information |
| `BARCODE_VALIDATION_FAILED` | 바코드 검증 실패 | 바코드 내용을 신분증의 나머지 부분과 대조하여 검증할 수 없습니다. | 구성 가능 — Invalid Code, 기본값 information |
| `BARCODE_SIGNATURE_INVALID` | 바코드 서명 유효하지 않음 | 바코드에 발급 기관의 디지털 서명이 포함되어 있으나 해당 서명이 검증되지 않았습니다. 즉, 바코드의 데이터가 해당 기관이 서명한 데이터가 아니며, 이는 위조되거나 변조된 신분증을 나타냅니다. 현재 **프랑스 2D-Doc (ANTS)** 바코드에 대해 확인되며, 서명이 검증되면 Didit은 MRZ 교차 검증 없이도 필드를 승격할 수 있습니다. AAMVA(미국/캐나다 운전면허증 및 신분증) 서명은 감지 및 기록만 되며 아직 적용되지 않습니다. | 고정 - Review(자체 작업 그룹 `invalid_barcode_signature_action`, 아직 콘솔/API에서 구성 불가) |
| `DATA_INCONSISTENT` | 신분증의 OCR 데이터가 일치하지 않음 | 신분증의 서로 다른 부분에서 추출된 데이터가 일치하지 않습니다(일반적으로 동일 신분증의 앞면과 뒷면 간 불일치). | 구성 가능 — Data Inconsistency, 기본값 information |

> [!NOTE]
>
> 바코드 서명 검증은 현재 ANTS 2D-Doc 바코드가 발급 기관에 의해 서명된 프랑스 국가 신분증을 지원합니다. `BARCODE_SIGNATURE_INVALID`는 서명 검사 자체가 payload를 거부할 때만 발생합니다. 서명이 없는 바코드, Didit의 신뢰 저장소에 아직 없는 기관이 서명한 바코드 또는 서명을 디코딩할 수 없는 바코드는 인증되지 않은 데이터로 처리되어 이전과 마찬가지로 이 위험을 발생시키지 않고 MRZ 및 인쇄된 텍스트와 대조하여 검증됩니다.
>
> 미국 및 캐나다 운전면허증(AAMVA) 바코드는 암호학적으로 검증되지 않습니다. 해당 지역에서는 디지털 서명이 선택 사항이며 관할권에 따라 다르고, 검증 키를 공개하는 관할권이 없으므로 Didit은 payload에 서명이 포함되어 있는지만 감지하고 기록합니다. 서명 자체는 검사되지 않습니다. 현재 AAMVA 서명 실패는 위험 신호가 아닙니다. 변조된 AAMVA payload는 변조로 인해 바코드가 MRZ 또는 인쇄/OCR 데이터와 불일치할 때만 `BARCODE_VALIDATION_FAILED`로 나타납니다. 그 외 내부적으로 일관된 payload에 위조된 서명이 있는 경우에는 어떠한 신호도 발생하지 않고 통과됩니다.
>
> `BARCODE_SIGNATURE_INVALID` 발생 시 사용자에게 재촬영을 요청하지 않습니다. payload와 일치하지 않는 서명은 사진을 더 잘 찍는다고 해결될 수 없기 때문입니다.

### 신원 일치

| 위험 | 짧은 설명 | 원인 | 심각도 |
| - | - | - | - |
| `ID_DOCUMENT_IN_BLOCKLIST` | 신분증이 차단 목록에 있음 | 해당 신분증이 차단 목록에 등록된 신분증(동일한 생년월일, 발급 국가 및 정확히 일치하는 신분증 번호) 또는 수동으로 차단 목록에 등록된 신분증 번호와 일치합니다. `additional_data`에 차단 목록 세션 참조가 포함됩니다. | `error` — **자동 거부** |
| `ID_DOCUMENT_IN_ALLOWLIST` | 신분증이 허용 목록에 있음 | 신분증 번호가 신분증 허용 목록과 일치하여 중복 사용자 작업이 건너뛰어졌습니다. `additional_data`에 `document_number`가 포함됩니다. | `information` |
| `POSSIBLE_DUPLICATED_USER` | 다른 세션의 중복 사용자 가능성 | 애플리케이션 내의 다른 신분증에 해당 세션의 상태와 관계없이 다른 사용자(`vendor_data`)에 속한 동일한 생년월일, 동일한 발급 국가 및 매우 유사한 성명이 등록되어 있습니다. `additional_data`에 중복 세션 참조가 포함됩니다. | 구성 가능 — Duplicated User, 기본값 information |
| `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | 신분증 이름이 승인된 다른 신분증과 다름 | 이 신분증의 이름이 동일한 사용자에 대해 이전에 승인된 신분증과 다릅니다. 표준 API 세션이 아닌 Didit 프로토콜(UserKYC) 계정에 대해서만 생성됩니다. | 구성 가능 — Data Inconsistency, 기본값 information |
| `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | 신분증 인증 문서 간 데이터 불일치 | 동일한 세션 내의 두 신분증 문서 간에 성명 / 생년월일 정보가 일치하지 않습니다. | 설정 가능 — 데이터 불일치, 기본값 information |
| `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY` | 문서 촬영 중 셀피가 문서 인물 사진과 일치하지 않음 | 문서 촬영 중 사용자의 전면 카메라로 캡처된 얼굴이 문서의 인물 사진과 충분히 일치하지 않습니다. | 임계값 기반: 거부 임계값 미만 시 `error`, 검토 임계값 이하 시 `warning` |
| `FRONT_CAMERA_FACE_IN_BLOCKLIST` | 문서 촬영 중 셀피가 차단 목록 얼굴과 일치함 | 문서 촬영 중 전면 카메라로 촬영된 셀피의 얼굴이 라이브니스 감지, 다른 세션의 문서 촬영 셀피 또는 업로드를 통해 추가된 얼굴 차단 목록의 얼굴과 확실하게 일치합니다. 차단된 얼굴이 세션에서 비롯된 경우 `additional_data`에 차단 목록 세션 참조(`blocklisted_session_id`, `blocklisted_session_number`)가 포함되며, 일치한 셀피의 `face_image_source`(`front_image_camera_front` 또는 `back_image_camera_front`)가 포함됩니다. | `error` — **자동 거부** |
| `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` | 문서 촬영 중 셀피가 차단 목록 얼굴과 일치할 수 있음 | 문서 촬영 셀피의 얼굴이 얼굴 차단 목록의 얼굴과 유사하지만, 확정적인 일치로 간주될 만큼 유사하지는 않습니다. `additional_data`는 위와 동일합니다. | `warning` — **항상 검토** |
| `FRONT_CAMERA_DUPLICATED_FACE` | 문서 촬영 중 셀피가 승인된 사용자와 일치함 | 문서 촬영 중 전면 카메라로 촬영된 셀피의 얼굴이 애플리케이션에서 이미 승인된 사용자의 얼굴과 확실하게 일치하므로, 동일한 인물이 다른 계정으로 다시 인증을 시도하는 것일 수 있습니다. `additional_data`에는 일치한 세션(`duplicated_session_id`, `duplicated_session_number`)과 일치한 셀피의 `face_image_source`가 포함됩니다. | **Silent Capture의 중복된 얼굴** 설정에 따름 (기본값 승인, `information`) |
| `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` | 문서 촬영 중 셀피가 승인된 사용자와 일치할 수 있음 | 문서 촬영 셀피의 얼굴이 애플리케이션에서 이미 승인된 사용자의 얼굴과 유사하지만, 확정적인 일치로 간주될 만큼 유사하지는 않습니다. `additional_data`는 위와 동일합니다. | **Silent Capture의 중복된 얼굴** 설정에 따름 (기본값 승인, `information`) |
| `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` | 문서 촬영 셀피가 다른 성명의 사용자와 일치함 | 승인된 사용자가 다른 성명으로 인증된 경우 `FRONT_CAMERA_DUPLICATED_FACE`에 추가로 발생합니다. `additional_data`에 `name_match_score`가 추가되며, 다른 사용자의 성명은 절대 포함되지 않습니다. | **이름이 다른 Silent Capture 중복** 설정에 따름 (기본값 검토, `warning`) |
| `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` | 문서 촬영 셀피가 다른 생년월일의 사용자와 일치함 | 승인된 사용자의 신분증에 다른 생년월일이 표시되어 있는 경우 `FRONT_CAMERA_DUPLICATED_FACE`에 추가로 발생합니다. 동일 인물의 다른 문서(예: 신분증 다음에 발급된 여권), 갱신된 문서, 동일 국가의 동일한 문서 번호는 플래그 처리되지 않습니다. `additional_data`에 `mismatch_dimensions`가 추가되며, 다른 사용자의 문서 데이터는 절대 포함되지 않습니다. | **생년월일이 다른 Silent Capture 중복** 설정에 따름 (기본값 검토, `warning`) |
| `FRONT_CAMERA_CAPTURED_DOCUMENT` | 전면 카메라에 사용자 대신 신분증 문서가 캡처됨 | 문서를 스캔하는 동안 촬영된 전면 카메라 프레임에 사람이 없고 신분증 문서(예: 카메라 앞에 들고 있는 카드)만 표시됩니다. 해당 프레임에 대해서는 문서 촬영 셀피 일치가 계산되지 않습니다. | 항상 **검토** |

### 문서 라이브니스 (위변조)

워크플로 내 사기 유형별로 임계값에 따라 제어됩니다. 독립형 OCR API에서는 이 세 가지 위험 요소가 발생하면 무조건 거부되며, 사용 가능한 점수를 생성하지 못한 요청된 검사는 승인 대신 `In Review`를 반환합니다.

점수 자체는 경고가 발생하지 않은 경우를 포함하여 모든 V3 보고서에 [`document_liveness`](https://docs.didit.me/ko/core-technology/id-verification/report-id-verification#문서-라이브니스-점수)로 표시되므로, 승인된 문서도 감사할 수 있습니다.

| 위험 | 간단한 설명 | 원인 | 심각도 |
| - | - | - | - |
| `SCREEN_CAPTURE_DETECTED` | 문서의 화면 캡처 감지됨 | 실물 문서가 아닌 화면에서 문서를 촬영했습니다. | 거부 임계값 미만 시 `error`, 검토 임계값 미만 시 `warning`, 그 외 `information` |
| `PRINTED_COPY_DETECTED` | 문서의 인쇄본 감지됨 | 문서가 원본이 아닌 인쇄된 사본으로 보입니다. | 동일한 3단계 임계값 적용 |
| `PORTRAIT_MANIPULATION_DETECTED` | 인물 사진 조작 감지됨 | 인물 사진 영역이 교체되거나 변조된 것으로 보입니다. | 동일한 3단계 임계값 적용 |
| `DOCUMENT_LIVENESS_NOT_COMPUTED` | 문서 라이브니스 검사를 계산할 수 없음 | 요청된 문서 라이브니스(위조) 검사에서 사용 가능한 점수가 반환되지 않았습니다(공급자 실패, 200 이외의 응답 또는 HTTP 200에 `status="ERR"` 반환). 따라서 문서의 인물 사진 교체, 인쇄본 여부 또는 화면 재생 여부를 검사하지 못했습니다. 점수 누락이 진본 문서임을 증명하지는 않습니다. 독립형 OCR API 전용입니다. | `warning` + `In Review` (설정 불가, `Declined`를 덮어쓰지 않음) |

### 캡처 채널 무결성

| 위험 | 간단한 설명 | 원인 | 설정 항목 | 기본값 |
| - | - | - | - | - |
| `INJECTION_ATTACK_DETECTED` | 인젝션 공격 감지됨 | 기기 자체 카메라로 캡처한 것이 아니라 조작되어 주입된 캡처입니다. 임의의 비디오를 재생할 수 있는 소프트웨어 가상 카메라, 페이지나 브라우저 자동화 도구가 생성한 카메라 피드, 후킹된 카메라, 또는 앱에 연결된 계측 도구가 프레임을 공급했습니다. `additional_data.reasons`에는 이를 입증하는 사유만 나열되며, `source`는 `capture_integrity`입니다. 문서 캡처 및 신분증 조회를 위해 촬영한 셀피에 적용됩니다. | `id_verification_injection_attack_action` | **거부** |

`log_type`은 설정된 작업을 반영합니다. Decline은 `error`, Review는 `warning`, No action은 `information`입니다.
권장 작업: 거부된 세션을 인젝션 캡처로 간주하고, 사용자에게 내장 카메라가 있는 물리적 기기에서 재시도하도록 요청하십시오.
실제 사람이 생성할 수 있는 신호는 `INJECTION_ATTACK_DETECTED`를 발생시키지 않으며 정보성 상태로 유지됩니다.
휴대폰을 웹캠으로 사용하거나 실제 웹캠 위에 효과 레이어를 적용하는 등 실제 카메라를 중계하는 앱은 인젝션 공격으로 보고되지 않습니다.
이는 인젝션 공격 감지이며, 프레젠테이션 공격 감지(실제 카메라 앞에 위조품을 제시하는 행위)와는 구분됩니다.

### 알려진 공개 문서 이미지

| 위험 | 간단한 설명 | 원인 | 심각도 |
| - | - | - | - |
| `PUBLIC_DOCUMENT_IMAGE_DETECTED` | 인터넷에 공개된 것으로 알려진 문서 이미지 감지됨 | 제출된 문서 이미지가 인터넷에 공개된 알려진 이미지(예: 문서 견본, 보도 사진 또는 스톡 사진)와 일치하므로 사용자의 실제 실물 문서 사진일 수 없습니다. 일치 여부 확인에는 Didit의 알려진 공개 문서 이미지 코퍼스를 대상으로 정확 일치 및 지각적(pHash/dHash) 핑거프린팅이 사용되며, `additional_data`에는 `match_type`(`exact` 또는 `perceptual`), `source`, `source_url`, `similarity_score`(0-100)가 포함됩니다. | 고정됨 — 워크플로에서는 검토, 단독 `/id-verification` API에서는 **자동 거부** |

### 예상 세부 정보 불일치

세션에 `expected_details`를 전달하면, Didit은 일치하지 않는 필드마다 불일치 경고를 발생시킵니다. 하나의 그룹 설정(`expected_details_mismatch_action`, 기본값 Review)으로 이 모든 경고의 라우팅을 제어합니다.

| 위험 | 간단한 설명 | 원인 |
| - | - | - |
| `FULL_NAME_MISMATCH_WITH_PROVIDED` | 제공된 정보와 성명 불일치 | 제공된 성명이 문서와 비교했을 때 이름 일치 임계값보다 낮은 점수를 받습니다. |
| `DOB_MISMATCH_WITH_PROVIDED` | 제공된 정보와 생년월일 불일치 | 제공된 생년월일이 일치하지 않습니다. |
| `GENDER_MISMATCH_WITH_PROVIDED` | 제공된 정보와 성별 불일치 | 제공된 성별이 일치하지 않습니다. |
| `COUNTRY_MISMATCH_WITH_PROVIDED` | 제공된 정보와 국가 불일치 | 제공된 국가가 `issuing_state`와 일치하지 않습니다. |
| `NATIONALITY_MISMATCH_WITH_PROVIDED` | 제공된 정보와 국적 불일치 | 제공된 국적이 일치하지 않습니다. |
| `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | 제공된 정보와 식별 번호 불일치 | 제공된 식별 번호가 문서 번호, 개인 번호 또는 납세자 번호와 일치하지 않습니다. |

각 불일치 경고는 `additional_data`에 예상 값과 추출된 값을 포함합니다.

### 연령

| 위험 | 간단한 설명 | 원인 | 심각도 |
| - | - | - | - |
| `MINIMUM_AGE_NOT_MET` | 최소 연령 미달 | 소지자가 설정된 최소 연령(전역 또는 국가/주별) 미만입니다. `additional_data`에는 `min_age_allowed` 및 `user_age`가 포함됩니다. | 설정 가능 — 최소 연령(Minimum Age), 기본값 Decline(`error`), 단독 OCR API에서는 무조건 거부 |
| `MAXIMUM_AGE_EXCEEDED` | 최대 연령 초과 | 소지자가 설정된 최대 연령을 초과했습니다. `additional_data`에는 `max_age_allowed` 및 `user_age`가 포함됩니다. | 설정 가능 — 최대 연령(Maximum Age), 기본값 Decline(`error`) |
| `AGE_NOT_DETECTED` | 연령이 감지되지 않음 | 적응형 연령 확인 워크플로: 문서에서 연령을 추출할 수 없습니다. | `error` — **자동 거부** |
| `AGE_BELOW_MINIMUM` | 최소 연령 미만 | 적응형 연령 확인 워크플로: 추출된 연령이 최소 연령 미만입니다. | `error` — **자동 거부** |

### 주소

| 위험 | 간단한 설명 | 원인 | 심각도 |
| - | - | - | - |
| `UNPARSED_ADDRESS` | 주소 위치 확인 불가 | 문서에 주소 필드가 정의되어 있으나 추출된 주소를 파싱하거나 지리적 위치를 파악할 수 없습니다. | 설정 가능 — 파싱되지 않은 주소(Unparsed Address), 기본값 information |

## 세션 간 문서 일치

위의 경고 외에도 V3 신분증 보고서에는 동일한 사용자에 속한 세션을 제외하고 동일한 생년월일, 동일한 발급 국가, 매우 유사한 성명을 가진 애플리케이션 내 최대 5개의 다른 문서 목록인 `matches[]` 배열이 제공됩니다(차단 목록에 등록된 문서의 경우 문서 번호의 정확한 일치도 추가로 요구됨). 차단 목록에 추가된 문서는 `is_blocklisted: true`로 표시됩니다. 허용 목록에 있는 문서는 일치 항목에 계속 나타나지만, 중복 사용자 작업은 건너뜁니다.

각 일치 항목에는 `session_id`, `session_number`, `vendor_data`, `verification_date`, `user_details`(`name`, `document_type`, `document_number`), `status`, `is_blocklisted`, `api_service` 및 서명된 `front_image_url`이 포함됩니다.

## 예시

### 기본 라우팅(information) 상태의 설정 가능한 경고

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "QR_NOT_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "QR not detected",
    "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
    "node_id": "id_primary"
  }
]
```

### 만료된 문서에 대한 자동 거부

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOCUMENT_EXPIRED",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Document expired",
    "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
    "node_id": "id_primary"
  }
]
```

### payload를 사용한 예상 세부 정보 불일치

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOB_MISMATCH_WITH_PROVIDED",
    "additional_data": {
      "expected_dob": "1990-01-01",
      "extracted_dob": "1991-03-15"
    },
    "log_type": "warning",
    "short_description": "Date of birth mismatch with provided information",
    "long_description": "The provided date of birth in `expected_details` doesn't match the date extracted from the document.",
    "node_id": "id_primary"
  }
]
```

## 경고 유형

각 위험에는 애플리케이션 설정에 따라 심각도가 할당됩니다. 세 가지 심각도는 다음과 같습니다.

## 관련 문서

* [신분증 인증 보고서](https://docs.didit.me/ko/core-technology/id-verification/report-id-verification.md) — 전체 보고서 스키마 및 상태.
* [문서 모니터링](https://docs.didit.me/ko/core-technology/id-verification/document-monitoring-id-verification.md) — Didit이 위변조 및 세션 간 중복을 감지하는 방법.
* [Webhook](https://docs.didit.me/ko/integration/webhooks.md) — 신분증 단계가 완료되는 즉시 경고를 전달하는 `session.status.updated`.
* [데이터 모델 — 신분증 인증](https://docs.didit.me/ko/reference/data-models.md#신분증-인증) — 필드별 표준 스키마.
* [데이터 모델 — 경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) — `warnings[]` 내 모든 항목의 구조.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.