Tetapkan Dokumen ProsesPOST

Buat proses tanpa dokumen, biarkan pengguna menyelesaikan pengambilan gambar, lalu kirim dokumen dari back-end Anda. Setelah itu, proses selesai.

MarkdownChatGPTClaude

Siklus hidup

1. Back-end Anda membuat proses dengan Buat Proses, tanpa person.duiType dan person.duiValue. Flow harus mengizinkan dokumen opsional. Proses dimulai dengan state PROCESS_STATE_CREATED.
2. Pengguna menjalankan perjalanan dan melakukan pengambilan gambar.
3. Unico API memindahkan proses ke AWAITING_FOR_DOCUMENT, yaitu state yang dikembalikan oleh Dapatkan Proses selama proses menunggu dokumen. Anda sudah dapat membaca hasil parsial dari kapabilitas yang tidak bergantung pada duiValue.
4. Back-end Anda memanggil endpoint ini dengan ID proses di URL dan dokumen di body. Unico API kemudian menyelesaikan proses, dan proses berpindah ke PROCESS_STATE_FINISHED.

Respons tidak memuat hasil akhir

Baca state akhir dan hasilnya dengan Dapatkan Proses, atau tunggu webhook.

Endpoint

Lingkungan	URL
Produksi	POST https://api.idcloud.unico.app/client/v1/process/{processId}/document
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document

Permintaan

Headers

Header	Nilai
Authorization	Bearer <access_token> (lihat Autentikasi)
Content-Type	application/json

Kredensial memerlukan izin yang sama dengan yang digunakan untuk memanggil Buat Proses.

Parameter path

Parameter	Tipe	Wajib	Deskripsi
processId	string (UUID)	ya	Identifier proses yang dikembalikan oleh Buat Proses.

Parameter body

Field	Tipe	Wajib	Deskripsi
duiType	enum	ya	Tipe dokumen. DUI_TYPE_UNSPECIFIED ditolak. Lihat nilai duiType di bawah.
duiValue	string	ya	Nomor dokumen, tanpa format. Maksimal 320 karakter.

Nilai duiType

