Lewati ke konten utama

Buat Proses

Endpoint ini menangani tiga produk yang berbagi path yang sama tetapi berbeda dalam parameter body, kapabilitas, dan field respons:

  • Integrasi — memvalidasi siapa pengguna tersebut dengan membandingkan wajah mereka dengan basis identitas Unico (subject.duiType + subject.code diperlukan).
  • Transaksional — memverifikasi bahwa ini adalah orang yang sama dari proses sebelumnya dengan membandingkan wajah-dengan-wajah (referenceProcessId ATAU array references dengan selfie / process id diperlukan).
  • Cardholder Verification — memastikan bahwa sebuah kartu adalah milik pemegang yang dinyatakan, tanpa pengambilan selfie apa pun (subject.code + card diperlukan). Secara opsional menggunakan kembali proses yang telah divalidasi sebelumnya melalui referenceProcessId untuk memicu gate penggunaan kembali; tanpa itu, respons akan default ke unsure. Lihat kapabilitas Cardholder Verification.

Produk aktif ditentukan oleh APIKEY yang dikirim di header permintaan.

Untuk alur integrasi lengkap, lihat Ringkasan API.

Endpoint

LingkunganURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Permintaan

Headers
HeaderNilai
AuthorizationBearer <access_token> (lihat Autentikasi)
APIKEYAPI key yang telah disediakan — menentukan produk aktif dan kapabilitas yang diaktifkan.
Content-Typeapplication/json
Parameter body
FieldTipeWajibDeskripsi
subject.duiTypeintegeryaPengidentifikasi tipe dokumen. Lihat nilai duiType di bawah.
subject.codestringyaNilai pengenal sebagaimana didefinisikan oleh subject.duiType. Tanpa titik atau tanda hubung.
subject.namestringtidakNama lengkap.
subject.genderstringtidakM atau F.
subject.birthDatestring (ISO 8601)tidakTanggal lahir (YYYY-MM-DD).
subject.emailstringtidakAlamat email.
subject.phonestringtidakNomor telepon E.164.
subject.clientReferencestringkondisionalPengidentifikasi unik pengguna dalam sistem Anda. Wajib untuk kemampuan Multi Akun. Unik dalam basis Anda, maksimal 256 karakter, tanpa spasi.
useCasestringtidakKonteks operasi, misalnya Onboarding.
subsidiaryIdstringtidakID cabang — diperlukan hanya jika terdapat beberapa cabang.
imageBase64stringyaSelfie yang ditangkap oleh front-end Anda, dalam base64.
Nilai duiType
NegaraKodeDeskripsi
BR1CPF Brasil
MX2CURP Meksiko
US4SSN Amerika Serikat
BR5Paspor Brasil
AR6Paspor Argentina
AR7DNI Argentina
NG8NIN Nigeria
CL9RUN Chili
EC10NI Ekuador
US11Paspor Amerika Serikat
GT12CUI Guatemala
UY13CI Uruguay
BR14CNPJ Brasil
ZZ15Alamat email
ID16NIK Indonesia
ZZ17Nomor telepon
US18SIM Amerika Serikat
NG20Nomor Verifikasi Bank Nigeria (BVN)
US21Kartu Paspor Amerika Serikat
US22Paspor Polikarbonat Amerika Serikat
US23Kartu Identitas Amerika Serikat
TR24Nomor Identifikasi Turki (TCKN)
MX25RFC Meksiko (Perorangan)
CO26NIT Kolombia
PE27RUC Peru
CA28SIN Kanada
DK29CPR Denmark
GB30Nomor Asuransi Nasional Inggris (NINO)
PL31PESEL Polandia
SE32Nomor Pribadi Swedia (PNR)
CH33Nomor AHV/AVS Swiss
AT34Nomor Pajak Austria (STNR)
FI35Kode Identitas Pribadi Finlandia (HETU)
BE36Nomor Nasional Belgia (NN)
IT37Codice Fiscale Italia (CF)
SE38Nomor Koordinasi Swedia (Samordningsnummer)
NO39Nomor Identitas Nasional Norwegia (Fødselsnummer)
PE40DNI Peru
DE41Nomor Identifikasi Pajak Jerman (IdNr)
NL42Nomor Layanan Warga Negara Belanda (BSN)
NG43Token BVN Nigeria (hash)
NG44Token NIN Nigeria (hash)
PT45Nomor Identifikasi Pajak Portugal (NIF)
FR46Nomor Referensi Pajak Prancis (SPI)
IE47Nomor Layanan Publik Pribadi Irlandia (PPSN)
LU48Nomor Identifikasi Nasional Luksemburg (Matricule)
AR49SIM Argentina (Licencia Nacional de Conducir)
ES50Nomor Identitas Warga Asing Spanyol (NIE)
ES51Dokumen Identitas Nasional Spanyol (DNI)
CL52Paspor Chili
CO53Paspor Kolombia
PE54Paspor Peru
CO55SIM Kolombia (Licencia de Conducción)
CO56Kartu Kewarganegaraan Kolombia (Cédula de Ciudadanía)
CL57SIM Chili (Licencia de Conducir)
MX58SIM Meksiko (Licencia de Conducir)
0Tidak ditentukan
3Pengidentifikasi internal Unico
Persyaratan gambar
  • Resolusi minimum: 640 x 480 (standar HD)
  • Ukuran file maksimum: 800 KB (kompresi JPEG92 disarankan)
  • Format yang diterima: PNG, JPEG, WebP
  • Token JWT dari SDK kedaluwarsa setelah 10 menit dan hanya dapat digunakan sekali

