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

# Peringatan & Kode Autentikasi Biometrik

> Kelola peringatan autentikasi biometrik Didit: LOW_LIVENESS_SCORE, serangan wajah, dan daftar blokir. Atur ambang batas serta tindakan penolakan.

Autentikasi Biometrik menggabungkan pemeriksaan liveness dengan pencocokan wajah 1:1 opsional terhadap wajah referensi yang ditentukan saat pembuatan sesi (`portrait_image` yang disediakan, atau wajah tersimpan milik pengguna yang dicari berdasarkan `vendor_data`). Setiap langkah memunculkan peringatannya masing-masing dalam payload keputusan V3. Halaman ini mencantumkan setiap kode, di mana kode tersebut muncul, dan bagaimana ambang batas diterjemahkan ke dalam status sesi akhir.

## Ringkasan

Saat sesi autentikasi biometrik berjalan, Didit:

* Mengambil swafoto langsung menggunakan 3D Action, Flash, atau Passive Liveness (`method`: `ACTIVE_3D`, `FLASHING`, atau `PASSIVE`).
* Mengekstrak wajah terbesar dari hasil pengambilan dan menilai liveness-nya.
* Jika alur kerja menyertakan Pencocokan Wajah, membandingkan wajah yang diambil dengan wajah referensi sesi (`portrait_image` yang disediakan atau wajah tersimpan milik pengguna).
* Menuliskan hasil dari setiap langkah beserta peringatan apa pun ke dalam keputusan sesi.

