Buat Proses Dokumen

Endpoint ini menangani dua alur dokumen yang berbagi path yang sama tetapi berbeda dalam parameter body:

• Pengambilan baru — mengirimkan gambar dokumen dalam base64 untuk diproses (field document.files diperlukan).
• Penggunaan ulang — melewati pengambilan gambar dengan merujuk dokumen yang sebelumnya diambil (field document.documentId diperlukan).

Alur yang aktif ditentukan oleh apakah document.documentId diberikan dalam body permintaan.

Sebelum membuat proses dokumen, gunakan Dapatkan Dokumen yang Dapat Digunakan Ulang untuk memeriksa apakah pengguna sudah memiliki dokumen yang tersedia untuk digunakan ulang.

Untuk alur integrasi lengkap, lihat Ikhtisar API.

Endpoint

Lingkungan	URL
Produksi	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Permintaan

Headers

Header	Nilai
Authorization	Bearer <access_token> (lihat Autentikasi)
APIKEY	Kunci API yang telah ditetapkan dengan Document Capture and Reuse diaktifkan.
Content-Type	application/json

Parameter body

Pengambilan baru

Field	Tipe	Wajib	Deskripsi
subject.duiType	integer	ya	Pengidentifikasi tipe dokumen. Lihat nilai duiType di bawah.
subject.code	string	ya	Nilai pengidentifikasi pengguna sesuai yang didefinisikan oleh subject.duiType. Tanpa titik atau tanda hubung.
subject.name	string	tidak	Nama lengkap.
subject.gender	string	tidak	M atau F.
subject.birthDate	string (ISO 8601)	tidak	Tanggal lahir (YYYY-MM-DD).
subject.email	string	tidak	Alamat email.
subject.phone	string	tidak	Nomor telepon E.164.
document.purpose	string	ya	Tujuan bisnis. Nilai: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	ya	ID proses biometrik yang terhubung ke pengambilan dokumen ini.
document.files	array	ya	Gambar dokumen dalam base64 (depan dan/atau belakang).
document.files[].data	string	ya	Gambar dokumen dalam base64 (PNG, JPEG, atau WebP, maks 800 KB).
subsidiaryId	string	tidak	ID cabang — hanya diperlukan jika terdapat beberapa cabang.

Penggunaan ulang

Field	Tipe	Wajib	Deskripsi
subject.duiType	integer	ya	Pengidentifikasi tipe dokumen. Lihat nilai duiType di bawah.
subject.code	string	ya	Nilai pengidentifikasi pengguna sesuai yang didefinisikan oleh subject.duiType. Tanpa titik atau tanda hubung.
subject.name	string	tidak	Nama lengkap.
subject.gender	string	tidak	M atau F.
subject.birthDate	string (ISO 8601)	tidak	Tanggal lahir (YYYY-MM-DD).
subject.email	string	tidak	Alamat email.
subject.phone	string	tidak	Nomor telepon E.164.
document.purpose	string	ya	Tujuan bisnis. Nilai: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	ya	ID proses biometrik yang terhubung ke dokumen ini.
document.documentId	string	ya	ID dokumen yang sebelumnya diambil (diperoleh dari Dapatkan Dokumen yang Dapat Digunakan Ulang). Ketika diberikan, document.files dapat dihilangkan.
subsidiaryId	string	tidak	ID cabang — hanya diperlukan jika terdapat beberapa cabang.

Nilai duiType

