Panduan Integrasi dan Evaluasi API Verifikasi ID (ID)

API verifikasi ID memungkinkan aplikasi mengumpulkan atau mengirimkan bukti identitas dan menerima hasil terstruktur mengenai orang yang diklaim. Bergantung pada alur kerja, API ini dapat memvalidasi dokumen identitas, mengekstrak atribut, membandingkan pemohon langsung dengan potret referensi, memeriksa keaktifan, menguatkan data, atau mengatur beberapa pemeriksaan dalam satu sesi.

Respons API adalah bukti, bukan keputusan bisnis yang lengkap. Integrasi produksi juga harus menentukan penangkapan yang tepercaya, kepemilikan status pelanggan, transisi status, percobaan ulang, peninjauan, privasi, pencatatan, dan kebijakan yang mengubah hasil teknis menjadi persetujuan, percobaan ulang, peningkatan, peninjauan, atau penolakan.

Poin-poin penting

• API verifikasi ID lebih dari satu titik akhir. Kontrak sebenarnya mencakup penangkapan, status asinkron, bukti, peristiwa, rekonsiliasi, peninjauan, dan penghapusan.
• Backend yang memiliki keputusan. Pengalihan klien atau layar keberhasilan visual tidak bersifat otoritatif; status akhir harus dikonfirmasi di sisi server.
• Hasil memerlukan cakupan dan alasan. Keaslian dokumen, hubungan pemegang, keaktifan, kualitas, dan risiko kontekstual harus tetap terpisah daripada digabungkan menjadi boolean yang tidak dapat dijelaskan.
• Keandalan muncul dalam jalur kegagalan. Idempotensi, verifikasi webhook, pemutaran ulang peristiwa, batas waktu, percobaan ulang, pembuatan versi, dan kesetaraan kotak pasir sama pentingnya dengan jalur yang berhasil.
• Evaluasi harus menggunakan populasi seperti produksi. Cakupan, resistensi penipuan, penyelesaian, hasil yang salah, beban peninjauan, dan privasi harus diukur berdasarkan dokumen, perangkat, geografi, dan segmen pengguna yang relevan.

Apa yang dilakukan API verifikasi ID?

API verifikasi ID menyediakan antarmuka yang dapat dibaca mesin untuk kemampuan pembuktian identitas. Integrasi tipikal membuat upaya verifikasi, mengarahkan pemohon melalui pengalaman penangkapan yang aman, menerima peristiwa kemajuan atau penyelesaian, mengambil bukti akhir, dan menerapkan kebijakan organisasi yang mengandalkan.

Model pembuktian identitas NIST SP 800-63A-4 memisahkan tiga fungsi penting:

• Resolusi: membedakan orang yang diklaim dalam populasi yang relevan.
• Validasi: menentukan apakah bukti dan atribut identitas asli, akurat, dan dapat diterima.
• Verifikasi: menetapkan bahwa pemohon adalah subjek yang terkait dengan bukti tersebut.

Sebuah API dapat melakukan satu, dua, atau ketiga-tiganya. Nama produk tidak menjamin cakupan, jadi persyaratan harus menyatakan kesimpulan persis yang diharapkan dari setiap hasil.

Perbandingan API verifikasi ID, API dokumen, API KYC, dan OCR

Antarmuka	Tujuan utama	Output yang berguna	Apa yang tidak dibuktikannya sendiri
API OCR	Mengubah piksel dokumen menjadi teks atau bidang	Nama, tanggal, nomor, alamat yang diekstraksi	Keaslian, kepemilikan, atau risiko pelanggan
API verifikasi dokumen	Memvalidasi dokumen dan bukti yang ditangkap	Pemeriksaan keaslian, kedaluwarsa, konsistensi bidang, indikator "tamper"	Bahwa pemohon saat ini memilikinya
API pencocokan wajah	Membandingkan wajah yang dikirimkan dengan referensi	Keputusan kesamaan atau pencocokan pada ambang batas	Keaktifan, keaslian dokumen, atau identitas hukum
API keaktifan	Memperkirakan kehadiran langsung saat pengambilan biometrik	Bona fide, serangan, percobaan ulang, atau bukti skor	Identitas orang tersebut
API verifikasi ID	Menggabungkan validasi bukti dan tautan pemohon	Hasil tingkat bukti dan hasil alur kerja	KYC lengkap atau kelayakan bisnis
API KYC	Mendukung alur uji tuntas pelanggan yang lebih luas	Identitas, penyaringan, risiko, alur kerja, dan catatan	Kepatuhan otomatis tanpa kebijakan organisasi

