Buat Proses

Endpoint ini menangani dua kasus penggunaan yang berbagi path yang sama tetapi berbeda dalam parameter body, kemampuan, dan field respons:

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

Kasus penggunaan aktif ditentukan oleh APIKEY yang dikirim di header permintaan.

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 disediakan — mendefinisikan kasus penggunaan aktif dan kemampuan yang diaktifkan.
`Content-Type`	`application/json`

Parameter body

Integrasi
Transaksional

Field	Tipe	Wajib	Deskripsi
`subject.code`	string	ya	CPF (BR) atau CURP (MX).
`subject.name`	string	ya	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, mis. `Onboarding`.
`imageBase64`	string	ya	Selfie yang diambil 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 berenkode base64 atau UUID proses).
`referenceProcessId`	string	kondisional	Tidak Digunakan Lagi. Gunakan `references` sebagai gantinya. ID proses Onboarding referensi untuk dibandingkan. Jika referensi adalah proses by-Unico, gunakan `authenticationInfo.authenticationId`.
`imageBase64`	string	ya	Selfie yang diambil oleh front-end Anda, dalam base64.
`subject`	object	tidak	Kontainer informasi pengguna.
`subject.code`	string	tidak	CPF (BR) atau CURP (MX).
`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, mis. `Transactional`.
`subsidiaryId`	string	tidak	ID cabang — hanya diperlukan jika terdapat beberapa cabang.

informasi

Untuk kasus penggunaan ini, tidak memungkinkan untuk mengorkestrasikan dengan Klasifikasi risiko penipuan. Hasil selalu dikembalikan secara sinkron dalam respons POST.

Persyaratan gambar

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

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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    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" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Field	Tipe	Deskripsi
`id`	string (UUID)	Pengidentifikasi proses. Gunakan dengan Dapatkan Proses untuk kueri ulang.
`status`	integer	`1` (memproses), `3` (selesai dengan sukses), `5` (error). Untuk semua nilai yang mungkin, lihat Dapatkan Proses.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — lihat Verifikasi Identitas.
`identityFraudsters.result`	string	`yes`, `inconclusive` — lihat Klasifikasi risiko penipuan.
`government.serpro`	integer	Skor kesamaan Serpro (0–100, -1, -2). Lihat Hasil Kemiripan Serpro.
`liveness`	integer	`1` (lulus), `2` (gagal) — lihat Deteksi Kehidupan.

informasi

Ketika unicoId.result = inconclusive dan orkestrasi Klasifikasi risiko penipuan 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)	Pengidentifikasi proses.
`status`	integer	`3` (selesai dengan sukses), `5` (error). Untuk semua nilai yang mungkin, lihat Dapatkan Proses.
`biometryToken.result`	boolean	`true` jika wajah yang dikirimkan cocok dengan proses referensi; `false` jika tidak.
`liveness`	integer	`1` (lulus), `2` (gagal) — lihat Deteksi Kehidupan.

400 Bad Request

Payload tidak sesuai format, gambar tidak valid, atau field yang diperlukan 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 limit tercapai. Coba lagi setelah interval yang ditunjukkan di header respons Retry-After. Lihat Rate limits.

Kode Error

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Kode	Pesan	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` mengarah ke proses yang tidak ada atau tidak lagi dapat diakses.
`20512`	The referenced process is not available for reuse.	Proses yang direferensikan ada tetapi tidak tersedia untuk digunakan ulang.
`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 tidak dikenal di field `useCase`.
`20024`	The referenceProcessId field is missing.	Parameter `referenceProcessId` tidak disediakan 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` berada 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 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.

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.

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

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

Langkah selanjutnya

Untuk mengkueri 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​

Langkah selanjutnya​