Laporan Pencocokan Wajah: JSON Skor Kecocokan

Gambaran Umum

Laporan pencocokan wajah mencatat perbandingan biometrik 1:1 antara swafoto langsung yang diambil selama deteksi liveness dan gambar referensi — yang paling umum adalah foto potret yang diekstrak dari dokumen identitas. Laporan ini menghasilkan satu skor kemiripan 0–100, URL bertanda tangan untuk kedua gambar yang dibandingkan, sesi sumber untuk gambar referensi, serta setiap peringatan yang muncul dari pencocokan tersebut. Laporan ini dibuat setelah pengguna menyelesaikan langkah deteksi liveness dan langkah dokumen dalam alur kerja (atau, untuk alur kerja berbasis potret seperti autentikasi biometrik, setelah deteksi liveness saja), atau secara langsung melalui Face Match API mandiri saat Anda menyediakan sendiri dua gambar wajah apa pun. Setiap laporan membawa status-nya masing-masing — terlepas dari status sesi secara keseluruhan — yang mencerminkan hasil penyelesaian langkah pencocokan wajah saja:

Approved — score berada di atas ambang batas peninjauan dan tidak ada peringatan penolakan otomatis yang terpicu.
In Review — score berada di antara ambang batas penolakan dan peninjauan, atau tidak ada skor yang dapat dihitung dan face_match_not_computed_action bernilai REVIEW.
Declined — score berada pada atau di bawah ambang batas penolakan, NO_REFERENCE_IMAGE terpicu, atau tidak ada skor yang dapat dihitung dan face_match_not_computed_action bernilai DECLINE.
Resub Requested — seorang peninjau meminta pengguna untuk mengirim ulang langkah ini dari konsol.
Not Finished — langkah pencocokan wajah belum menghasilkan hasil apa pun (termasuk saat pengguna sedang mencoba ulang pengambilan gambar yang gagal).

Lokasi kemunculan dalam respons API

Laporan pencocokan wajah dikirimkan di dalam array face_matches[] — selalu berupa array JSON, bukan objek tunggal face_match. Nilainya adalah null hingga setidaknya satu langkah pencocokan wajah telah menghasilkan data, dan beberapa entri akan muncul saat alur kerja menjalankan pencocokan wajah lebih dari sekali. Alur kerja Adaptive Age Verification juga mengisinya saat fallback verifikasi identitas berjalan: entri tersebut melaporkan node estimasi usia sebagai node_id-nya, karena alur kerja tersebut tidak memiliki node Pencocokan Wajah tersendiri.

API keputusan sesi — GET /v3/session/{sessionId}/decision/ mengembalikan face_matches[] di tingkat atas. Lihat Mengambil keputusan sesi.
Webhook — payload session.status.updated menyertakan array face_matches[] yang sama setelah langkah tersebut menghasilkan data. Lihat Webhook.
Face Match API mandiri — untuk perbandingan langsung 1:1, lihat API mandiri Face Match.

Baca response.face_matches[0] dan lakukan iterasi pada array tersebut — bentuk tunggal face_match yang dirujuk pada beberapa tutorial lama tidak ada pada endpoint keputusan v3.

Skema

Skema kanonik kolom demi kolom tersedia di halaman referensi Model data. Kolom-kolom di bawah ini mencerminkan skema kanonik tersebut.

