Buat Proses

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

Untuk alur integrasi lengkap, lihat Ikhtisar Web & SDK.

Endpoint

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

Permintaan

Header

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

Parameter body

Field	Tipe	Wajib	Deskripsi
callbackUri	string	ya	URL ke mana pengguna diarahkan setelah perjalanan selesai. Gunakan / untuk alur SDK native di mana callback ditangani dalam aplikasi.
flow	string	ya	Pengenal alur — menentukan kapabilitas 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.
person.duiValue	string	ya	Nomor dokumen, tanpa format.
person.friendlyName	string	tidak	Nama tampilan pengguna yang ditampilkan di UI perjalanan. 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 alur dengan Tanda Tangan Elektronik.
person.notifications	array	tidak	Saluran notifikasi untuk mengirim tautan perjalanan. Setiap item memiliki notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, atau NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	kondisional	Tidak lagi disarankan. 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 validasi 1:1 dan alur Revalidasi Cerdas, menggantikan bioTokenId. Setiap item berisi referenceType (REFERENCE_TYPE_IMAGE_BASE64 atau REFERENCE_TYPE_PROCESS_ID) dan referenceContent (gambar berformat base64 atau UUID proses).
useCase	string	kondisional	Kasus penggunaan 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 (kunci asing untuk referensi silang di portal).
companyBranchId	string (UUID)	tidak	ID cabang. Hanya diperlukan jika akun layanan memiliki lebih dari satu cabang yang terkait.
expiresIn	string	tidak	Jendela validitas proses sejak pembuatan. Format: "3600s". Default 7 hari jika tidak diisi.
flow_config	object	tidak	Override konfigurasi per alur.
flow_config.biometry_capture.enabled_back_camera	boolean	tidak	Gunakan kamera belakang perangkat. Tidak kompatibel dengan pengambilan dokumen atau alur Tanda Tangan Elektronik.
contextualization	object	tidak	Konteks transaksi yang ditampilkan kepada pengguna selama perjalanan untuk menjelaskan pengambilan.
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 alasan yang dilokalisasi. Kunci: ptBr, enUs, esMx — masing-masing dengan string reason yang ditampilkan selama perjalanan.

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 Get Process.
process.state	enum	PROCESS_STATE_CREATED — proses dibuat, perjalanan belum dimulai. PROCESS_STATE_FAILED — pembuatan proses gagal.
process.flow	string	Identifier alur yang dikirim saat pembuatan.
process.purpose	string	Tujuan bisnis yang dikirim saat pembuatan.
process.callbackUri	string	Callback URI yang dikirim saat pembuatan.
process.clientReference	string	Identifier internal Anda yang dikirim saat pembuatan. Hanya ada jika disertakan dalam permintaan.
process.companyBranchId	string (UUID)	ID cabang. Hanya ada jika disertakan dalam permintaan.
process.userRedirectUrl	string	URL untuk mengalihkan pengguna (integrasi Web Redirect dan iFrame). Jangan ubah URL ini.
process.token	string	JWT untuk menginisialisasi Web SDK iFrame.
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 pada 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 (contoh: BR, MX).

400 Bad Request

Dikembalikan saat payload permintaan salah format, field yang diperlukan tidak ada, atau nilai flow tidak dikenal.

401 Unauthorized

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

429 Too Many Requests

Batas rate tercapai. Coba lagi setelah interval yang ditunjukkan dalam header respons.

Kode Error

400 Bad Request

Kode	Pesan	Deskripsi
3	invalid flow	Ketika alur yang ditentukan tidak ada.
3	invalid person: friendly name exceeds 50 characters.	Ketika nama tampilan melebihi 50 karakter.
3	invalid purpose	Ketika tujuan 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.
9	XX ID Apikeys are not set	Ketika API Key tidak dikonfigurasi dengan benar.

401 Unauthorized

Pesan	Deskripsi
Jwt header is an invalid JSON	Ketika token akses yang digunakan mengandung karakter yang tidak benar.
Jwt is expired	Ketika token akses yang digunakan telah kedaluwarsa.

429 Too Many Requests

Tidak ada kode error terperinci yang disediakan untuk status ini — hanya status HTTP.

500 Internal Server Error

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

Langkah selanjutnya

• Setelah pengguna menyelesaikan perjalanan, panggil Get Process untuk mengambil hasil, atau tunggu webhook.