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

# Laporan Autentikasi Biometrik: Skema JSON

> Urai respons Autentikasi Biometrik Didit dengan liveness dan pencocokan wajah opsional melalui liveness_checks dan face_matches.

Laporan Autentikasi Biometrik adalah cara Didit melaporkan kembali hasil verifikasi ulang pengguna lama. Alur kerja ini menjalankan pemeriksaan liveness baru dan, saat Pencocokan Wajah diaktifkan dalam alur kerja, pencocokan wajah 1:1 terhadap wajah referensi yang ditentukan saat pembuatan sesi (`portrait_image` yang Anda berikan, atau wajah tersimpan pengguna yang dicari berdasarkan `vendor_data`). Kedua pemeriksaan muncul sebagai item fitur standar dalam respons keputusan sesi V3.

![Laporan autentikasi biometrik Didit yang menggabungkan pemeriksaan liveness dan pencocokan wajah terhadap potret tersimpan](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)

## Gambaran umum

Autentikasi Biometrik adalah jenis alur kerja (`workflow_type: "biometric_authentication"`), bukan objek respons terpisah. Saat alur kerja berjalan, alur kerja ini menghasilkan:

* Satu **pemeriksaan liveness** yang mengambil swafoto langsung dan menilainya untuk spoofing.
* Satu **pencocokan wajah** yang membandingkan wajah yang diambil dengan wajah referensi yang ditentukan saat pembuatan sesi (hanya jika Pencocokan Wajah diaktifkan dalam alur kerja).

Setiap kali alur kerja menyertakan Pencocokan Wajah, pembuatan sesi memerlukan wajah referensi. Kirimkan `portrait_image` (gambar yang dikodekan dalam base64, maks 2MB), atau abaikan dan Didit akan menggunakan kembali wajah yang sudah tersimpan untuk pengguna `vendor_data`: wajah liveness yang disetujui terlebih dahulu, kemudian foto chip ePassport, lalu potret dokumen identitas, kemudian wajah profil yang didaftarkan secara manual. Jika baik `portrait_image` maupun wajah yang tersimpan tidak tersedia, pembuatan sesi mengembalikan `400` dengan `{"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."}`. Dalam kedua kasus, referensi yang ditentukan dicatat di bawah sesi baru, sehingga `source_image_session_id` pada item pencocokan wajah diatur ke `session_id` dari sesi itu sendiri (ini memberi tahu Anda bahwa referensi berasal dari potret tersimpan sesi alih-alih dari potret dokumen yang diambil pada sesi yang sama, yang akan membuat kolom tersebut bernilai `null`).

## Tempat kemunculannya