Kolom	Tipe	Deskripsi
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Status langkah pencocokan wajah (`FeatureStatusChoices`).
`node_id`	string \| null	Node graf alur kerja yang menghasilkan laporan ini.
`score`	number 0–100 \| null	Skor kemiripan biometrik, dibulatkan ke 2 desimal. `null` jika tidak ada perbandingan yang dapat dilakukan.
`source_image_session_id`	string \| null	UUID sesi yang potret tersimpannya menjadi gambar referensi (sumber) — diatur dalam alur berbasis potret (autentikasi biometrik, atau potret yang diberikan saat pembuatan sesi). `null` jika gambar referensi adalah potret dokumen yang diambil dalam sesi yang sama.
`source_image`	string (URL bertanda tangan)	Gambar referensi (biasanya potret dokumen). URL bertanda tangan dengan masa berlaku singkat — unduh segera, jangan pernah menyimpan URL tersebut secara permanen.
`target_image`	string (URL bertanda tangan)	Gambar target (biasanya swafoto yang diambil saat deteksi liveness). URL bertanda tangan dengan masa berlaku singkat — unduh segera, jangan pernah menyimpan URL tersebut secara permanen.
`warnings[]`	array	Peringatan tingkat modul. Setiap entri membawa `feature` (selalu `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, dan `node_id` — lihat Peringatan pencocokan wajah.

Nilai status

Status	Arti	Efek lanjutan
`Approved`	Skor di atas ambang batas peninjauan dan tidak ada peringatan penolakan otomatis yang terpicu.	Dihitung sebagai pencocokan wajah yang berhasil.
`In Review`	Skor di atas ambang batas penolakan tetapi pada atau di bawah ambang batas peninjauan, atau tidak ada skor yang dapat dihitung (`FACE_MATCH_NOT_COMPUTED`, misalnya setelah pencarian non-dokumen yang tidak menyisakan referensi) dengan `face_match_not_computed_action` diatur ke `REVIEW`.	Sesi juga beralih ke `In Review` hingga peninjau mengambil tindakan.
`Declined`	Skor pada atau di bawah ambang batas penolakan, `NO_REFERENCE_IMAGE` terpicu, atau tidak ada skor yang dapat dihitung dengan `face_match_not_computed_action` diatur ke `DECLINE`.	Sesi ditolak kecuali ada cabang lain yang disetujui yang memenuhi alur kerja.
`Resub Requested`	Peninjau meminta pengiriman ulang langkah ini dari konsol.	Pengguna diminta untuk mengambil gambar kembali.
`Not Finished`	Langkah pencocokan wajah belum menghasilkan hasil apa pun (input hilang, alur kerja tidak pernah mencapai langkah perbandingan, atau pengguna masih dalam siklus coba ulang pengambilan gambar).	Cabang tidak selesai.

Kegagalan akibat kemiripan rendah akan dicoba ulang sebelum status ditetapkan secara permanen: pengguna mendapatkan hingga face_match_max_attempts pengambilan gambar (secara default 3), dan hanya skor dari percobaan terakhir yang diterapkan. Aturan status kustom yang dikonfigurasikan pada node alur kerja dapat menyesuaikan status yang dihasilkan lebih lanjut, digabungkan dengan status yang ditentukan berdasarkan skor, dengan urutan prioritas Declined > In Review > Approved.

Contoh

Approved — kecocokan bersih

{
  "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": []
    }
  ]
}

In Review — kemiripan di ambang batas

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

Declined — tidak ada gambar referensi untuk dibandingkan

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

Catatan keamanan

URL bertanda tangan untuk source_image dan target_image merupakan data biometrik dan memiliki masa berlaku yang singkat. Perlakukan URL tersebut sebagai data berumur pendek: jangan menyimpannya dalam cache atau menampilkannya secara publik. Biasanya aplikasi Anda hanya membutuhkan status dan score — simpan data sesedikit mungkin untuk meminimalkan data biometrik di server Anda.

Terkait

Peringatan pencocokan wajah — enum peringatan lengkap, penyebab, dan remediasi.
Laporan liveness — langkah sebelumnya yang mengambil gambar target.
Webhook — pantau session.status.updated untuk menerima laporan.
Model data — Pencocokan wajah — skema kanonikal dengan setiap kolom.

Autentikasi

Verifikasi

Pemantauan

Platform

Laporan Pencocokan Wajah: JSON Skor Kecocokan

Gambaran Umum

Lokasi kemunculan dalam respons API

Skema

Nilai status

Contoh

Approved — kecocokan bersih

In Review — kemiripan di ambang batas

Declined — tidak ada gambar referensi untuk dibandingkan

Catatan keamanan

Terkait

​Gambaran Umum

​Lokasi kemunculan dalam respons API

​Skema

​Nilai status

​Contoh

​Approved — kecocokan bersih

​In Review — kemiripan di ambang batas

​Declined — tidak ada gambar referensi untuk dibandingkan

​Catatan keamanan

​Terkait

Gambaran Umum

Lokasi kemunculan dalam respons API

Skema

Nilai status

Contoh

Approved — kecocokan bersih

In Review — kemiripan di ambang batas

Declined — tidak ada gambar referensi untuk dibandingkan

Catatan keamanan

Terkait