> ## 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의 1:1 얼굴 대조 보고서 읽는 방법: 상태, 유사도 점수, 원본/대상 이미지 URL, 경고 및 API 응답 내 데이터 위치를 안내합니다.

## 개요

**얼굴 대조 보고서**는 라이브니스 단계에서 캡처한 라이브 셀피와 기준 이미지(일반적으로 신분증 문서에서 추출한 인물 사진) 간의 1:1 생체 인식 비교 결과를 기록합니다. 0\~100 사이의 단일 유사도 점수, 비교된 두 이미지에 대한 서명된 URL, 기준 이미지의 소스 세션, 대조 시 발생한 모든 경고를 반환합니다.

이 보고서는 사용자가 워크플로에서 라이브니스 단계와 문서 단계를 모두 완료한 후(생체 인증과 같은 인물 사진 기반 워크플로의 경우 라이브니스 단계만 완료한 후) 생성되거나, 임의의 두 얼굴 이미지를 직접 제공하는 독립 실행형 [Face Match API](https://docs.didit.me/ko/standalone-apis/face-match.md)를 통해 직접 생성됩니다.

각 보고서는 전체 세션 상태와 무관하게 고유한 `status`를 가지며, 이는 얼굴 대조 단계 자체의 처리 결과를 반영합니다.

* **승인됨** — `score`가 검토 임계값보다 높고 자동 거부 경고가 발생하지 않았습니다.
* **검토 중** — `score`가 거부 임계값과 검토 임계값 사이에 있거나, 점수를 계산할 수 없고 `face_match_not_computed_action`이 `REVIEW`로 설정되었습니다.
* **거부됨** — `score`가 거부 임계값 이하이거나, `NO_REFERENCE_IMAGE`가 발생했거나, 점수를 계산할 수 없고 `face_match_not_computed_action`이 `DECLINE`으로 설정되었습니다.
* **Resub Requested** — 검토자가 콘솔에서 사용자에게 이 단계의 재제출을 요청했습니다.
* **Not Finished** — 얼굴 대조 단계에서 아직 결과가 생성되지 않았습니다(사용자가 실패한 캡처를 재시도하는 중인 경우 포함).

## API 응답에 표시되는 위치

얼굴 대조 보고서는 `face_matches[]` 배열 내에 포함되며, 단일 `face_match` 객체가 아닌 **항상 JSON 배열** 형태로 제공됩니다. 최소 하나 이상의 얼굴 대조 단계에서 데이터가 생성될 때까지는 `null`이며, 워크플로에서 얼굴 대조를 두 번 이상 실행하면 여러 항목이 나타납니다. [Adaptive Age Verification](https://docs.didit.me/ko/core-technology/age-estimation/overview.md#적응형-연령-추정) 워크플로에서도 신분증 인증 대체 동작이 실행될 때 이 배열이 채워집니다. 해당 워크플로에는 자체 얼굴 대조 노드가 없으므로 이 항목은 연령 추정 노드를 `node_id`로 보고합니다.

* **세션 결정 API** — `GET /v3/session/{sessionId}/decision/`은 최상위 수준에서 `face_matches[]`를 반환합니다. [Retrieve session decision](https://docs.didit.me/ko/sessions-api/retrieve-session.md)을 참조하세요.
* **webhook** — 단계에서 데이터가 생성되면 `session.status.updated` payload에 동일한 `face_matches[]` 배열이 포함됩니다. [Webhooks](https://docs.didit.me/ko/integration/webhooks.md)를 참조하세요.
* **독립 실행형 Face Match API** — 직접 1:1 비교를 수행하려면 [Face Match standalone API](https://docs.didit.me/ko/standalone-apis/face-match.md)를 참조하세요.

> [!NOTE]
>
> `response.face_matches[0]`을 읽고 배열을 순회하세요. 일부 이전 튜토리얼에서 언급된 단일 `face_match` 형태는 v3 decision endpoint에 존재하지 않습니다.

## 스키마

필드별 표준 스키마는 [Data models](https://docs.didit.me/ko/reference/data-models.md#얼굴-대조) 참조 페이지에 있습니다. 아래 필드는 해당 표준 스키마를 반영합니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | 얼굴 대조 단계 상태(`FeatureStatusChoices`). |
| `node_id` | string \| null | 이 보고서를 생성한 워크플로 그래프 노드입니다. |
| `score` | number 0–100 \| null | 소수점 둘째 자리로 반올림된 생체 인식 유사도 점수입니다. 비교할 수 없는 경우 `null`입니다. |
| `source_image_session_id` | string \| null | 기준(소스) 이미지를 제공한 인물 사진이 저장된 세션의 UUID입니다. 인물 사진 기반 플로우(생체 인증 또는 세션 생성 시 제공된 인물 사진)에서 설정됩니다. 기준 이미지가 동일한 세션에서 캡처된 신분증 인물 사진인 경우 `null`입니다. |
| `source_image` | string (서명된 URL) | 기준 이미지(일반적으로 신분증 인물 사진)입니다. 수명이 짧은 서명된 URL이므로 즉시 다운로드해야 하며 URL을 저장하지 마세요. |
| `target_image` | string (서명된 URL) | 대상 이미지(일반적으로 라이브니스 셀피)입니다. 수명이 짧은 서명된 URL이므로 즉시 다운로드해야 하며 URL을 저장하지 마세요. |
| `warnings[]` | array | 모듈 수준 경고입니다. 각 항목에는 `feature`(항상 `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`가 포함됩니다. [Face match warnings](https://docs.didit.me/ko/core-technology/face-match/warnings-face-match.md)를 참조하세요. |

## 상태 값

| 상태 | 의미 | 후속 영향 |
| - | - | - |
| `Approved` | 점수가 검토 임계값보다 높고 자동 거부 경고가 발생하지 않았습니다. | 성공한 얼굴 대조로 처리됩니다. |
| `In Review` | 점수가 거부 임계값보다 높지만 검토 임계값 이하이거나, `face_match_not_computed_action`이 `REVIEW`로 설정된 상태에서 점수를 계산할 수 없는 경우(예: 기준 이미지가 남지 않는 비문서 조회 후 `FACE_MATCH_NOT_COMPUTED`)입니다. | 검토자가 조치할 때까지 세션도 `In Review`로 전환됩니다. |
| `Declined` | 점수가 거부 임계값 이하이거나, `NO_REFERENCE_IMAGE`가 발생했거나, `face_match_not_computed_action`이 `DECLINE`으로 설정된 상태에서 점수를 계산할 수 없는 경우입니다. | 다른 승인된 분기가 워크플로를 충족하지 않는 한 세션이 거부됩니다. |
| `Resub Requested` | 검토자가 콘솔에서 이 단계의 재제출을 요청했습니다. | 사용자에게 다시 캡처하도록 요청합니다. |
| `Not Finished` | 얼굴 대조 단계에서 결과가 생성되지 않았습니다(입력값이 누락되었거나, 워크플로가 비교 단계에 도달하지 않았거나, 사용자가 여전히 캡처 재시도 루프에 있는 경우). | 분기가 완료되지 않았습니다. |

유사도가 낮아 실패한 경우 상태가 확정되기 전에 재시도됩니다. 사용자는 최대 `face_match_max_attempts`회(기본값 3회)까지 캡처할 수 있으며 최종 시도의 점수만 적용됩니다. 워크플로 노드에 구성된 커스텀 상태 규칙에 따라 결과 상태를 추가로 조정할 수 있으며, `Declined` > `In Review` > `Approved` 우선순위에 따라 점수 기반 상태와 결합됩니다.

## 예시

### 승인됨 — 정상 일치

```json theme={null}
{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}
```

### 검토 중 — 경계선 유사도

```json theme={null}
{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "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_1"
        }
      ]
    }
  ]
}
```

### 거부됨 — 대조할 기준 이미지 없음

```json theme={null}
{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

## 보안 참고 사항

`source_image` 및 `target_image`에 대한 서명된 URL은 생체 인식 데이터이며 짧은 유효 기간이 지나면 만료됩니다. 이를 수명이 짧은 URL로 취급하여 캐시하거나 공개적으로 노출하지 마세요. 일반적으로 애플리케이션에는 `status`와 `score`만 필요하므로, 서버의 생체 인식 데이터를 최소화할 수 있도록 가능한 한 적게 저장하세요.

## 관련 항목

* [얼굴 대조 경고](https://docs.didit.me/ko/core-technology/face-match/warnings-face-match.md) — 전체 경고 열거형, 원인 및 해결 방법.
* [라이브니스 보고서](https://docs.didit.me/ko/core-technology/liveness/report-liveness.md) — 대상 이미지를 캡처하는 업스트림 단계.
* [webhook](https://docs.didit.me/ko/integration/webhooks.md) — 보고서를 수신하려면 `session.status.updated` 이벤트를 수신 대기합니다.
* [데이터 모델 — 얼굴 대조](https://docs.didit.me/ko/reference/data-models.md#얼굴-대조) — 모든 필드가 포함된 표준 스키마.


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