> ## 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. # 생체 인증 보고서: JSON 스키마 > Didit 생체 인증 응답을 분석하세요. liveness_checks 및 face_matches 필드를 통해 라이브니스 감지 및 저장된 사진과의 얼굴 대조 결과를 제공합니다. 생체 인증 보고서는 Didit이 재방문 사용자의 재인증 결과를 보고하는 방식입니다. 워크플로는 새로운 라이브니스 검사를 실행하며, 워크플로에서 얼굴 대조가 활성화된 경우 세션 생성 시 결정된 기준 얼굴(직접 제공한 `portrait_image` 또는 `vendor_data`로 조회한 사용자의 저장된 얼굴)과 1:1 얼굴 대조를 수행합니다. 두 검사는 모두 V3 세션 결정 응답에서 표준 기능 항목으로 표시됩니다. ![저장된 인물 사진과 라이브니스 검사 및 얼굴 대조를 결합한 Didit 생체 인증 보고서](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/biometric-auth-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=c02e5558780972797d4b2feea685bc73) ## 개요 생체 인증은 별도의 응답 객체가 아닌 워크플로 유형(`workflow_type: "biometric_authentication"`)입니다. 워크플로가 실행되면 다음이 생성됩니다: * 라이브 셀피를 캡처하고 스푸핑 여부를 점수화하는 **라이브니스 검사** 1건. * 캡처된 얼굴을 세션 생성 시 결정된 기준 얼굴과 비교하는 **얼굴 대조** 1건(워크플로에서 얼굴 대조가 활성화된 경우에만 해당). 워크플로에 얼굴 대조가 포함된 경우 세션 생성 시 기준 얼굴이 필요합니다. `portrait_image`(base64로 인코딩된 이미지, 최대 2MB)를 전송하거나, 이를 생략하면 Didit이 `vendor_data` 사용자에 대해 이미 저장된 얼굴(승인된 라이브니스 얼굴 우선, 그 다음 전자여권(ePassport) 칩 사진, 신분증 문서 인물 사진, 수동 등록된 프로필 얼굴 순)을 재사용합니다. `portrait_image`와 저장된 얼굴을 모두 사용할 수 없는 경우 세션 생성 시 `{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}`와 함께 `400`이 반환됩니다. 두 경우 모두 확인된 기준 얼굴이 새 세션 아래에 기록되므로, 얼굴 대조 항목의 `source_image_session_id`는 해당 세션 자체의 `session_id`로 설정됩니다(동일 세션에서 캡처되어 해당 필드가 `null`로 유지되는 신분증 문서 인물 사진이 아니라, 세션에 저장된 인물 사진에서 기준 얼굴을 가져왔음을 나타냄). ## 표시 위치 | 결정 응답 키 | 복수 여부 | 항목 스키마 | | - | - | - | | `liveness_checks[]` | 라이브니스 단계당 1개(생체 인증에서는 보통 1개) | [data-models#liveness-check](https://docs.didit.me/ko/reference/data-models.md#라이브니스-검사) | | `face_matches[]` | 얼굴 대조 단계당 1개(라이브니스 전용 워크플로에서는 `null`) | [data-models#face-match](https://docs.didit.me/ko/reference/data-models.md#얼굴-대조) | 두 배열 모두 워크플로 유형이 `biometric_authentication`인 세션에 대해 [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/ko/sessions-api/retrieve-session)에서 반환됩니다. 이들은 단일 객체가 아닌 항상 배열이며, 각 단계에서 데이터가 생성될 때까지 `null` 상태를 유지합니다. 다중 인스턴스 워크플로에서 단계를 명확히 구분할 수 있도록 각 항목에는 `node_id`가 포함됩니다. ## 스키마 참조 전체 필드 목록은 데이터 모델 페이지에 한 번 정의되어 있으므로 이러한 기능을 표시하는 모든 보고서가 단일 정보 소스를 공유합니다: * [라이브니스 항목 스키마](https://docs.didit.me/ko/reference/data-models.md#라이브니스-검사) — `status`, `method`, `score`, `reference_image`, `video_url`, `age_estimation`, `matches[]`, `face_quality`, `face_luminance`, `warnings[]`, `node_id`. * [얼굴 대조 항목 스키마](https://docs.didit.me/ko/reference/data-models.md#얼굴-대조) — `status`, `score`, `source_image_session_id`, `source_image`, `target_image`, `warnings[]`, `node_id`. * [경고 항목 구조](https://docs.didit.me/ko/reference/data-models.md#경고-객체) — `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`. ## 상태 값 `liveness_checks[].status`와 `face_matches[].status`는 모두 공통 기능 수명 주기([기능 수준 상태](https://docs.didit.me/ko/reference/data-models.md#기능-수준-상태))를 사용합니다: | 상태 | 의미 | | - | - | | `Not Finished` | 해당 단계가 아직 최종 결과를 생성하지 않았습니다(사용자가 완료하지 않았거나 이탈함). 단계가 시작되기 전에는 결정 응답에서 해당 배열이 단순히 `null`로 표시됩니다. | | `Approved` | 검사가 설정된 모든 임계값을 통과했습니다. | | `In Review` | 점수가 검토 구간에 속하거나, 설정 가능한 경고가 검토로 설정되었습니다. | | `Declined` | 점수가 거부 임계값 이하로 떨어졌거나 자동 거부 경고가 발생했습니다(얼굴 공격, 얼굴 감지되지 않음, 차단 목록에 등록된 얼굴, 얼굴 대조용 기준 이미지 없음). | | `Resub Requested` | 검토자가 사용자에게 이 단계를 재시도하도록 요청했습니다. | 전체 세션 `status`는 두 항목을 종합하여 결정됩니다. 어느 기능이든 `Declined` 상태이면 세션이 거부되고, `In Review` 상태이면 세션이 `In Review` 상태가 되며, 그렇지 않으면(모든 기능이 완료된 후) `Approved` 상태가 됩니다. 임계값 동작 및 경고 코드의 전체 목록은 [생체 인증 경고](https://docs.didit.me/ko/core-technology/biometric-auth/warnings-biometric-authentication.md)를 참조하십시오. ## 예시 — 라이브니스 + 얼굴 대조 (승인됨) 예시는 축약되어 있습니다. 전체 결정 응답에는 `session_url`, `metadata`, `callback`, `reviews`, `contact_details`, `expected_details`, `environment`, `created_at`, `expires_at`도 포함됩니다. ```json theme={null} { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "session_number": 1234, "status": "Approved", "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa", "features": ["LIVENESS", "FACE_MATCH"], "vendor_data": "user-123", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "PASSIVE", "score": 89.92, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": 92.4, "face_luminance": 58.1, "warnings": [] } ], "face_matches": [ { "node_id": "feature_face_match", "status": "Approved", "score": 88.47, "source_image_session_id": "11111111-2222-3333-4444-555555555555", "source_image": "https:///.../source.jpg", "target_image": "https:///.../target.jpg", "warnings": [] } ], "id_verifications": null, "nfc_verifications": null, "poa_verifications": null, "phone_verifications": null, "email_verifications": null, "aml_screenings": null } ``` ## 예시 — 라이브니스 전용 (워크플로에서 얼굴 대조 비활성화됨) ```json theme={null} { "session_id": "22222222-3333-4444-5555-666666666666", "session_kind": "user", "status": "Approved", "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb", "features": ["LIVENESS"], "vendor_data": "user-456", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "ACTIVE_3D", "score": 96.10, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": null, "face_luminance": null, "warnings": [] } ], "face_matches": null } ``` 라이브니스 전용 모드는 워크플로 구성 방식 중 하나입니다. 얼굴 대조가 비활성화된 경우 세션 생성 시 기준 얼굴이 필요하지 않으며 `face_matches`는 `null` 상태를 유지합니다. 얼굴 대조가 활성화되어 **있는** 경우, `portrait_image`를 생략하더라도 라이브니스 전용으로 대체되지 않고 Didit이 `vendor_data` 사용자에 대해 저장된 얼굴을 재사용하며, 저장된 얼굴이 없으면 세션 생성이 `400` 오류로 실패합니다. ## 예시 — 낮은 유사도로 인한 얼굴 대조 거부 ```json theme={null} { "session_id": "33333333-4444-5555-6666-777777777777", "status": "Declined", "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "PASSIVE", "score": 91.20, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": 90.15, "face_luminance": 55.30, "warnings": [] } ], "face_matches": [ { "node_id": "feature_face_match", "status": "Declined", "score": 41.18, "source_image_session_id": "33333333-4444-5555-6666-777777777777", "source_image": "https:///.../source.jpg", "target_image": "https:///.../target.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "error", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match" } ] } ] } ``` ## 보안 참고 사항 `reference_image`, `video_url`, `source_image`, `target_image`는 유효 기간(기본값 4시간)이 지나면 만료되는 서명된 URL입니다. 이 URL들은 생체 인식 데이터를 가리키므로 캐시하거나 공개적으로 노출하지 마십시오. 인증 결과(status, score, `source_image_session_id`)는 사용자 측에 저장하고, 새로운 URL이 필요한 경우 결정 endpoint를 다시 호출하십시오. ## 관련 항목 > [card] [생체 인증 경고](https://docs.didit.me/ko/core-technology/biometric-auth/warnings-biometric-authentication.md) > > 경고 코드, 임계값 및 자동 거부 조건. > [card] [라이브니스 보고서](https://docs.didit.me/ko/core-technology/liveness/report-liveness.md) > > `liveness_checks[]` 항목에 대한 전체 필드 참조. > [card] [얼굴 대조 보고서](https://docs.didit.me/ko/core-technology/face-match/report-face-match.md) > > `face_matches[]` 항목에 대한 전체 필드 참조. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.