Set Process Document

Mengatur dokumen identifikasi (CPF, CURP, SSN, atau duiType lainnya) pada proses yang dibuat tanpa dokumen. Setelah diatur, dokumen tidak dapat diubah.

Hanya tersedia untuk proses yang Custom Flow-nya mengizinkan pembuatan tanpa dokumen — yaitu, proses dalam status AWAITING_FOR_DOCUMENT.

Endpoint

Lingkungan	URL
Production	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

Parameter path

Field	Tipe	Wajib	Deskripsi
processId	string	ya	Process ID yang dikembalikan di process.id saat pembuatan.

Parameter body

Field	Tipe	Wajib	Deskripsi
duiType	enum	ya	Tipe dokumen. Nilai: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Endpoint ini mendukung subset tipe dokumen yang diterima oleh Buat Proses — Custom Flow yang mengizinkan pembuatan dokumen opsional saat ini divalidasi terhadap daftar yang lebih sempit ini.
duiValue	string	ya	Nomor dokumen, tanpa format. Maksimum 320 karakter (mengakomodasi identifier yang di-encode atau komposit; nomor dokumen standar seperti CPF atau CURP jauh lebih pendek).

Contoh

cURL

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

Node.js

import fetch from 'node-fetch';

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

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

Respons

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

Field	Tipe	Deskripsi
process.id	string	Identifier proses.
process.person.duiType	string	Tipe dokumen yang diatur pada proses.
process.person.duiValue	string	Nilai dokumen yang diatur pada proses.

400 Bad Request

Dikembalikan ketika payload permintaan salah format, field wajib tidak ada, atau status proses tidak mengizinkan operasi tersebut.

401 Unauthorized

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

404 Not Found

Proses tidak ditemukan.

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	process id is invalid	Ketika process id tidak valid.
3	dui_type is required	Ketika tipe dokumen tidak diberikan.
3	dui_value is required	Ketika nomor dokumen tidak diberikan.
3	dui_value exceeds maximum length	Ketika nomor dokumen melebihi batas karakter maksimum.
9	process is not awaiting for document	Ketika proses yang ditentukan tidak menerima pengiriman dokumen.
9	process expired	Ketika proses yang ditentukan telah kedaluwarsa.
9	document already set, cannot be modified	Ketika proses sudah memiliki dokumen yang terhubung.
9	process already finished	Ketika proses sudah selesai.
9	flow does not allow optional document	Ketika dokumen wajib untuk flow yang dijalankan oleh proses.

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.

404 Not Found

Code	Message	Deskripsi
5	error getting process: rpc error: code = NotFound desc = process not found	Ketika process ID tidak ditemukan.

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 mengatur dokumen, proses melanjutkan pipeline-nya. Panggil Dapatkan Proses untuk mengambil hasilnya, atau tunggu webhook.