Contoh

curl -X POST https://api.id.unico.app/processes/v1 \
-H "Authorization: Bearer $TOKEN" \
-H "APIKEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": {
"duiType": 1,
"code": "12345678909",
"name": "Luke Skywalker",
"gender": "M",
"birthDate": "2000-05-20",
"email": "[email protected]",
"phone": "5519725570707"
},
"useCase": "Onboarding",
"imageBase64": "/9j/4AAQSkZJR..."
}'

Respons

200 OK

Kontrak ini bersifat unik — field idCloud.result membawa keputusan konsolidasi dari kapabilitas yang digunakan.

Unico mengonsolidasikan hasil dari kapabilitas yang dijalankan menjadi satu idCloud.result, siap untuk menentukan langkah berikutnya dalam alur Anda — tanpa perlu mengorkestrasi hasil individual.

{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 3,
"idCloud": {
"result": "approved"
}
}
FieldTipeDeskripsi
idstring (UUID)Identifier proses. Gunakan dengan Dapatkan Proses untuk kueri ulang.
statusinteger1 (memproses), 3 (selesai dengan sukses), 5 (error).
Possible result values
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot enough evidence for a verdict.Route to manual review or an alternative flow.

Nilai yang dikembalikan bergantung pada recipe yang dikonfigurasi dalam APIKey Anda. Lihat Alur untuk nilai hasil yang dapat dikembalikan oleh setiap recipe.

BrazilKlien di Brasil dapat menerima respons per kapabilitas

Struktur respons secara keseluruhan tetap sama — hasil tunggal adalah default-nya.

Integrasi di Brasil dapat menerima hasil per kapabilitas yang terbuka. Setiap kapabilitas yang diaktifkan di APIKey menambahkan blok tersendiri ke respons — field untuk kapabilitas yang dinonaktifkan tidak disertakan.

{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 3,
"unicoId": { "result": "yes" },
"riskLevel": { "result": "inconclusive" },
"idFace": {
"personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
"result": "FOUND"
},
"government": { "serpro": 87 },
"liveness": 1
}
Field respons bergantung pada APIKey Anda

Contoh di atas menampilkan semua kemungkinan field kapabilitas. Respons aktual Anda hanya akan menyertakan field untuk kapabilitas yang diaktifkan dalam konfigurasi APIKey Anda — field untuk kapabilitas yang dinonaktifkan tidak disertakan sama sekali. Hubungi manajer proyek Unico Anda untuk mengaktifkan atau menyesuaikan kapabilitas.

FieldTipeDeskripsi
unicoId.resultstringyes, no, inconclusive — lihat Verifikasi Identitas.
riskLevel.resultstringapproved, reproved, risk-critical, risk-high, inconclusive — lihat nilai yang mungkin di bawah atau Klasifikasi Risiko Penipuan.
idFace.resultstringFOUND — lihat Pengidentifikasi Wajah.
idFace.personIdstringPengidentifikasi opak stabil untuk wajah, dikembalikan bersama idFace.result = FOUND. Ketika tidak ada wajah yang dapat diidentifikasi dalam gambar, permintaan gagal dengan error 20532 alih-alih mengembalikan blok idFace.
identityFraudsters.resultstringTidak digunakan lagi. Gunakan riskLevel sebagai gantinya. Klien dengan integrasi yang sedang berjalan dapat terus menggunakannya sambil mengoordinasikan migrasi dengan tim proyek yang bertanggung jawab.
government.serprointegerSkor kemiripan Serpro (0–100, -1, -2). Tersedia di Brasil saja. Lihat Hasil Kemiripan Serpro.
livenessinteger1 (lulus), 2 (gagal) — lihat Deteksi Kehidupan.
riskLevel.result — nilai yang mungkin
NilaiMakna
approvedIni adalah wajah pemegang ID, dan tidak ditemukan bukti terkait penipuan.
reprovedPenolakan direkomendasikan, karena beberapa indikator penipuan terdeteksi.
risk-criticalPenolakan direkomendasikan, namun keputusan akhir ada pada kebijaksanaan Anda. Risiko kritis menunjukkan bahwa kami menemukan setidaknya 2 bukti kuat adanya penipuan.
risk-highPenolakan juga direkomendasikan, namun keputusan tetap ada pada Anda. Risiko tinggi menunjukkan bahwa kami menemukan setidaknya satu bukti kuat adanya penipuan.
inconclusiveTidak ditemukan bukti kuat adanya penipuan. Oleh karena itu, tidak dapat disimpulkan apakah terdapat risiko yang relevan atau tidak.
informasi