Negara	Nilai	Deskripsi
AR	DUI_TYPE_AR_PASSPORT	Paspor Argentina
AR	DUI_TYPE_AR_DNI	DNI Argentina
AR	DUI_TYPE_AR_LNC	SIM Argentina (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	Nomor Pajak Austria (STNR)
BE	DUI_TYPE_BE_NN	Nomor Nasional Belgia (NN)
BR	DUI_TYPE_BR_CPF	CPF Brasil
BR	DUI_TYPE_BR_PASSPORT	Paspor Brasil
BR	DUI_TYPE_BR_CNPJ	CNPJ Brasil
CA	DUI_TYPE_CA_SIN	SIN Kanada
CH	DUI_TYPE_CH_AHV	Nomor AHV/AVS Swiss
CL	DUI_TYPE_CL_RUN	RUN Chili
CL	DUI_TYPE_CL_PASSPORT	Paspor Chili
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	SIM Chili (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	NIT Kolombia
CO	DUI_TYPE_CO_PASSPORT	Paspor Kolombia
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	SIM Kolombia (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	Kartu Kewarganegaraan Kolombia (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	Nomor Identifikasi Pajak Jerman (IdNr)
DK	DUI_TYPE_DK_CPR	CPR Denmark
EC	DUI_TYPE_EC_NI	NI Ekuador
ES	DUI_TYPE_ES_NIE	Nomor Identitas Warga Asing Spanyol (NIE)
ES	DUI_TYPE_ES_DNI	Dokumen Identitas Nasional Spanyol (DNI)
FI	DUI_TYPE_FI_HETU	Kode Identitas Pribadi Finlandia (HETU)
FR	DUI_TYPE_FR_SPI	Nomor Referensi Pajak Prancis (SPI)
GB	DUI_TYPE_GB_NINO	Nomor Asuransi Nasional Inggris (NINO)
GT	DUI_TYPE_GT_CUI	CUI Guatemala
ID	DUI_TYPE_ID_NIK	NIK Indonesia
IE	DUI_TYPE_IE_PPSN	Nomor Layanan Publik Pribadi Irlandia (PPSN)
IT	DUI_TYPE_IT_CF	Codice Fiscale Italia (CF)
LK	DUI_TYPE_LK_NIC	NIC Sri Lanka
LU	DUI_TYPE_LU_MATRICULE	Nomor Identifikasi Nasional Luksemburg (Matricule)
MX	DUI_TYPE_MX_CURP	CURP Meksiko
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	RFC Meksiko (Perorangan)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	SIM Meksiko (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	NIN Nigeria
NG	DUI_TYPE_NG_BVN	Nomor Verifikasi Bank Nigeria (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	Token BVN Nigeria (hash)
NG	DUI_TYPE_NG_NIN_TOKEN	Token NIN Nigeria (hash)
NL	DUI_TYPE_NL_BSN	Nomor Layanan Warga Negara Belanda (BSN)
NO	DUI_TYPE_NO_FNR	Nomor Identitas Nasional Norwegia (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	RUC Peru
PE	DUI_TYPE_PE_DNI	DNI Peru
PE	DUI_TYPE_PE_PASSPORT	Paspor Peru
PL	DUI_TYPE_PL_PESEL	PESEL Polandia
PT	DUI_TYPE_PT_NIF	Nomor Identifikasi Pajak Portugal (NIF)
SE	DUI_TYPE_SE_PNR	Nomor Pribadi Swedia (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	Nomor Koordinasi Swedia (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	Nomor Identifikasi Turki (TCKN)
US	DUI_TYPE_US_SSN	SSN Amerika Serikat
US	DUI_TYPE_US_PASSPORT	Paspor Amerika Serikat
US	DUI_TYPE_US_DRIVER_LICENSE	SIM Amerika Serikat
US	DUI_TYPE_US_PASSPORT_CARD	Kartu Paspor Amerika Serikat
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	Paspor Polikarbonat Amerika Serikat
US	DUI_TYPE_US_ID_CARD	Kartu Identitas Amerika Serikat
UY	DUI_TYPE_UY_CI	CI Uruguay
ZZ	DUI_TYPE_ZZ_EMAIL	Alamat email
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	Nomor telepon

Kapan panggilan diterima

• Proses berada dalam state AWAITING_FOR_DOCUMENT: pengguna sudah menyelesaikan pengambilan gambar.
• Proses belum kedaluwarsa.
• Flow mengizinkan dokumen opsional.

Dokumen bersifat tidak dapat diubah. Panggilan kedua akan gagal, karena proses tidak lagi menunggu dokumen.

Contoh

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

Respons

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

Field	Tipe	Deskripsi
processId	string (UUID)	Identifier proses.
duiType	enum	Tipe dokumen yang terdaftar untuk proses.
duiValue	string	Nomor dokumen yang terdaftar untuk proses.

Nilai pada contoh hanyalah placeholder.

Kode Error

400 Bad Request

Kode	Deskripsi
3	processId tidak ada atau tidak valid, duiType tidak ditentukan, atau duiValue kosong atau lebih dari 320 karakter.
9	Proses tidak sedang menunggu dokumen (termasuk jika dokumen sudah ditetapkan), sudah kedaluwarsa atau selesai, atau flow tidak mengizinkan dokumen opsional.

401 Unauthorized

Kode	Pesan	Deskripsi
—	Jwt header is an invalid JSON	Ketika access token yang digunakan mengandung karakter yang salah.
—	Jwt is expired	Ketika access token yang digunakan sudah kedaluwarsa.

403 Forbidden

Kode	Deskripsi
7	Kredensial tidak memiliki izin yang diperlukan oleh Buat Proses.

404 Not Found

Kode	Deskripsi
5	Proses tidak ada, atau bukan milik perusahaan Anda.

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	Deskripsi
13	Dokumen tidak dapat disimpan.

catatan

Dokumen didaftarkan ke layanan identitas sebelum disimpan. Jika pendaftaran tersebut gagal, panggilan akan mengembalikan status dari kegagalan tersebut.

Selanjutnya

• Untuk membaca state akhir dan hasilnya, lihat Dapatkan Proses.
• Untuk mendapatkan notifikasi saat proses selesai, lihat Webhook dan Event.