Buat Proses

Ini adalah titik masuk setiap integrasi Web & SDK. Back-end Anda memanggilnya untuk membuat proses; front-end Anda menggunakan token yang dikembalikan untuk merender iFrame, mengarahkan pengguna, atau menginisialisasi SDK native.

Untuk alur integrasi lengkap, lihat Ringkasan Web & SDK.

Endpoint

Lingkungan	URL
Production	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

Permintaan

Headers

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

Parameter body

Field	Tipe	Wajib	Deskripsi
callbackUri	string	ya	URL tempat pengguna diarahkan setelah journey selesai. Gunakan / untuk alur SDK native di mana callback ditangani di dalam aplikasi.
flow	string	ya	Identifier flow — menentukan kapabilitas mana yang dijalankan. Contoh: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Lihat Alur yang tersedia.
purpose	string	ya	Tujuan bisnis. Nilai yang diterima: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	ya	Tipe dokumen. Nilai yang diterima: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_CO_NIT, DUI_TYPE_PE_RUC, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_AT_STNR, DUI_TYPE_FI_HETU.
person.duiValue	string	ya	Nomor dokumen, tanpa format.
person.friendlyName	string	tidak	Nama tampilan pengguna yang ditampilkan di UI journey. Maksimum 50 karakter.
person.phone	string	tidak	Nomor telepon dalam format DDI + DDD + nomor, tanpa pemisah. Diperlukan saat mengirim notifikasi melalui SMS atau WhatsApp.
person.email	string	tidak	Alamat email. Diperlukan untuk flow dengan Tanda Tangan Elektronik.
person.notifications	array	tidak	Saluran notifikasi untuk mengirim link journey. Setiap item memiliki notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, atau NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	kondisional	Tidak digunakan lagi. Gunakan references sebagai gantinya. ID proses biometrik referensi. Diperlukan untuk alur Validasi 1:1 (idtoken, idtokentrust, idtokensign) dan Revalidasi Cerdas (idsmart).
references	array	kondisional	Input referensi untuk alur Validasi 1:1 dan Revalidasi Cerdas, menggantikan bioTokenId. Setiap item berisi referenceType (REFERENCE_TYPE_IMAGE_BASE64 atau REFERENCE_TYPE_PROCESS_ID) dan referenceContent (gambar yang di-encode base64 atau UUID proses).
useCase	string	kondisional	Use case Revalidasi Cerdas. Diperlukan untuk idsmart. Contoh: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	tidak	Identifier internal Anda untuk proses ini (foreign key untuk referensi silang di portal).
companyBranchId	string (UUID)	tidak	ID cabang. Diperlukan hanya jika service account memiliki lebih dari satu cabang yang terkait.
expiresIn	string	tidak	Jendela validitas proses sejak pembuatan. Format: "3600s". Default-nya 7 hari jika dihilangkan.
flow_config	object	tidak	Override konfigurasi per flow.
flow_config.biometry_capture.enabled_back_camera	boolean	tidak	Gunakan kamera belakang perangkat. Tidak kompatibel dengan alur pengambilan dokumen atau Tanda Tangan Elektronik.
contextualization	object	tidak	Konteks transaksi yang ditampilkan kepada pengguna selama journey untuk menjelaskan pengambilan.
contextualization.company_name	string	tidak	Nama perusahaan yang ditampilkan selama journey. Maksimum 20 karakter.
contextualization.currency	string	tidak	Kode mata uang yang ditampilkan kepada pengguna. Nilai yang diterima: BRL, MXN, USD.
contextualization.price	number	tidak	Jumlah transaksi yang ditampilkan kepada pengguna.
contextualization.locale	object	tidak	Teks yang dilokalisasi ditampilkan selama journey. Kunci: ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	tidak	Alasan singkat untuk pengambilan, ditampilkan selama journey. Maksimum 50 karakter.
contextualization.locale.{ptBr|enUs|esMx}.title	string	tidak	Judul pemberitahuan pelanggan yang ditampilkan selama journey. Maksimum 100 karakter. Harus disediakan bersama dengan text. Tag HTML dihapus.
contextualization.locale.{ptBr|enUs|esMx}.text	string	tidak	Isi pemberitahuan pelanggan yang ditampilkan selama journey. Maksimum 210 karakter. Harus disediakan bersama dengan title. Tag HTML dihapus.

Contoh

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Respons

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