Ketika unicoId.result = inconclusive dan orkestrasi Skor Risiko aktif, proses mungkin mengembalikan status: 1 (memproses). Poll Dapatkan Proses atau gunakan webhook untuk mengambil hasil akhir.

Kode Error

CodeMessageDeskripsi
40221This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.Alur penggunaan ulang (referenceProcessId/bioTokenId, tanpa gambar) ditolak karena penggunaan ulang proses tidak diaktifkan untuk API key ini.
20900O base64 informado não é válido.Parameter base64 tidak valid. Kemungkinan penyebab: bukan gambar atau percobaan injeksi.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.Resolusi gambar yang diunggah terlalu rendah.
20532No face detected in image.Tidak ada wajah yang dapat terdeteksi dalam gambar yang dikirim.
20513The referenced process was not found.referenceProcessId menunjuk ke proses yang tidak ada atau tidak lagi dapat diakses.
20512The referenced process is not available for reuse.Proses referensi ada tetapi tidak tersedia untuk digunakan kembali.
20509The subject.name field is invalid.subject.name mengandung karakter tidak valid.
20508The subject.gender field is invalid.subject.gender harus M atau F.
20507O parâmetro subject.code é inválido.CPF tidak standar atau tidak ada.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Ukuran gambar melebihi 800 KB; kompres ke JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Format base64 tidak valid atau tidak didukung.
20065The referenceProcessId field is invalid.referenceProcessId bukan UUID yang valid.
20062The useCase field is invalid.Nilai yang tidak dikenali di field useCase.
20024The referenceProcessId field is missing.Parameter referenceProcessId tidak diberikan dan references tidak dikirim sebagai alternatif. Tidak berlaku untuk Cardholder Verification — referenceProcessId-nya tidak pernah divalidasi sebagai wajib; reuse gate yang tidak terpenuhi menjawab unsure sebagai gantinya.
20533The card field is missing.Cardholder Verification: objek card tidak diberikan.
20534The card.bin field is missing.Cardholder Verification: card.bin tidak diberikan.
20535The card.last4 field is missing.Cardholder Verification: card.last4 tidak diberikan.
20536The card data is invalid.Cardholder Verification: data kartu ditolak karena tidak valid.
20021The subject.phone field is invalid.Format subject.phone tidak valid (IDD + kode area + nomor, 13 karakter).
20019The subject.birthDate field is invalid.subject.birthDate di luar format ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.Parameter gambar selfie tidak ada.
20008The subject.email field is invalid.Format email tidak valid di subject.email.
20006O parâmetro subject.name não foi informado.Parameter subject.name tidak ada.
20005O parâmetro subject.code não foi informado.Parameter subject.code tidak ada.
20004O parâmetro subject não foi informado.Parameter subject tidak ada.
20003The request body is missing or invalid.Payload null atau tidak valid.
20002O parâmetro APIKey não foi informado.Parameter APIKEY tidak ada di header permintaan.
20001O parâmetro authtoken não foi informado.Parameter token integrasi tidak ada di header permintaan.
10508The JWT with the captured face has already been used.JWT hanya dapat digunakan sekali.
10507The JWT with the captured face is expired.JWT kedaluwarsa; harus dikirim dalam 10 menit.
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 bukan JWT valid yang dihasilkan oleh SDK.

Selanjutnya

  • Untuk melihat kueri hasil proses Integrasi, lihat Dapatkan Proses.
  • Untuk melihat semua kombinasi recipe dan nilai hasil yang mungkin, lihat Alur.
  • Untuk operasi Dokumen dan Verifikasi Usia, lihat halaman masing-masing di bagian ini.