Buat Proses

Endpoint ini menangani dua use case yang berbagi path yang sama tetapi berbeda dalam parameter body, kapabilitas, dan field respons:

Integrasi — memvalidasi siapa pengguna tersebut dengan membandingkan wajah mereka dengan basis identitas Unico (subject.duiType + subject.code diperlukan).
Transaksional — memverifikasi bahwa ini adalah orang yang sama dari proses sebelumnya dengan membandingkan wajah-dengan-wajah (referenceProcessId ATAU array references dengan selfie / process id diperlukan).

Use case aktif ditentukan oleh APIKEY yang dikirim di header permintaan.

Untuk alur integrasi lengkap, lihat Ringkasan API.

Endpoint

Lingkungan	URL
Production	`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`	API key yang telah disediakan — menentukan use case aktif dan kapabilitas yang diaktifkan.
`Content-Type`	`application/json`

Parameter body

Integrasi
Transaksional

Field	Tipe	Wajib	Deskripsi
`subject.duiType`	integer	ya	Pengidentifikasi tipe dokumen. Lihat nilai `duiType` di bawah.
`subject.code`	string	ya	Nilai pengenal sebagaimana 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.
`useCase`	string	tidak	Konteks operasi, misalnya `Onboarding`.
`subsidiaryId`	string	tidak	ID cabang — diperlukan hanya jika terdapat beberapa cabang.
`imageBase64`	string	ya	Selfie yang ditangkap oleh front-end Anda, dalam base64.