Field	Tipe	Deskripsi
process.id	string (UUID)	Identifier proses. Gunakan untuk mengambil hasil melalui Dapatkan Proses.
process.state	enum	PROCESS_STATE_CREATED — proses dibuat, journey belum dimulai. PROCESS_STATE_FAILED — pembuatan proses gagal.
process.flow	string	Identifier flow yang dikirim saat pembuatan.
process.purpose	string	Tujuan bisnis yang dikirim saat pembuatan.
process.callbackUri	string	URI callback yang dikirim saat pembuatan.
process.clientReference	string	Identifier internal Anda yang dikirim saat pembuatan. Hanya muncul jika diberikan dalam permintaan.
process.companyBranchId	string (UUID)	ID cabang. Hanya muncul jika diberikan dalam permintaan.
process.userRedirectUrl	string	URL untuk mengarahkan pengguna (integrasi Web Redirect dan iFrame). Jangan modifikasi URL ini.
process.token	string	JWT untuk menginisialisasi iFrame Web SDK.
process.webAppToken	string	JWT untuk menginisialisasi SDK native (Android, iOS, Flutter).
process.createdAt	string (date-time)	Timestamp ketika proses dibuat.
process.expiresAt	string (date-time)	Timestamp setelah proses kedaluwarsa dan tidak dapat lagi diselesaikan.
process.capacities	array	Kapabilitas yang dikonfigurasi untuk proses ini.
process.authenticationInfo	object	Informasi autentikasi untuk proses (kosong saat pembuatan).
process.person	object	Echo dari objek person yang dikirim saat pembuatan.
process.companyData.branchId	string (UUID)	ID cabang yang terkait dengan proses.
process.companyData.countryCode	string	Kode negara yang terkait dengan cabang (misalnya, BR, MX).

400 Bad Request

Dikembalikan ketika payload permintaan salah format, field wajib tidak ada, atau nilai flow tidak diketahui.

401 Unauthorized

Bearer token tidak ada, kedaluwarsa, atau tidak valid. Lihat Autentikasi.

429 Too Many Requests

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

Praktik terbaik:

• Periode pendinginan (backoff): Segera hentikan atau batasi permintaan berikutnya dari sistem Anda. Jangan terus-menerus mencoba ulang permintaan yang gagal dalam loop ketat.
• Antrian & pembatasan: Buffer atau antrikan permintaan keluar di 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 detik, 2 detik, 4 detik, 8 detik) dan tambahkan penundaan acak kecil ("jitter") untuk mencegah efek kawanan di mana semua permintaan yang diantrikan mencoba ulang pada milidetik yang sama persis.

peringatan

Terus-menerus menghubungi endpoint yang dibatasi rate tanpa melakukan backoff dapat memperpanjang periode pembatasan dan sangat memengaruhi throughput operasional sistem Anda. Pembatasan permintaan yang tepat di sisi Anda memastikan integrasi yang lebih lancar dan lebih tangguh.

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

Kode Error

400 Bad Request

Code	Message	Deskripsi
3	invalid flow	Ketika flow yang ditentukan tidak ada.
3	invalid person: friendly name exceeds 50 characters.	Ketika friendly name melebihi 50 karakter.
3	invalid purpose	Ketika purpose yang diberikan tidak valid.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Ketika callbackUri yang diberikan tidak valid.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Ketika email yang diberikan tidak valid dan notifikasi email dikonfigurasi.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	Ketika nomor telepon yang diberikan tidak valid dan notifikasi SMS atau WhatsApp dikonfigurasi.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Ketika identifier yang diberikan (duiValue) tidak valid.
3	invalid expiresIn argument	Ketika nilai expiresIn tidak valid.
3	invalid company_name argument in process contextualization, max length is 20	Ketika contextualization.company_name melebihi 20 karakter.
3	title and text must be provided together in process contexts	Ketika hanya salah satu dari title atau text yang disediakan dalam sebuah locale.
3	invalid title argument in process contexts, max length is 100	Ketika title dalam sebuah locale melebihi 100 karakter.
3	invalid text argument in process contexts, max length is 210	Ketika text dalam sebuah locale melebihi 210 karakter.
3	invalid reason argument in process contexts, max length is 50	Ketika reason dalam sebuah locale melebihi 50 karakter.
9	XX ID Apikeys are not set	Ketika API Key tidak dikonfigurasi dengan benar.

401 Unauthorized

Message	Deskripsi
Jwt header is an invalid JSON	Ketika access token yang digunakan mengandung karakter yang salah.
Jwt is expired	Ketika access token yang digunakan telah kedaluwarsa.

429 Too Many Requests

Tidak ada kode error detail yang disediakan untuk status ini — hanya status HTTP. Lihat bagian 429 Too Many Requests di atas untuk praktik terbaik.

500 Internal Server Error

Code	Message	Deskripsi
99999	Internal failure! Try again later	Ketika terjadi error internal.

Selanjutnya

• Setelah pengguna menyelesaikan journey, panggil Dapatkan Proses untuk mengambil hasilnya, atau tunggu webhook.