Buat ProsesPOST

Buat proses Human Token dari back-end Anda dan dapatkan humanToken di data.humanToken.

Markdown

Human Token berjalan di endpoint Human API POST /client/v1/process. Dengan alur API Only (api+humantoken, api+liveness+humantoken, dan api+liveness+humantoken+revalidation), proses dibuat dan diselesaikan dalam satu panggilan: respons sudah membawa hasilnya di data.humanToken. Dengan alur Human Token Journey (humantoken dan humantoken+revalidation), respons membawa id proses, sebuah token, dan link perjalanan, dan hasilnya tersedia setelah pengguna menyelesaikan perjalanan. Alur +revalidation memerlukan array references berisi humanToken yang diperoleh sebelumnya untuk revalidasi.

Alur

Human Token berjalan dalam dua model integrasi:

• API Only — back-end Anda mengirim selfie di imageBase64.
• Human Token Journey — pengguna menjalani perjalanan Unico di Web dan kembali ke callbackUri Anda.

Flow	Capabilities	Possible result	Integration components required	Example
api+humantoken	Human Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken	LivenessHuman Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	LivenessHuman Token	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb
humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb

Endpoint

Lingkungan	URL
Produksi	POST https://humantoken.unico.app/client/v1/process

Permintaan

Headers

Header	Nilai
x-unico-accesskey	<your_access_key> (lihat Autentikasi)
Content-Type	application/json

Parameter body

Field	Tipe	Wajib	Deskripsi
flow	string	ya	Alur Human Token: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) atau humantoken, humantoken+revalidation (Human Token Journey). Lihat Alur.
imageBase64	string	API Only	Selfie, diambil oleh front-end Anda dan dikirim secara langsung, dalam base64. PNG, JPEG, atau WebP, hingga 800 KB. Ikuti Capture Standard.
callbackUri	string	Human Token Journey	URL tempat pengguna diarahkan setelah perjalanan berakhir.
companyBranchId	string	tidak	Pengenal branch. Jika disediakan, proses menggunakan konfigurasi branch yang ditentukan.
references	array	Alur revalidasi	Array objek referensi. Wajib untuk alur +revalidation. Setiap objek memiliki referenceType (REFERENCE_TYPE_HUMAN_TOKEN) dan referenceContent (nilai humanToken yang diperoleh sebelumnya).

Respons

200 OK

Field	Tipe	Deskripsi
id	string (UUID)	Pengenal proses. Gunakan untuk mengambil proses kembali melalui Dapatkan Proses.
state	string	Status proses — lihat Menafsirkan hasil. Hanya pada alur API Only.
token	string	Token dari proses yang dibuat, Anda dapat menggunakannya untuk membuka pengalaman Journey SDK. Hanya dalam alur Human Token Journey (humantoken, humantoken+revalidation).
link	string	URL Human Token Journey: arahkan pengguna ke URL ini. Hanya pada alur Human Token Journey (humantoken, humantoken+revalidation).
data.​humanToken.​value	string	Pengenal wajah yang stabil dan buram (hingga 100 karakter). Orang yang sama selalu menghasilkan nilai yang sama. Hanya pada alur API Only (non-revalidasi).
data.​humanTokenMatch	string	"true" jika selfie cocok dengan humanToken yang direferensikan, "false" jika tidak. Hanya pada alur +revalidation API Only.

Menafsirkan hasil

state	Makna	Yang harus dilakukan
PROCESS_STATE_FINISHED	data.humanToken.value terisi: orang nyata, dengan Human Token.	Cari value di catatan Anda: jika ada, itu adalah pengguna yang kembali atau kemungkinan duplikat; jika tidak, itu adalah orang baru.
PROCESS_STATE_FINISHED	Tidak ada data.humanToken, atau value kosong: tidak meyakinkan.	Anggap hasilnya tidak meyakinkan. Jangan pernah menyimpan atau mencocokkan value yang kosong; ulangi proses atau tolak, sesuai aturan bisnis Anda.
PROCESS_STATE_FAILED	Proses identifikasi gagal.	Ulangi proses atau tolak, sesuai aturan bisnis Anda.
PROCESS_STATE_CREATED	Proses dibuat.	Tunggu. Ambil hasilnya nanti dengan Dapatkan Proses.
PROCESS_STATE_CANCELED	Proses dibatalkan.	Buat proses baru, jika pengguna masih perlu diverifikasi.

peringatan

Selalu pastikan data.humanToken.value tidak kosong sebelum menggunakannya.

Kode Error

catatan

Status HTTP yang dikembalikan saat access key di header x-unico-accesskey tidak ada atau tidak valid masih dikonfirmasi. Lihat Autentikasi.

400 Bad Request

Kode	Pesan	Deskripsi
3	invalid flow	Ketika alur yang ditentukan tidak ada.
3	INVALID_IMAGE	Ketika gambar bukan base64 yang valid, atau tampak seperti upaya injeksi.
3	IMAGE_TOO_LARGE	Ketika gambar melebihi ukuran maksimum 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	Ketika format gambar bukan PNG, JPEG, atau WebP.
3	MISSING_IMAGE	Ketika gambar diperlukan untuk alur ini dan tidak dikirim.
3	INVALID_REQUEST	Ketika body permintaan bernilai null atau tidak dapat diinterpretasikan.
9	monthly process limit of <monthly_limit> reached for this tenant	Ketika batas penggunaan bulanan telah tercapai.
9	PROCESS_FAILED	Ketika proses mencapai kegagalan terminal saat sedang dibuat.

403 Forbidden

Kode	Pesan	Deskripsi
7	PERMISSION_DENIED	Ketika kredensial valid tetapi tidak berhak melakukan tindakan ini.

429 Too Many Requests

Batas rate tercapai. Ketika sistem Anda menerima error HTTP 429, Anda harus mengimplementasikan mekanisme untuk mencegah kegagalan berantai dan menghindari memperburuk pembatasan.

Praktik terbaik:

• Periode pendinginan (backoff): Segera hentikan atau kurangi permintaan berikutnya dari sistem Anda. Jangan terus-menerus mencoba ulang permintaan yang gagal dalam loop yang ketat.
• Antrean & pembatasan (Queueing & throttling): Buffer atau antrean permintaan keluar dari sisi Anda untuk mengontrol aliran lalu lintas sebelum mengirimnya kembali.
• Exponential backoff dengan jitter: Saat mencoba ulang, tingkatkan waktu tunggu secara eksponensial antar percobaan (misalnya, 1 s, 2 s, 4 s, 8 s) dan tambahkan penundaan acak kecil ("jitter") untuk mencegah efek kawanan di mana semua permintaan yang diantrean mencoba ulang pada milidetik yang sama persis.

peringatan

Terus-menerus mengirim permintaan ke endpoint yang dibatasi rate tanpa menerapkan backoff dapat memperpanjang periode pembatasan dan sangat memengaruhi throughput operasional sistem Anda. Membatasi permintaan dengan benar dari sisi Anda memastikan integrasi yang lebih lancar dan lebih tangguh.

Untuk batas default, peningkatan permintaan, dan detail tambahan, lihat Batas Rate.

500 Internal Server Error

Kode	Pesan	Deskripsi
13	Internal failure! Try again later	Ketika terjadi kesalahan internal.

Untuk daftar lengkap kode endpoint ini, lihat referensi Buat Proses Human API.

Selanjutnya

• Simpan nilai humanToken bersama catatan pengguna Anda untuk mengenali orang yang sama pada panggilan Human Token berikutnya.
• Untuk mengambil proses kembali, untuk audit atau dukungan, gunakan Dapatkan Proses.