Dapatkan Dokumen yang Dapat Digunakan Kembali

Gunakan endpoint ini untuk memeriksa apakah pengguna sudah memiliki dokumen yang tersedia untuk digunakan kembali sebelum memulai alur pengambilan Dokumen baru. Jika dokumen ditemukan, documentId-nya dapat langsung diteruskan ke POST /processes/v1 (tipe Dokumen) untuk melewati langkah pengambilan.

Endpoint

Lingkungan	URL
Production	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

Permintaan

Headers

Header	Nilai
Authorization	Bearer <access_token> (lihat Autentikasi)
APIKEY	API key yang telah disediakan dengan Pengambilan Dokumen dan Penggunaan Kembali diaktifkan.

Parameter query

Parameter	Tipe	Wajib	Deskripsi
code	string	ya	Identitas pengguna (CPF atau CURP, tanpa format).
type	string	ya	Tipe dokumen yang akan dicari. Nilai yang diterima: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

catatan

Nilai type di atas khusus untuk endpoint ini. Jangan salah mengartikannya dengan:

• subject.duiType pada permintaan POST — menggunakan prefiks DUI_TYPE_* dan mengidentifikasi orang, bukan tipe dokumen (misalnya, DUI_TYPE_BR_CPF).
• documentType pada respons — menggunakan jalur registri lengkap (misalnya, unico.moja.dictionary.br.cnh.v2.Cnh).

Contoh

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Respons

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Field	Tipe	Deskripsi
items	array	Daftar dokumen yang dapat digunakan kembali yang ditemukan untuk pengguna. Array kosong jika tidak ada dokumen yang dapat digunakan kembali ditemukan untuk code dan type yang diberikan.
items[].documentType	string	Identifier tipe dokumen. Nilai yang mungkin: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
items[].documentId	string	Identifier dokumen. Teruskan nilai ini di document.documentId pada POST /processes/v1 untuk menggunakan kembali dokumen tersebut.

403 Forbidden

Bearer token atau APIKEY tidak ada, kedaluwarsa, atau tidak valid.

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.

Menggunakan documentId untuk penggunaan kembali

Setelah Anda memiliki documentId, teruskan dalam permintaan proses Dokumen untuk melewati pengambilan:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Field	Deskripsi
document.purpose	Tujuan bisnis untuk proses dokumen ini. Nilai yang diterima: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. Nilai-nilai ini khusus untuk Document API dan berbeda dari enum purpose SDK biometrik.
document.authProcessId	ID proses biometrik yang sebelumnya dibuat untuk pengguna ini (dari POST /processes/v1).
document.documentId	ID dokumen yang diperoleh dari respons endpoint ini. Ketika diberikan, document.files dapat dihilangkan — platform secara otomatis mengambil dokumen yang sebelumnya ditangkap.

Untuk skema permintaan proses Dokumen lengkap, lihat Create Document Process.

Kode Error

400 Bad Request

Code	Message	Deskripsi
20507	O parâmetro subject.code é inválido.	Nilai identifier yang salah format atau tidak ada (CPF atau CURP).
20002	O parâmetro APIKey não foi informado.	Header APIKEY tidak ada.
20001	O parâmetro authtoken não foi informado.	Header token autentikasi tidak ada.

403 Forbidden

Code	Message	Deskripsi
30020	The provided authorization token does not have permission to perform this action.	Token tidak memiliki izin untuk mengakses selfie dokumen.
30017	User does not have permission to perform this action.	JWT yang salah format atau pengguna tanpa izin untuk melakukan operasi ini.
10502	O token informado está expirado.	Access-token kedaluwarsa.
10501	O token informado é inválido.	Token autentikasi tidak valid.
10201	O AppKey informado é inválido.	APIKEY tidak ada atau tidak ditemukan.

404 Not Found

Code	Message	Deskripsi
99987	Attachment not found.	Lampiran yang terkait dengan dokumen tidak ditemukan.
50001	The process is not found.	Tidak ada dokumen yang ditemukan untuk parameter yang diberikan.

500 Internal Server Error

Code	Message	Deskripsi
99999	Internal failure! Try again later.	Error pemrosesan di sisi server.