Perbedaan ini mencegah kesalahan arsitektur. Misalnya, menambahkan OCR ke formulir unggah membuat entri data lebih cepat tetapi tidak mengautentikasi dokumen. Menambahkan pencocokan wajah menghubungkan dua gambar tetapi tidak dapat menetapkan apakah salah satu gambar berasal dari penangkapan tepercaya dan langsung.

Untuk konteks kebijakan yang lebih luas, penyaringan, risiko, dan peninjauan berkelanjutan di sekitar antarmuka ini, lihat panduan siklus hidup KYC. Artikel ini tetap berada di batas kepercayaan pengembang: penangkapan, status API, bukti, peristiwa, rekonsiliasi, dan keputusan backend.

Model integrasi umum

Sesi verifikasi yang dihosting

Backend aplikasi membuat sesi dan menerima URL atau token berumur pendek. Pengguna menyelesaikan penangkapan dalam perjalanan yang dihosting penyedia, lalu kembali ke aplikasi. Model ini dapat mengurangi kompleksitas frontend dan perangkat sambil mempertahankan kontrol sisi server.

Pertanyaan kunci meliputi branding, serah terima domain, aksesibilitas, lokalisasi, dukungan browser seluler, kedaluwarsa sesi, perilaku pengembalian, dan bagaimana aplikasi dilanjutkan saat pengguna beralih perangkat.

SDK web atau seluler tertanam

SDK menjalankan pengalaman penangkapan di dalam aplikasi. Ini dapat memberikan kontrol antarmuka yang lebih ketat dan akses ke kemampuan perangkat, tetapi kualitas integrasi memengaruhi keamanan. Dukungan versi, integritas aplikasi, izin kamera, penanganan kamera virtual, kebijakan pembaruan, dan telemetri menjadi bagian dari peninjauan.

Pemeriksaan server-ke-server mandiri

Sistem pelanggan mengirimkan data atau media terstruktur langsung ke titik akhir. Ini berguna untuk penangkapan yang sudah tepercaya, operasi batch, atau modul individual. Ini juga menggeser tanggung jawab untuk integritas penangkapan, persetujuan, kualitas, keamanan payload, dan pencegahan pemutaran ulang ke integrator.

Alur kerja yang diatur

Satu sesi dapat bercabang di seluruh validasi dokumen, pemeriksaan basis data, keaktifan, pencocokan wajah, penyaringan, sinyal perangkat, dan peninjauan manual. API harus mengekspos versi alur kerja dan kebijakan sehingga status yang sama dapat ditafsirkan nanti.

Urutan integrasi yang aman

1. Buat upaya dari backend

Backend tepercaya menghasilkan referensi pelanggan internal dan memanggil penyedia dengan alur kerja, lokal, dan konteks kebijakan yang diperlukan. Jangan mengekspos kredensial API permanen dalam kode browser atau seluler.

Gunakan strategi idempotensi untuk operasi pembuatan. Batas waktu klien seharusnya tidak membuat upaya kedua yang dapat ditagih atau melepaskan hasil dari pelanggan asli.

2. Keluarkan serah terima penangkapan berumur pendek

Berikan frontend hanya token atau URL terbatas yang diperlukan untuk upaya tersebut. Ikat ke aplikasi yang diharapkan, referensi pelanggan, alur kerja, dan kedaluwarsa. Hindari menempatkan data pribadi yang tidak perlu di URL, peristiwa analitik, atau log klien.

3. Tangkap dan validasi bukti

Pandu pengguna melalui bukti yang didukung dan persyaratan kualitas. Pisahkan masalah kualitas yang dapat dipulihkan dari dugaan serangan. "Mendekat," "dokumen kedaluwarsa," dan "integritas penangkapan gagal" seharusnya tidak menjadi satu kesalahan umum.

4. Menerima peristiwa yang diautentikasi