Field	Tipe	Wajib	Deskripsi
`references`	array	kondisional	Input referensi untuk alur Validasi 1:1. Setiap item berisi `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` atau `REFERENCE_TYPE_PROCESS_ID`) dan `referenceContent` (gambar yang di-encode base64 atau UUID proses).
`referenceProcessId`	string	kondisional	Tidak digunakan lagi. Gunakan `references` sebagai gantinya. ID proses Integrasi referensi untuk dibandingkan. Jika referensi adalah proses by-Unico, gunakan `authenticationInfo.authenticationId`.
`imageBase64`	string	ya	Selfie yang ditangkap oleh front-end Anda, dalam base64.
`subject`	object	tidak	Wadah informasi pengguna.
`subject.duiType`	string	tidak	Jenis pengenal. Nilai yang mungkin: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	tidak	Nilai pengenal sebagaimana didefinisikan oleh `subject.duiType`. Tanpa titik atau tanda hubung.
`subject.name`	string	tidak	Nama lengkap pengguna.
`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.
`useCase`	string	tidak	Konteks operasi, misalnya `Transactional`.
`subsidiaryId`	string	tidak	ID cabang — diperlukan hanya jika ada beberapa cabang.

informasi

Untuk use case ini, tidak memungkinkan untuk melakukan orkestrasi dengan Skor Risiko. Hasil selalu dikembalikan secara sinkron dalam respons POST.

Nilai duiType

Negara	Kode	Deskripsi
BR	1	CPF Brasil
BR	5	Paspor Brasil
MX	2	CURP Meksiko
AR	6	Paspor Argentina
AR	7	DNI Argentina
US	4	SSN Amerika Serikat
US	11	Paspor Amerika Serikat
US	18	SIM Amerika Serikat
ID	16	NIK Indonesia
NG	8	NIN Nigeria
CL	9	RUN Chili
EC	10	NI Ekuador
GT	12	CUI Guatemala
UY	13	CI Uruguay
ZZ	15	Alamat email
ZZ	17	Nomor telepon
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)
AT	34	Nomor Pajak Austria (STNR)
FI	35	Kode Identitas Pribadi Finlandia (HETU)
—	0	Tidak ditentukan
—	3	Pengidentifikasi internal Unico

Persyaratan gambar

Resolusi minimum: 640 x 480 (standar HD)
Ukuran file maksimum: 800 KB (kompresi JPEG92 disarankan)
Format yang diterima: PNG, JPEG, WebP
Token JWT dari SDK kedaluwarsa setelah 10 menit dan hanya dapat digunakan sekali

Contoh

Integrasi — cURL
Integrasi — Node.js
Transaksional — cURL
Transaksional — Node.js

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",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respons

Integrasi
Transaksional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}

Field respons bergantung pada APIKey Anda

Contoh di atas menampilkan semua kemungkinan field kapabilitas. Respons aktual Anda hanya akan menyertakan field untuk kapabilitas yang diaktifkan dalam konfigurasi APIKey Anda — field untuk kapabilitas yang dinonaktifkan tidak disertakan sama sekali. Hubungi manajer proyek Unico Anda untuk mengaktifkan atau menyesuaikan kapabilitas.

Field	Tipe	Deskripsi
`id`	string (UUID)	Identifier proses. Gunakan dengan Dapatkan Proses untuk kueri ulang.
`status`	integer	`1` (memproses), `3` (selesai dengan sukses), `5` (error).
`unicoId.result`	string	`yes`, `no`, `inconclusive` — lihat Verifikasi Identitas.
`riskLevel.result`	string	`approved`, `reproved`, `risk-critical`, `risk-high`, `inconclusive` — lihat nilai yang mungkin di bawah atau Klasifikasi Risiko Penipuan.
`idFace.result`	string	`FOUND`, `NOT_FOUND` — lihat Pengidentifikasi Wajah.
`idFace.personId`	string	Pengidentifikasi opak stabil untuk wajah. Hanya ada ketika `idFace.result = FOUND`.
`identityFraudsters.result`	string	Tidak digunakan lagi. Gunakan `riskLevel` sebagai gantinya. Klien dengan integrasi yang sedang berjalan dapat terus menggunakannya sambil mengoordinasikan migrasi dengan tim proyek yang bertanggung jawab.
`government.serpro`	integer	Skor kemiripan Serpro (0–100, -1, -2). Tersedia di Brasil saja. Lihat Hasil Kemiripan Serpro.
`liveness`	integer	`1` (lulus), `2` (gagal) — lihat Deteksi Kehidupan.

riskLevel.result — nilai yang mungkin

Nilai	Makna
`approved`	Ini adalah wajah pemegang ID, dan tidak ditemukan bukti terkait penipuan.
`reproved`	Penolakan direkomendasikan, karena beberapa indikator penipuan terdeteksi.
`risk-critical`	Penolakan direkomendasikan, namun keputusan akhir ada pada kebijaksanaan Anda. Risiko kritis menunjukkan bahwa kami menemukan setidaknya 2 bukti kuat adanya penipuan.
`risk-high`	Penolakan juga direkomendasikan, namun keputusan tetap ada pada Anda. Risiko tinggi menunjukkan bahwa kami menemukan setidaknya satu bukti kuat adanya penipuan.
`inconclusive`	Tidak ditemukan bukti kuat adanya penipuan. Oleh karena itu, tidak dapat disimpulkan apakah terdapat risiko yang relevan atau tidak.

informasi

Ketika unicoId.result = inconclusive dan orkestrasi Skor Risiko aktif, proses mungkin mengembalikan status: 1 (memproses). Poll Dapatkan Proses atau gunakan webhook untuk mengambil hasil akhir.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

Field	Tipe	Deskripsi
`id`	string (UUID)	Identifier proses.
`status`	integer	`3` (selesai dengan sukses), `5` (error). Untuk semua nilai yang mungkin, lihat Dapatkan Proses.
`biometryToken.result`	boolean	`true` jika wajah yang dikirim cocok dengan proses referensi; `false` jika tidak.
`liveness`	integer	`1` (lulus), `2` (gagal) — lihat Deteksi Kehidupan.

400 Bad Request

Payload salah format, gambar tidak valid, atau field wajib tidak ada. Lihat Kode Error di bawah.

403 Forbidden

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

409 Conflict

processId yang diberikan sudah ada untuk tenant ini. Lihat Kode Error di bawah.

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
403 Forbidden
409 Conflict
500 Internal Server Error

Code	Message	Deskripsi
`20900`	O base64 informado não é válido.	Parameter base64 tidak valid. Kemungkinan penyebab: bukan gambar atau 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.
`20513`	The referenced process was not found.	`referenceProcessId` menunjuk ke proses yang tidak ada atau tidak lagi dapat diakses.
`20512`	The referenced process is not available for reuse.	Proses referensi ada tetapi tidak tersedia untuk digunakan kembali.
`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.	CPF 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.
`20065`	The referenceProcessId field is invalid.	`referenceProcessId` bukan UUID yang valid.
`20062`	The useCase field is invalid.	Nilai yang tidak dikenali di field `useCase`.
`20024`	The referenceProcessId field is missing.	Parameter `referenceProcessId` tidak diberikan dan `references` tidak dikirim sebagai alternatif.
`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` di luar format ISO 8601 (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	Parameter gambar selfie tidak ada.
`20008`	The subject.email field is invalid.	Format email tidak valid di `subject.email`.
`20006`	O parâmetro subject.name não foi informado.	Parameter subject.name tidak ada.
`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 di header permintaan.
`20001`	O parâmetro authtoken não foi informado.	Parameter token integrasi tidak ada di 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.

Code	Message	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.

Code	Message	Deskripsi
`20073`	The processID already exists.	`processId` yang diberikan sudah ada untuk tenant ini.

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

Selanjutnya

Untuk melihat kueri hasil proses Integrasi, lihat Dapatkan Proses.
Untuk operasi Dokumen dan Verifikasi Usia, lihat halaman masing-masing di bagian ini.

Endpoint​

Permintaan​

Contoh​

Respons​

Kode Error​

Selanjutnya​