> ## 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`も保存済みの顔画像もない場合、セッション作成は`400`と`{"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."}`を返します。いずれの場合も、確定した参照画像は新しいセッションに記録されるため、顔照合項目の`source_image_session_id`にはそのセッション自身の`session_id`が設定されます(これは、参照画像が同じセッション内で撮影された書類のポートレートではなく、セッションの保存済みポートレートに由来することを示します。同じセッション内で撮影された身分証明書類のポートレートに由来する場合、このフィールドは`null`になります)。

## 表示される場所

| 判定レスポンスのキー | 件数 | 項目のスキーマ |
| - | - | - |
| `liveness_checks[]` | ライブネスのステップごとに1件(生体認証では通常1件) | [data-models#liveness-check](https://docs.didit.me/ja/reference/data-models.md#ライブネスチェック) |
| `face_matches[]` | 顔照合のステップごとに1件(ライブネスのみのワークフローでは`null`) | [data-models#face-match](https://docs.didit.me/ja/reference/data-models.md#顔照合) |

どちらの配列も、ワークフロータイプが`biometric_authentication`であるセッションでは、[`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/ja/sessions-api/retrieve-session)によって返されます。これらは常に配列であり、単一のオブジェクトになることはありません。また、それぞれのステップがデータを生成するまでは`null`です。各項目には`node_id`が含まれるため、複数のインスタンスを持つワークフローでもステップを区別できます。

## スキーマリファレンス

全フィールドの一覧はdata-modelsページで一元的に定義されており、これらの機能を含むすべてのレポートが同じ情報源を共有します。

* [ライブネス項目のスキーマ](https://docs.didit.me/ja/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/ja/reference/data-models.md#顔照合): `status`、`score`、`source_image_session_id`、`source_image`、`target_image`、`warnings[]`、`node_id`。
* [警告エントリの構造](https://docs.didit.me/ja/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/ja/reference/data-models.md#機能レベルのステータス))を使用します。

| ステータス | 意味 |
| - | - |
| `Not Finished` | ステップがまだ最終結果を生成していません(ユーザーが完了していない、または離脱した)。ステップが開始される前は、判定レスポンス内の配列は単に`null`です。 |
| `Approved` | チェックが設定されたすべてのしきい値を満たしました。 |
| `In Review` | スコアがレビュー範囲に入ったか、設定可能な警告がレビューに設定されていました。 |
| `Declined` | スコアが却下しきい値以下だったか、自動却下の警告が発生しました(顔への攻撃、顔の未検出、ブロックリスト登録済みの顔、顔照合用の参照画像なし)。 |
| `Resub Requested` | レビュアーがユーザーにこのステップの再試行を求めました。 |

セッション全体の`status`は両方の項目を集約します。いずれかの機能が`Declined`であればセッションは却下され、いずれかが`In Review`であればセッションは`In Review`になり、それ以外の場合は(すべての機能が完了した後に)`Approved`になります。

しきい値の動作と警告コードの全一覧については、[生体認証の警告](https://docs.didit.me/ja/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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../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です。これらは生体データを指しているため、キャッシュしたり公開したりしないでください。認証結果(ステータス、スコア、`source_image_session_id`)は自社側で保存し、新しいURLが必要な場合は判定エンドポイントを再度呼び出してください。

## 関連情報

> [card] [生体認証の警告](https://docs.didit.me/ja/core-technology/biometric-auth/warnings-biometric-authentication.md)
>
> 警告コード、しきい値、自動却下の条件。

> [card] [ライブネスレポート](https://docs.didit.me/ja/core-technology/liveness/report-liveness.md)
>
> `liveness_checks[]`項目の全フィールドリファレンス。

> [card] [顔照合レポート](https://docs.didit.me/ja/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.