Verifikasi Usia

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 — harus memiliki kapabilitas Verifikasi Usia diaktifkan.
Content-Type	application/json

Parameter body

Field	Tipe	Wajib	Deskripsi
subject	object	ya	Wadah informasi pengguna.
subject.code	string	kondisional	CPF (BR) atau CURP (MX), tanpa format. Diperlukan ketika alur mencakup Deteksi Kehidupan atau Verifikasi Identitas (lihat kapabilitas Verifikasi Usia); tidak diperlukan untuk alur khusus Verifikasi Usia.
subject.name	string	tidak	Nama lengkap pengguna.
subject.gender	string	tidak	M untuk laki-laki atau F untuk perempuan.
subject.birthDate	string (ISO 8601)	tidak	Tanggal lahir (YYYY-MM-DD).
subject.email	string	tidak	Alamat email pengguna.
subject.phone	string	tidak	Nomor telepon: kode negara + kode area + nomor, tanpa pemisah (misalnya 5519725570707).
useCase	string	tidak	Identifier use case operasi.
subsidiaryId	string	tidak	ID cabang — diperlukan hanya jika ada beberapa cabang.
imageBase64	string	ya	Output SDK terenkripsi atau gambar base64 (PNG, JPEG, WebP).

Persyaratan gambar

• Resolusi minimum: 640 x 480 (standar HD)
• Ukuran file maksimum: 800 KB (kompresi JPEG92 disarankan)
• Token JWT dari SDK kedaluwarsa setelah 10 menit dan hanya dapat digunakan sekali

Contoh

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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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: {
      code: '12345678909',
      name: 'Luke Skywalker',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respons

200 OK

Field respons yang dikembalikan tergantung pada kapabilitas mana yang diaktifkan untuk APIKEY Anda.

Verifikasi Usia saja (tanpa Deteksi Kehidupan, tanpa Verifikasi Identitas):

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idAge": { "result": "yes" }
}

Verifikasi Usia + Deteksi Kehidupan + Verifikasi Identitas:

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

Field	Tipe	Deskripsi
id	string (UUID)	Identifier proses. Gunakan dengan Dapatkan Proses untuk kueri ulang.
status	integer	3 (selesai dengan sukses), 5 (error). Hanya gunakan status = 3 untuk keputusan bisnis. Untuk semua nilai yang mungkin, lihat Dapatkan Proses.
idAge.result	string	yes, no, inconclusive — Hasil Verifikasi Usia. Muncul di semua respons.
unicoId.result	string	yes, no, inconclusive — muncul hanya ketika Verifikasi Identitas diaktifkan.
liveness	integer	1 (lulus), 2 (gagal) — muncul hanya ketika Deteksi Kehidupan diaktifkan.

400 Bad Request

Payload salah format, gambar tidak valid, atau field wajib tidak ada.

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.

500 Internal Server Error

Error server yang tidak terduga.

Kode Error

400 Bad Request

Code	Message	Deskripsi
20900	O base64 informado não é válido.	Parameter base64 tidak valid; kemungkinan masalah gambar atau injeksi.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Resolusi gambar di bawah ambang minimum.
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 identifier yang salah format atau tidak ada. Hanya terpicu ketika Deteksi Kehidupan atau Verifikasi Identitas termasuk dalam alur — tidak diperlukan untuk alur khusus Verifikasi Usia.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Payload melebihi 800 KB; kompres ke JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Format tidak didukung atau prefiks base64 tidak valid.
20062	The useCase field is invalid.	Nilai yang tidak dikenali 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 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.
20005	O parâmetro subject.code não foi informado.	Parameter subject.code tidak ada. Hanya terpicu ketika Deteksi Kehidupan atau Verifikasi Identitas termasuk dalam alur — tidak diperlukan untuk alur khusus Verifikasi Usia.
20004	O parâmetro subject não foi informado.	Objek subject tidak ada.
20003	The request body is missing or invalid.	Payload null atau salah format.
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.
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 melebihi jendela validitas 10 menit.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 bukan JWT valid yang dihasilkan oleh SDK.

403 Forbidden

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.
30017	Jwt header is an invalid JSON.	Access-token mengandung karakter tidak valid.
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.

409 Conflict

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

500 Internal Server Error

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

Selanjutnya

• Untuk melihat kueri proses yang sudah ada, lihat Dapatkan Proses.