Negara	Kode	Deskripsi
BR	1	CPF Brasil
MX	2	CURP Meksiko
US	4	SSN Amerika Serikat
BR	5	Paspor Brasil
AR	6	Paspor Argentina
AR	7	DNI Argentina
NG	8	NIN Nigeria
CL	9	RUN Chili
EC	10	NI Ekuador
US	11	Paspor Amerika Serikat
GT	12	CUI Guatemala
UY	13	CI Uruguay
BR	14	CNPJ Brasil
ZZ	15	Alamat email
ID	16	NIK Indonesia
ZZ	17	Nomor telepon
US	18	SIM Amerika Serikat
NG	20	Nomor Verifikasi Bank Nigeria (BVN)
US	21	Kartu Paspor Amerika Serikat
US	22	Paspor Polikarbonat Amerika Serikat
US	23	Kartu Identitas Amerika Serikat
TR	24	Nomor Identifikasi Turki (TCKN)
MX	25	RFC Meksiko (Perorangan)
CO	26	NIT Kolombia
PE	27	RUC Peru
CA	28	SIN Kanada
DK	29	CPR Denmark
GB	30	Nomor Asuransi Nasional Inggris (NINO)
PL	31	PESEL Polandia
SE	32	Nomor Pribadi Swedia (PNR)
CH	33	Nomor AHV/AVS Swiss
AT	34	Nomor Pajak Austria (STNR)
FI	35	Kode Identitas Pribadi Finlandia (HETU)
BE	36	Nomor Nasional Belgia (NN)
IT	37	Codice Fiscale Italia (CF)
SE	38	Nomor Koordinasi Swedia (Samordningsnummer)
NO	39	Nomor Identitas Nasional Norwegia (Fødselsnummer)
PE	40	DNI Peru
DE	41	Nomor Identifikasi Pajak Jerman (IdNr)
NL	42	Nomor Layanan Warga Negara Belanda (BSN)
NG	43	Token BVN Nigeria (hash)
NG	44	Token NIN Nigeria (hash)
PT	45	Nomor Identifikasi Pajak Portugal (NIF)
FR	46	Nomor Referensi Pajak Prancis (SPI)
IE	47	Nomor Layanan Publik Pribadi Irlandia (PPSN)
LU	48	Nomor Identifikasi Nasional Luksemburg (Matricule)
AR	49	SIM Argentina (Licencia Nacional de Conducir)
ES	50	Nomor Identitas Warga Asing Spanyol (NIE)
ES	51	Dokumen Identitas Nasional Spanyol (DNI)
CL	52	Paspor Chili
CO	53	Paspor Kolombia
PE	54	Paspor Peru
CO	55	SIM Kolombia (Licencia de Conducción)
CO	56	Kartu Kewarganegaraan Kolombia (Cédula de Ciudadanía)
CL	57	SIM Chili (Licencia de Conducir)
MX	58	SIM Meksiko (Licencia de Conducir)
—	0	Tidak ditentukan
—	3	Pengidentifikasi internal Unico

Contoh

Pengambilan baru — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

Pengambilan baru — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

Penggunaan ulang — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

Penggunaan ulang — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

Respons

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

Field	Tipe	Deskripsi
id	string (UUID)	Pengidentifikasi proses.
status	integer	3 (selesai dengan sukses), 5 (selesai dengan kegagalan).
document.id	string	Pengidentifikasi dokumen yang diambil. Gunakan nilai ini dalam permintaan document.documentId di masa mendatang untuk penggunaan ulang.
document.type	string	Tipe dokumen yang diidentifikasi, berupa nama dictionary yang sepenuhnya terkualifikasi. Lihat nilai document.type di bawah.
document.cpfMatch	boolean	true jika pengidentifikasi yang diekstrak dari dokumen cocok dengan subject.code.
document.faceMatch	boolean	true jika wajah pada dokumen cocok dengan foto selfie biometrik dari document.authProcessId.
document.content	object	Field yang diekstrak melalui OCR. Struktur bervariasi berdasarkan tipe dokumen — klik di sini untuk detail field.
document.fileUrls	array	URL sementara (validitas 10 menit) untuk mengunduh gambar dokumen.

Hanya field yang berhasil diekstrak yang ada di document.content; apa pun yang tidak dapat dibaca oleh OCR dihilangkan alih-alih dikembalikan dalam keadaan kosong.

Nilai document.type

Skema terpadu

Semua tipe dokumen yang menggunakan skema terpadu — unified_schema pada referensi field — dilaporkan dalam document.type sebagai unico.moja.dictionary.<country>.generic.v1.<DocumentType>, di mana <country> adalah kode ISO 3166-1 alpha-2 dalam huruf kecil dan <DocumentType> adalah tipe yang diidentifikasi. Misalnya:

