> ## 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の単一の類似度スコア、比較した2枚の画像の署名付きURL、参照画像の取得元セッション、照合で発生した警告を返します。

このレポートは、ユーザーがワークフロー内のライブネスステップと書類ステップの両方を完了した後（生体認証など顔写真ベースのワークフローでは、ライブネスのみの完了後）に生成されます。任意の2つの顔画像を自分で指定する場合は、スタンドアロンの[顔照合API](https://docs.didit.me/ja/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[]`配列内に含まれます。**常にJSON配列**であり、単数形の`face_match`オブジェクトになることはありません。少なくとも1つの顔照合ステップがデータを生成するまでは`null`で、ワークフローで顔照合が複数回実行されると複数のエントリが含まれます。[Adaptive Age Verification](https://docs.didit.me/ja/core-technology/age-estimation/overview.md#アダプティブ年齢推定)ワークフローでも、本人確認のフォールバックが実行されるとこの配列にデータが入ります。このワークフローには独自の顔照合ノードがないため、そのエントリの`node_id`には年齢推定ノードのIDが設定されます。

* **セッション判定API**：`GET /v3/session/{sessionId}/decision/`はトップレベルで`face_matches[]`を返します。[セッション判定の取得](https://docs.didit.me/ja/sessions-api/retrieve-session.md)を参照してください。
* **Webhook**：ステップがデータを生成すると、`session.status.updated`ペイロードに同じ`face_matches[]`配列が含まれます。[Webhook](https://docs.didit.me/ja/integration/webhooks.md)を参照してください。
* **スタンドアロン顔照合API**：直接の1:1比較については、[顔照合スタンドアロンAPI](https://docs.didit.me/ja/standalone-apis/face-match.md)を参照してください。

> [!NOTE]
>
> `response.face_matches[0]`を読み取り、配列を反復処理してください。古いチュートリアルの一部で参照されていた単数形の`face_match`の形式は、v3の判定エンドポイントには存在しません。

## スキーマ

フィールドごとの正式なスキーマは[データモデル](https://docs.didit.me/ja/reference/data-models.md#顔照合)リファレンスページにあります。以下のフィールドはその正式なスキーマに準拠しています。

| フィールド | 型 | 説明 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | 顔照合ステップのステータス（`FeatureStatusChoices`）。 |
| `node_id` | string \| null | このレポートを生成したワークフローグラフのノード。 |
| `score` | number 0–100 \| null | 生体類似度スコア（小数点以下2桁に丸め）。比較できなかった場合は`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`が含まれます。[顔照合の警告](https://docs.didit.me/ja/core-technology/face-match/warnings-face-match.md)を参照してください。 |

## ステータス値

| ステータス | 意味 | 後続への影響 |
| - | - | - |
| `Approved` | スコアがレビューしきい値を上回り、自動却下の警告が発生していない。 | 顔照合の成功として扱われます。 |
| `In Review` | スコアが却下しきい値を上回りレビューしきい値以下である、またはスコアを算出できず（`FACE_MATCH_NOT_COMPUTED`。例：書類以外の照会で参照画像が残らなかった場合）、`face_match_not_computed_action`が`REVIEW`に設定されている。 | レビュアーが対応するまで、セッションも`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は生体データであり、短い有効期間が過ぎると失効します。有効期間の短いものとして扱い、キャッシュしたり公開したりしないでください。通常、アプリケーションに必要なのは`status`と`score`だけです。サーバー上の生体データを最小限に抑えるため、保存するデータはできるだけ少なくしてください。

## 関連情報

* [顔照合の警告](https://docs.didit.me/ja/core-technology/face-match/warnings-face-match.md)：警告 enum の完全な一覧、原因、対処方法。
* [ライブネスレポート](https://docs.didit.me/ja/core-technology/liveness/report-liveness.md)：対象画像を取得する前段のステップ。
* [Webhook](https://docs.didit.me/ja/integration/webhooks.md)：`session.status.updated`を受信してレポートを取得します。
* [データモデル:顔照合](https://docs.didit.me/ja/reference/data-models.md#顔照合)：すべてのフィールドを含む標準スキーマ。


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