Perlakukan webhook sebagai masukan yang tidak tepercaya sampai diverifikasi. Validasi tanda tangan peristiwa atau autentikasi pesan, stempel waktu atau kontrol kebaruan, tujuan yang diharapkan, jenis konten, dan pengidentifikasi peristiwa. RFC 9421 mendefinisikan mekanisme umum untuk Tanda Tangan Pesan HTTP, meskipun penyedia dapat menggunakan skema penandatanganan terdokumentasi yang berbeda.

Simpan pengidentifikasi peristiwa dan proses secara idempoten. Sistem pengiriman mencoba lagi; peristiwa duplikat adalah hal yang normal. Jangan berasumsi urutan kedatangan, dan jangan biarkan peristiwa yang lebih lama menggerakkan pelanggan mundur dari keadaan terminal.

5. Ambil hasil kanonik

Setelah peristiwa penyelesaian, ambil upaya akhir dari API penyedia. Langkah rekonsiliasi ini mengurangi ketergantungan pada isi satu webhook dan pulih dari pengiriman yang terlewat atau tertunda.

6. Terapkan kebijakan organisasi

Petakan bukti terstruktur ke dalam status keputusan organisasi sendiri. Penyedia dapat merekomendasikan hasil, tetapi organisasi yang mengandalkan mengetahui produk, riwayat pelanggan, dasar hukum, selera risiko, dan jalur pemulihan yang tersedia.

7. Catat transisi

Pertahankan referensi pelanggan internal, pengidentifikasi upaya penyedia, alur kerja dan versi, bukti atau referensi yang relevan, kode alasan, riwayat peristiwa, versi kebijakan, tindakan peninjau, dan alasan akhir. Minimalkan data sensitif yang disalin saat referensi yang tahan lama sudah cukup.

Model status yang harus diekspos oleh API

Bidang boolean verified terlalu kecil untuk perjalanan pelanggan yang sebenarnya. Status yang berguna sering kali mencakup:

Status	Makna	Tindakan aplikasi yang umum
Dibuat	Upaya ada tetapi penangkapan belum dimulai	Sajikan atau kirim ulang serah terima yang aman
Sedang Berlangsung	Pengguna atau pemeriksaan asinkron aktif	Tunggu; jangan berikan akses akhir
Menunggu Masukan	Diperlukan lebih banyak bukti atau tindakan pengguna	Tampilkan panduan pemulihan yang tepat
Percobaan Ulang Diizinkan	Penangkapan atau kualitas gagal dapat dipulihkan	Mulai upaya baru yang terikat
Dalam Peninjauan	Peninjau terlatih memiliki kasus tersebut	Biarkan akses tertunda dan ekspos langkah selanjutnya yang diharapkan
Disetujui	Bukti yang diperlukan memenuhi alur kerja yang dikonfigurasi	Terapkan kebijakan organisasi dan transisi status
Ditolak	Bukti gagal kontrol yang ditentukan	Terapkan banding, pembatasan, atau jalur alternatif
Kedaluwarsa atau Ditinggalkan	Upaya berakhir tanpa keputusan	Izinkan memulai ulang yang terkontrol
Kesalahan Teknis	Sistem tidak dapat menghasilkan bukti	Coba lagi atau rekonsiliasi tanpa memperlakukannya sebagai penipuan

Setiap status terminal harus memiliki alasan terstruktur. Kode mesin yang stabil memungkinkan kebijakan dan analitik; pesan manusia yang dilokalisasi membantu pengguna dan peninjau. RFC 9457 menyediakan format standar untuk detail masalah HTTP yang dapat dibaca mesin pada tingkat antarmuka.

Bukti apa yang harus terkandung dalam hasil?

Bukti tingkat dokumen

Sertakan jenis bukti, negara penerbit, kelas dokumen, kedaluwarsa, konsistensi bidang, kualitas, dan indikator validasi yang relevan dengan metode. Jelaskan apakah hasilnya berasal dari inspeksi optik, data chip, penguatan penerbit atau basis data, atau sumber lain.

Bukti tautan pemohon

Jaga agar perbandingan wajah, keaktifan, integritas penangkapan, dan tautan atribut identitas terpisah. Catat referensi yang digunakan dan ambang batas keputusan atau versi yang diperlukan untuk interpretasi nanti tanpa mengekspos materi biometrik yang tidak perlu ke setiap konsumen.

Bukti risiko dan operasional