• unico.moja.dictionary.ar.generic.v1.IdCard: Kartu identitas Argentina
• unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: Paspor polikarbonat Amerika Serikat

Skema spesifik

Tipe dokumen yang menggunakan skema field-nya sendiri — terdaftar di bawah specific_document_schemas pada referensi field — ditampilkan pada tabel di bawah ini:

Negara	Nilai	Dokumen
BR	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	unico.moja.dictionary.br.cnh.v2.Cnh	CNH (SIM)
BR	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	unico.moja.dictionary.br.passaporte.v1.Passaporte	Paspor
MX	unico.moja.dictionary.mx.ine.v1.Ine	Kredensial pemilih INE
MX	unico.moja.dictionary.mx.lpc.v1.Lpc	Licencia para conducir (SIM)
MX	unico.moja.dictionary.mx.pasaporte.v1.Pasaporte	Paspor
—	unico.moja.dictionary.other.unknown.v1.Unknown	Tipe tidak dapat diidentifikasi — document.content kosong

Tidak ada ekstraksi OCR yang dilakukan dan tidak ada field yang dilaporkan ketika document.type adalah unico.moja.dictionary.other.unknown.v1.Unknown.

Kode Error

400 Bad Request

Kode	Pesan	Deskripsi
99989	The document is invalid.	Objek document memiliki struktur tidak valid.
99988	The document is empty.	Objek document tidak ada dalam body permintaan.
20900	O base64 informado não é válido.	Parameter base64 tidak valid. Kemungkinan penyebab: bukan gambar atau merupakan percobaan injeksi.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Resolusi gambar yang diunggah terlalu rendah.
20509	The subject.name field is invalid.	subject.name mengandung karakter tidak valid.
20508	The subject.gender field is invalid.	subject.gender harus M atau F.
20507	O parâmetro subject.code é inválido.	Nilai pengidentifikasi tidak standar atau tidak ada.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Ukuran gambar melebihi 800 KB; kompres ke JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Format base64 tidak valid atau tidak didukung.
20068	The document.documentId or document.files parameter must be present.	document.documentId maupun document.files tidak disediakan.
20067	The document.purpose parameter is invalid.	Nilai tidak dikenal di document.purpose.
20066	The document.authProcessId parameter is invalid.	Nilai tidak valid di document.authProcessId.
20062	The useCase field is invalid.	Nilai tidak dikenal di field useCase.
20021	The subject.phone field is invalid.	Format subject.phone tidak valid (IDD + kode area + nomor, 13 karakter).
20019	The subject.birthDate field is invalid.	subject.birthDate berada di luar format ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Parameter gambar dokumen tidak ada.
20008	The subject.email field is invalid.	Format email tidak valid di subject.email.
20005	O parâmetro subject.code não foi informado.	Parameter subject.code tidak ada.
20004	O parâmetro subject não foi informado.	Parameter subject tidak ada.
20003	The request body is missing or invalid.	Payload null atau tidak valid.
20002	O parâmetro APIKey não foi informado.	Parameter APIKEY tidak ada dari header permintaan.
20001	O parâmetro authtoken não foi informado.	Parameter token integrasi tidak ada dari header permintaan.
10508	The JWT with the captured face has already been used.	JWT hanya dapat digunakan sekali.
10507	The JWT with the captured face is expired.	JWT kedaluwarsa; harus dikirim dalam 10 menit.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 bukan JWT valid yang dihasilkan oleh SDK.

403 Forbidden

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

Kode	Pesan	Deskripsi
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 telah kedaluwarsa.
10501	O token informado é inválido.	Token autentikasi tidak valid.
10201	O AppKey informado é inválido.	APIKEY tidak valid atau tidak ada.

409 Conflict

Kode	Pesan	Deskripsi
20073	The processID already exists.	processId yang diberikan sudah ada untuk tenant ini.

500 Internal Server Error

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

Langkah selanjutnya

• Untuk memeriksa apakah dokumen sudah tersedia sebelum panggilan ini, lihat Dapatkan Dokumen yang Dapat Digunakan Ulang.
• Untuk pembuatan proses biometrik (diperlukan untuk document.authProcessId), lihat Buat Proses.