Peringatan mempertahankan struktur [objek peringatan](https://docs.didit.me/id/reference/data-models.md#objek-peringatan) bersama yang digunakan di seluruh platform: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, dan `node_id`.

## Di mana peringatan muncul

| Kunci respons keputusan | Tag fitur pada peringatan | Kapan peringatan dipicu |
| - | - | - |
| `liveness_checks[].warnings[]` | `LIVENESS` | Penilaian liveness, kualitas wajah, luminansi, beberapa wajah, serta pemeriksaan daftar blokir / daftar izin / wajah duplikat. |
| `face_matches[].warnings[]` | `FACEMATCH` | Pencocokan wajah terhadap wajah referensi sesi (`portrait_image` yang disediakan atau wajah tersimpan milik pengguna). |

Dalam sesi autentikasi biometrik pada umumnya, terdapat satu item di setiap array. Dalam alur kerja multi-instance, `node_id` pada setiap peringatan memperjelas langkah mana yang menghasilkannya.

## Kondisi penolakan otomatis

Peringatan berikut selalu menolak langkahnya (`log_type: "error"`) terlepas dari bagaimana Anda mengonfigurasi alur kerja:

| Risiko | Fitur | Alasan penolakan otomatis |
| - | - | - |
| `FACE_IN_BLOCKLIST` | `LIVENESS` | Wajah cocok dengan entri dalam daftar blokir wajah Anda. |
| `NO_FACE_DETECTED` | `LIVENESS` | Tidak ada wajah yang ditemukan selama pengambilan liveness, atau pengguna telah menghabiskan seluruh percobaan pengambilan ulang. |
| `LIVENESS_FACE_ATTACK` | `LIVENESS` | Serangan presentasi terdeteksi (masker, pemutaran ulang layar, spoofing kelas deepfake). |
| `NO_REFERENCE_IMAGE` | `FACEMATCH` | Tidak ada gambar referensi yang tersedia untuk menjalankan perbandingan. Saat ini dipicu, `LOW_FACE_MATCH_SIMILARITY` tidak dimunculkan. |

Saat `NO_FACE_DETECTED` dipicu, `LOW_LIVENESS_SCORE` tidak dimunculkan (tidak ada wajah untuk dinilai).

## Ambang batas dan tindakan yang dapat dikonfigurasi

Peringatan ini dinilai dan kemudian dipetakan ke suatu status melalui ambang batas dan tindakan yang Anda tetapkan per alur kerja:

| Risiko | Fitur | Perilaku yang dapat dikonfigurasi |
| - | - | - |
| `LOW_LIVENESS_SCORE` | `LIVENESS` | Skor yang sama dengan atau di bawah ambang batas peninjauan → `In Review`; yang sama dengan atau di bawah ambang batas penolakan → `Declined`. |
| `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | Skor yang sama dengan atau di bawah ambang batas peninjauan (default 70) → `In Review`; yang sama dengan atau di bawah ambang batas penolakan (default 50) → `Declined`. |
| `LOW_FACE_QUALITY` | `LIVENESS` | Ambang batas peninjauan (default 15) → `In Review`; ambang batas penolakan (default 0, yaitu penolakan dinonaktifkan) → `Declined`. Hanya Passive Liveness. |
| `LOW_FACE_LUMINANCE` | `LIVENESS` | Di bawah ambang batas luminansi minimum (default 20): Tidak ada tindakan / Peninjauan (default) / Penolakan. Hanya Passive Liveness. |
| `HIGH_FACE_LUMINANCE` | `LIVENESS` | Di atas ambang batas luminansi maksimum (default 80): Tidak ada tindakan / Peninjauan (default) / Penolakan. Hanya Passive Liveness. |
| `MULTIPLE_FACES_DETECTED` | `LIVENESS` | Tidak ada tindakan (default) / Peninjauan / Penolakan saat lebih dari satu wajah tertangkap. Hanya Passive Liveness. |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | Satu tindakan bersama untuk wajah duplikat: Tidak ada tindakan (default) / Peninjauan / Penolakan untuk kecocokan terhadap wajah yang disetujui atau diimpor milik pengguna lain. |
| `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | Tindakan terpisah (`face_liveness_duplicated_face_name_mismatch_action`): Tidak ada tindakan / Peninjauan (default) / Penolakan. Dikeluarkan bersamaan dengan `DUPLICATED_FACE` saat identitas sesi yang cocok tidak sesuai dengan nama yang ditentukan untuk sesi ini — lihat [Peringatan liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md#pencocokan-wajah-lintas-sesi). |

`POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) **tidak** dapat dikonfigurasi — kecocokan daftar blokir dengan tingkat keyakinan lebih rendah selalu diarahkan ke Peninjauan (`log_type: "warning"`).

## Percobaan ulang pengambilan

Kegagalan yang hanya disebabkan oleh risiko kualitas pengambilan yang dapat diperbaiki (skor rendah, tidak ada wajah, kualitas, luminansi, beberapa wajah — dan kemiripan rendah pada pencocokan wajah) masuk ke dalam perulangan coba lagi sebelum status ditetapkan: pengguna mendapatkan total hingga `face_liveness_max_attempts` / `face_match_max_attempts` upaya (default 3, dapat dikonfigurasi 2–5 per node alur kerja). Saat batas upaya habis, status yang dihitung dari upaya terakhir akan diterapkan dan `LIVENESS_MAX_ATTEMPTS_EXCEEDED` atau `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` dicatat sebagai `information` untuk merekamnya.

## Peringatan liveness

API mengembalikan string `short_description` dan `long_description` persis berikut:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_LIVENESS_SCORE` | Skor liveness rendah | Pemeriksaan liveness menghasilkan skor rendah, yang mengindikasikan potensi penggunaan representasi wajah non-live atau data biometrik berkualitas buruk. |
| `NO_FACE_DETECTED` | Tidak Ada Wajah yang Terdeteksi dalam liveness | Sistem tidak dapat mengidentifikasi wajah selama pemeriksaan liveness, yang mungkin disebabkan oleh kualitas gambar yang buruk, posisi yang tidak tepat, atau masalah teknis. |
| `LIVENESS_FACE_ATTACK` | Serangan Wajah Liveness | Sistem mendeteksi potensi upaya untuk memintas pemeriksaan liveness. |
| `FACE_IN_BLOCKLIST` | Wajah di daftar blokir | Sistem mengidentifikasi wajah di dalam daftar blokir, yang berarti wajah tersebut tidak diizinkan untuk diverifikasi. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Kemungkinan wajah di daftar blokir | Sistem mengidentifikasi kemungkinan wajah di dalam daftar blokir, yang berarti wajah tersebut tidak diizinkan untuk diverifikasi. |
| `FACE_IN_ALLOWLIST` | Wajah di daftar izin | Wajah cocok dengan daftar izin wajah aplikasi, sehingga tindakan untuk wajah duplikat dilewati untuk sinyal ini. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Kemungkinan wajah di daftar izin | Wajah kemungkinan cocok dengan daftar izin wajah aplikasi, sehingga tindakan untuk kemungkinan wajah duplikat dilewati untuk sinyal ini. |
| `DUPLICATED_FACE` | Wajah terduplikasi dari sesi lain yang disetujui | Sistem mengidentifikasi wajah terduplikasi dari sesi lain yang telah disetujui, sehingga memerlukan investigasi lebih lanjut. |
| `POSSIBLE_DUPLICATED_FACE` | Kemungkinan wajah terduplikasi dari sesi lain yang disetujui | Sistem mengidentifikasi kemungkinan wajah duplikat dari sesi lain yang telah disetujui, sehingga memerlukan investigasi lebih lanjut. |
| `DUPLICATED_FACE_NAME_MISMATCH` | Wajah terduplikasi dengan nama berbeda | Wajah yang sama telah disetujui pada sesi lain, tetapi dengan nama yang berbeda. Identitas di balik duplikat tersebut tidak cocok dengan identitas yang dinyatakan pada sesi ini, yang merupakan indikator kuat penipuan identitas. |
| `MULTIPLE_FACES_DETECTED` *(Hanya untuk mode pasif)* | Beberapa wajah terdeteksi | Beberapa wajah terdeteksi pada gambar liveness. Sistem menggunakan wajah terbesar untuk verifikasi liveness dan perbandingan wajah, tetapi keberadaan beberapa wajah mungkin memerlukan peninjauan tambahan. |
| `LOW_FACE_QUALITY` *(Hanya untuk mode pasif)* | Kualitas wajah rendah | Kualitas gambar wajah berada di bawah ambang batas yang dapat diterima, yang dapat memengaruhi keandalan deteksi liveness. Hal ini mungkin disebabkan oleh resolusi kamera, fokus, atau artefak kompresi. |
| `LOW_FACE_LUMINANCE` *(Hanya untuk mode pasif)* | Luminansi wajah rendah | Gambar wajah terlalu gelap, yang dapat memengaruhi akurasi deteksi liveness. Disarankan kondisi pencahayaan yang lebih baik. |
| `HIGH_FACE_LUMINANCE` *(Hanya untuk mode pasif)* | Luminansi wajah tinggi | Gambar wajah terlalu terang atau mengalami pencahayaan berlebih, yang dapat memengaruhi akurasi deteksi liveness. Disarankan untuk mengurangi pencahayaan atau menghindari cahaya langsung. |
| `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | Upaya liveness maksimum terlampaui | Jumlah maksimum upaya pengambilan gambar untuk liveness telah tercapai. Status yang dihitung dari upaya terakhir (ditolak atau dalam peninjauan) telah diterapkan. |

Kecocokan dengan daftar blokir, daftar izin, dan duplikat memuat `additional_data` bersama sesi yang cocok (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, `*_session_number` yang cocok, dan `api_service`). Hanya satu dari enam kode tersebut yang muncul per laporan. `DUPLICATED_FACE_NAME_MISMATCH` adalah pengecualian: kode ini dimunculkan **selain** `DUPLICATED_FACE`, tidak pernah menggantikannya, ketika identitas sesi yang cocok tidak sesuai dengan nama hasil resolusi pada sesi ini. `additional_data`-nya menambahkan `name_match_score` ke kolom sesi duplikat yang sama. Nama yang ditulis dalam aksara berbeda di setiap sisi tidak dianggap sebagai ketidakcocokan apabila dokumen identitas kedua sesi memiliki negara penerbit yang sama, nomor dokumen atau nomor pribadi yang persis sama, serta tanggal lahir yang tidak saling bertentangan. Lihat [Peringatan liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md#pencocokan-wajah-lintas-sesi).

## Peringatan pencocokan wajah

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | Kemiripan pencocokan wajah rendah | Fitur wajah pada gambar yang diberikan tidak terlalu mirip dengan gambar referensi, yang menunjukkan potensi ketidakcocokan identitas. |
| `NO_REFERENCE_IMAGE` | Tidak ada gambar sumber yang ditemukan untuk melakukan pencocokan wajah | Gambar referensi untuk perbandingan wajah tidak ada, sehingga sistem tidak dapat menyelesaikan proses pencocokan wajah. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Upaya pencocokan wajah maksimum terlampaui | Jumlah maksimum upaya pengambilan gambar untuk pencocokan wajah telah tercapai. Status yang dihitung dari upaya terakhir (ditolak atau dalam peninjauan) telah diterapkan. |

## Contoh — ditolak karena serangan wajah

```json theme={null}
{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "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": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}
```

## Contoh — dalam peninjauan karena kemiripan rendah

```json theme={null}
{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "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": "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"
        }
      ]
    }
  ]
}
```

Skor tersebut (58.70) berada di antara ambang batas penolakan (bawaan 50) dan ambang batas peninjauan (bawaan 70), sehingga peringatan memuat `log_type: "warning"` dan status pencocokan wajah adalah `In Review`. Pada contoh ini, peringatan terpicu pada sesi dengan `session_id` `11111111-2222-3333-4444-555555555555` — `source_image_session_id` memuat id sesi itu sendiri karena referensi berasal dari potret yang disimpan saat pembuatan sesi.

## Jenis peringatan

Setiap risiko diberi jenis peringatan berdasarkan konfigurasi aplikasi Anda. Peringatan terbagi ke dalam tiga kategori tingkat keparahan:

## Terkait

> [card] [Laporan Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/report-biometric-authentication.md)
>
> Tempat `liveness_checks[]` dan `face_matches[]` muncul dalam keputusan V3.

> [card] [Peringatan liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md)
>
> Referensi lengkap peringatan liveness termasuk pencocokan wajah duplikat.

> [card] [Peringatan Pencocokan Wajah](https://docs.didit.me/id/core-technology/face-match/warnings-face-match.md)
>
> Referensi lengkap peringatan pencocokan wajah untuk perbandingan 1:1.


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