| Kunci respons keputusan | Jamak | Skema item |
| - | - | - |
| `liveness_checks[]` | Satu per langkah liveness (biasanya 1 dalam autentikasi biometrik) | [data-models#liveness-check](https://docs.didit.me/id/reference/data-models.md#pemeriksaan-liveness) |
| `face_matches[]` | Satu per langkah pencocokan wajah (`null` dalam alur kerja liveness saja) | [data-models#face-match](https://docs.didit.me/id/reference/data-models.md#pencocokan-wajah) |

Kedua array dikembalikan oleh [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/id/sessions-api/retrieve-session) untuk sesi yang jenis alur kerjanya adalah `biometric_authentication`. Keduanya selalu berupa array — tidak pernah berupa objek tunggal — dan masing-masing bernilai `null` sampai langkahnya menghasilkan data. Setiap item membawa `node_id` sehingga alur kerja multi-instance dapat membedakan langkah-langkah yang ada.

## Referensi skema

Daftar kolom lengkap didefinisikan satu kali di halaman model data sehingga setiap laporan yang menampilkan fitur-fitur ini berbagi satu sumber kebenaran:

* [Skema item liveness](https://docs.didit.me/id/reference/data-models.md#pemeriksaan-liveness) — `status`, `method`, `score`, `reference_image`, `video_url`, `age_estimation`, `matches[]`, `face_quality`, `face_luminance`, `warnings[]`, `node_id`.
* [Skema item pencocokan wajah](https://docs.didit.me/id/reference/data-models.md#pencocokan-wajah) — `status`, `score`, `source_image_session_id`, `source_image`, `target_image`, `warnings[]`, `node_id`.
* [Bentuk entri peringatan](https://docs.didit.me/id/reference/data-models.md#objek-peringatan) — `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

## Nilai status

Baik `liveness_checks[].status` maupun `face_matches[].status` menggunakan siklus hidup fitur bersama ([status tingkat fitur](https://docs.didit.me/id/reference/data-models.md#status-tingkat-fitur)):

| Status | Arti |
| - | - |
| `Not Finished` | Langkah belum menghasilkan hasil akhir (pengguna belum menyelesaikannya, atau drop-off). Sebelum langkah dimulai sama sekali, array-nya bernilai `null` dalam respons keputusan. |
| `Approved` | Pemeriksaan lolos semua ambang batas yang dikonfigurasi. |
| `In Review` | Skor berada dalam rentang peninjauan, atau peringatan yang dapat dikonfigurasi diatur ke peninjauan. |
| `Declined` | Skor berada pada atau di bawah ambang batas penolakan, atau peringatan penolakan otomatis terpicu (serangan wajah, tidak ada wajah terdeteksi, wajah ada di daftar blokir, tidak ada gambar referensi untuk pencocokan wajah). |
| `Resub Requested` | Peninjau meminta pengguna untuk mencoba lagi langkah ini. |

Status keseluruhan sesi (`status`) menggabungkan kedua item: fitur apa pun yang berstatus `Declined` akan menolak sesi, fitur apa pun yang berstatus `In Review` membuat sesi menjadi `In Review`, jika tidak maka `Approved` (setelah setiap fitur selesai).

Untuk perilaku ambang batas dan daftar lengkap kode peringatan, lihat [Peringatan Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/warnings-biometric-authentication.md).

## Contoh — liveness + pencocokan wajah (disetujui)

Contoh telah diringkas: respons keputusan lengkap juga memuat `session_url`, `metadata`, `callback`, `reviews`, `contact_details`, `expected_details`, `environment`, `created_at`, dan `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
}
```

## Contoh — liveness saja (Pencocokan Wajah dinonaktifkan dalam alur kerja)

```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
}
```

Mode liveness saja adalah konfigurasi alur kerja: saat Pencocokan Wajah dinonaktifkan, tidak ada wajah referensi yang diperlukan saat pembuatan sesi dan `face_matches` tetap bernilai `null`. Saat Pencocokan Wajah **diaktifkan**, mengabaikan `portrait_image` tidak akan beralih ke mode liveness saja: Didit menggunakan kembali wajah yang tersimpan untuk pengguna `vendor_data`, dan jika tidak ada wajah tersimpan maka pembuatan sesi gagal dengan kode `400`.

## Contoh — pencocokan wajah ditolak karena kemiripan rendah

```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"
        }
      ]
    }
  ]
}
```

## Catatan keamanan

`reference_image`, `video_url`, `source_image`, dan `target_image` adalah URL bertanda tangan yang kedaluwarsa setelah masa berlaku terbatas (secara default 4 jam). Tautan ini mengarah ke data biometrik — jangan menyimpannya dalam cache atau menampilkannya secara publik. Simpan hasil verifikasi (status, skor, `source_image_session_id`) di pihak Anda; panggil kembali endpoint keputusan jika Anda memerlukan URL baru.

## Terkait

> [card] [Peringatan Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/warnings-biometric-authentication.md)
>
> Kode peringatan, ambang batas, dan kondisi penolakan otomatis.

> [card] [Laporan liveness](https://docs.didit.me/id/core-technology/liveness/report-liveness.md)
>
> Referensi kolom lengkap untuk item `liveness_checks[]`.

> [card] [Laporan Pencocokan Wajah](https://docs.didit.me/id/core-technology/face-match/report-face-match.md)
>
> Referensi kolom lengkap untuk item `face_matches[]`.


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