Sinyal perangkat, IP, kecepatan, upaya berulang, atau alur kerja dapat memandu peningkatan dan peninjauan. Mereka seharusnya tidak secara diam-diam mengubah atribut identitas. Pertahankan subsistem mana yang menghasilkan setiap alasan.

Asal dan versi

Hasil dapat berubah ketika model, templat dokumen, daftar pantauan, atau kebijakan berubah. Simpan versi penyedia, versi alur kerja, waktu keputusan, referensi sumber, dan apakah manusia meninjau kasus tersebut.

Persyaratan keamanan API

API identitas memproses data pribadi dan biometrik yang berharga serta mengekspos alur bisnis yang dapat diotomatisasi oleh penyerang. OWASP API Security Top 10 menyoroti risiko yang secara langsung relevan di sini: otorisasi objek yang rusak, autentikasi yang rusak, eksposur properti yang berlebihan, konsumsi sumber daya yang tidak terbatas, otomatisasi alur sensitif, inventaris API yang buruk, dan kepercayaan yang tidak aman pada API pihak ketiga.

Autentikasi dan otorisasi

Gunakan kredensial dan aplikasi terpisah untuk pengujian dan produksi. Terapkan hak istimewa terkecil, rotasi, pencabutan, isolasi lingkungan, dan otorisasi tingkat objek. Organisasi yang diautentikasi seharusnya tidak dapat mengambil upaya organisasi lain dengan mengubah pengidentifikasi.

Kontrol unggahan dan sumber daya

Validasi jenis media, ukuran, dimensi, struktur, dan sumber yang diharapkan. Tetapkan batas waktu, batas konkurensi, kontrol tarif, dan batas upaya. Panggilan verifikasi mengkonsumsi komputasi dan dapat membawa biaya per pemeriksaan, membuat titik akhir yang tidak terbatas menjadi risiko penolakan layanan dan biaya.

Eksposur data

Kembalikan hanya bidang yang dibutuhkan konsumen. Pisahkan peran operasional sehingga dukungan, analis, pengembang, dan administrator tidak semuanya menerima bukti identitas penuh secara default. Redaksi payload sensitif dari log dan alat observabilitas.

Kontrol webhook dan pemutaran ulang

Autentikasi peristiwa, pertahankan badan mentah yang diperlukan untuk verifikasi tanda tangan, tolak pengiriman yang usang atau salah bentuk, deduplikasi pengidentifikasi peristiwa, dan ambil status kanonik. Putar rahasia webhook tanpa merusak pengiriman yang sedang berlangsung.

Inventaris dan pembuatan versi

Dokumentasikan setiap titik akhir aktif, versi, host, kredensial, panggilan balik, SDK, dan tanggal penghentian. Titik akhir uji bayangan dengan data produksi atau SDK lama yang tidak terawat dapat merusak jalur yang ditinjau.

Cara menguji API verifikasi ID

Uji kontrak dan status

Lakukan setiap status, alasan, percobaan ulang, batas waktu, dan transisi terminal yang didokumentasikan. Verifikasi penomoran halaman, pemfilteran, badan kesalahan, kompatibilitas mundur, dan perilaku bidang yang tidak diketahui. Simulasikan webhook duplikat dan tidak berurutan.

Uji bukti

Gunakan sampel yang diizinkan dan representatif di seluruh jenis dokumen, negara, skrip, kondisi kedaluwarsa, perangkat, kamera, dan jaringan dalam populasi yang diharapkan. Lacak bukti yang tidak didukung, tidak dapat dibaca, tidak cocok, dimanipulasi, dan asli secara terpisah.

Uji penipuan

Bangun set serangan yang diotorisasi untuk pemutaran ulang, bukti cetak, dokumen yang diubah, kamera virtual, emulator, media yang disuntikkan, identitas berulang, dan upaya otomatis. Persyaratan pembuktian jarak jauh NIST membedakan kepercayaan sensor penangkapan, analisis media palsu, saluran yang dilindungi, dan perbandingan biometrik karena tidak ada satu mekanisme pun yang mencakup jalur penuh.

Uji operasional

Ukur penyelesaian, percobaan ulang, pengabaian, tingkat peninjauan manual, waktu penyelesaian, kontak dukungan, penundaan webhook, rekonsiliasi, dan ketersediaan. Uraikan hasil berdasarkan dokumen, perangkat, jaringan, bahasa, dan kelompok pelanggan yang relevan.

Uji kualitas keputusan

Jangan membandingkan penyedia dengan satu angka "akurasi". Tinjau penerimaan palsu dan penolakan palsu pada ambang batas yang dimaksudkan, hasil spesifik serangan, jumlah sampel, kepercayaan diri, kasus tanpa respons, dan hasil yang dikonfirmasi di hilir.

Uji privasi dan penghapusan

Verifikasi konfigurasi retensi, ekspor, penghapusan, log akses, penanganan regional, kontrol subprosesor, dan perilaku ketika permintaan penghapusan tiba selama peninjauan terbuka atau penangguhan yang diwajibkan secara hukum.

Cara mengevaluasi penyedia

Cakupan dan jaminan

Fungsi pembuktian apa yang disertakan? Model jaminan dan pengujian independen apa yang berlaku? Komponen dan versi mana yang diuji? Bisakah penyedia menjelaskan apa arti sebuah "lulus" dan "tidak lulus"?

Cakupan

Minta matriks negara dan dokumen, bukan hanya total. Uji bukti yang disajikan pelanggan Anda, termasuk perangkat lama, beberapa skrip, kamera berkualitas rendah, dan dokumen yang tidak biasa tetapi sah.

Pengalaman pengembang

Tinjau konsistensi API, kualitas OpenAPI, pemeliharaan SDK, contoh, skenario kotak pasir, alat webhook, disiplin changelog, kebijakan migrasi, halaman status, dan eskalasi dukungan. Contoh jalur sukses lima baris bukanlah panduan integrasi produksi.

Operasi dan kemampuan menjelaskan

Periksa antrean peninjauan, tampilan bukti, izin peran, log audit, kode alasan, banding, dan ekspor. Konfirmasikan bahwa manusia dapat membedakan kegagalan teknis, percobaan ulang kualitas, kemungkinan serangan, dan ketidakcocokan identitas.

Komersial dan portabilitas

Pahami penagihan berbasis keberhasilan versus berbasis upaya, biaya peninjauan, minimum, batas, penyimpanan, opsi regional, dan ketentuan keluar. Pertahankan referensi pelanggan internal dan batas kebijakan Anda dapat dipindahkan sehingga perubahan penyedia tidak memerlukan penulisan ulang status akun.

Kesalahan integrasi umum

Memberikan akses dari URL pengembalian

Pengguna mengontrol jalur browser. Pengalihan sukses adalah status antarmuka, bukan bukti. Konfirmasi status akhir dari backend tepercaya.

Memperlakukan setiap kegagalan sebagai penipuan

Penolakan izin, batas waktu, bukti tidak didukung, buram, dan dugaan manipulasi berbeda. Mencampurkannya menciptakan penolakan palsu dan analitik yang tidak dapat digunakan.

Memproses webhook tepat sekali

Jaringan tidak dapat menjanjikan pengiriman tepat sekali. Desain untuk peristiwa setidaknya sekali dengan deduplikasi, transisi monoton, dan pengambilan kanonik.

Mencatat payload lengkap

Pencatatan debug yang nyaman dapat menyalin dokumen dan data biometrik ke dalam sistem dengan akses yang lebih luas dan retensi yang lebih lama. Gunakan pengidentifikasi, alasan terstruktur, dan akses bukti yang terkontrol.

Menguji hanya kasus sukses kotak pasir

Kegagalan produksi terjadi dalam percobaan ulang, perangkat lama, dokumen tepi, penundaan peristiwa, perubahan versi, dan peninjauan. Jadikan skenario kegagalan sebagai bagian dari rangkaian penerimaan.

Mengalihdayakan keputusan kebijakan

Hasil vendor tidak dapat mengetahui setiap yurisdiksi, jenis pelanggan, risiko produk, atau batasan bisnis. Pertahankan logika keputusan dan akuntabilitas organisasi.

Daftar periksa implementasi

Sebelum produksi, konfirmasikan bahwa:

• Kredensial API tetap berada di sisi server dan dicakup oleh lingkungan dan peran;
• panggilan pembuatan idempoten dan dipetakan ke referensi pelanggan internal yang stabil;
• token penangkapan berumur pendek dan terikat pada upaya yang diharapkan;
• setiap status dan alasan memiliki tindakan pelanggan dan backend yang eksplisit;
• tanda tangan webhook, kebaruan, duplikat, dan urutan diuji;
• pengambilan kanonik merekonsiliasi peristiwa yang terlewat atau tertunda;
• output tingkat bukti tetap terpisah dari keputusan pelanggan akhir;
• kontrol tarif, unggah, konkurensi, dan upaya menahan penyalahgunaan otomatis;
• pengujian dokumen, perangkat, penipuan, privasi, aksesibilitas, dan peninjauan menggunakan sampel seperti produksi;
• retensi, penghapusan, respons insiden, pembuatan versi, dan migrasi memiliki pemilik.

Menggunakan Didit untuk verifikasi ID

Didit menyediakan Verifikasi ID sebagai modul yang dapat disusun dan memungkinkan tim menambahkan Deteksi Keaktifan, Analisis Perangkat dan IP, serta jalur bersyarat melalui Orkestrator Alur Kerja. Harga Verifikasi ID mandiri yang dipublikasikan adalah $0.15, sedangkan bundel KYC $0.33 yang dipublikasikan menggabungkan Verifikasi ID, Keaktifan Pasif, Pencocokan Wajah, dan Analisis IP.

Halaman harga mencantumkan tarif modul saat ini, dan tingkat gratis adalah 500 verifikasi gratis per bulan. Hasil produk tersebut harus memberi makan kebijakan dan status pelanggan yang dimiliki backend daripada menggantikannya.

Pertanyaan yang sering diajukan

Apa itu API verifikasi ID?

Ini adalah antarmuka terprogram untuk mengumpulkan atau mengirimkan bukti identitas dan menerima hasil terstruktur tentang validitas bukti dan tautan pemohon ke identitas yang diklaim.

Apakah API verifikasi ID sama dengan API KYC?

Belum tentu. Verifikasi ID berfokus pada bukti identitas dan tautan pemegang. API KYC juga dapat mencakup penyaringan, risiko pelanggan, alur kerja, peninjauan, catatan, dan penyegaran berkelanjutan.

Haruskah verifikasi identitas dijalankan dari frontend?

Antarmuka penangkapan dapat berjalan di frontend, tetapi kredensial permanen, pembuatan sesi, pengambilan hasil akhir, keputusan kebijakan, dan perubahan status pelanggan berada di backend tepercaya.

Mengapa webhook dibutuhkan?

Banyak pemeriksaan dan peninjauan bersifat asinkron. Webhook memberi tahu aplikasi tentang perubahan, sementara titik akhir pengambilan menyediakan status kanonik untuk rekonsiliasi.

Bagaimana seharusnya webhook duplikat ditangani?

Verifikasi setiap peristiwa, simpan pengidentifikasinya, proses secara idempoten, cegah status yang lebih lama menimpa status terminal yang lebih baru, dan ambil upaya kanonik jika perlu.

Apa yang harus disertakan dalam kotak pasir?

Ini harus mereproduksi kontrak produksi dan menyediakan kasus deterministik untuk keberhasilan, percobaan ulang, penolakan, peninjauan, kedaluwarsa, kesalahan teknis, peristiwa duplikat, peristiwa tertunda, dan kode alasan yang relevan.

Bisakah API membuat perusahaan patuh?

Tidak. API dapat menyediakan bukti dan hasil alur kerja. Organisasi tetap bertanggung jawab atas analisis hukum, kebijakan, keputusan pelanggan, pengecualian, catatan, privasi, dan kontrol berkelanjutan.

Referensi utama

• NIST SP 800-63A-4: Pembuktian dan Pendaftaran Identitas
• OWASP API Security Top 10 — 2023
• RFC 9110: Semantik HTTP
• RFC 9421: Tanda Tangan Pesan HTTP
• RFC 9457: Detail Masalah untuk API HTTP

Integrasi verifikasi ID yang kuat membuat setiap batas kepercayaan eksplisit: siapa yang membuat upaya, bagaimana bukti ditangkap, hasil mana yang kanonik, bagaimana peristiwa diautentikasi, apa arti setiap alasan, dan sistem mana yang memiliki keputusan pelanggan akhir.