Verifikasi Usia

Untuk alur integrasi lengkap, lihat Gambaran Umum API.

Endpoint

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

Permintaan

Header

Header	Nilai
Authorization	Bearer <access_token> (lihat Autentikasi)
APIKEY	API key yang telah disediakan — harus memiliki kemampuan Verifikasi Usia yang diaktifkan.
Content-Type	application/json

Parameter body

Kolom	Tipe	Wajib	Deskripsi
subject	object	ya	Kontainer informasi pengguna.
subject.code	string	kondisional	CPF (BR) atau CURP (MX), tanpa pemformatan. Wajib diisi ketika alur menyertakan Deteksi Kehidupan atau Verifikasi Identitas (lihat kemampuan Verifikasi Usia); tidak wajib untuk alur khusus Verifikasi Usia saja.
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 (mis. 5519725570707).
useCase	string	tidak	Pengidentifikasi use case operasi.
subsidiaryId	string	tidak	ID cabang — hanya wajib jika ada beberapa cabang.
imageBase64	string	ya	Output SDK terenkripsi atau gambar base64 (PNG, JPEG, WebP).

Persyaratan gambar

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

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

Kolom respons yang dikembalikan bergantung pada kemampuan mana yang diaktifkan untuk APIKEY Anda.

Hanya Verifikasi Usia (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
}

Kolom	Tipe	Deskripsi
id	string (UUID)	Pengidentifikasi 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. Selalu ada dalam semua respons.
unicoId.result	string	yes, no, inconclusive — hanya ada ketika Verifikasi Identitas diaktifkan.
liveness	integer	1 (lulus), 2 (gagal) — hanya ada ketika Deteksi Kehidupan diaktifkan.

400 Bad Request

Payload tidak valid, gambar tidak valid, atau kolom yang wajib diisi 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. Coba lagi setelah interval yang ditunjukkan dalam header respons Retry-After. Lihat Batas rate.

500 Internal Server Error

Error server yang tidak terduga.

Kode Error

400 Bad Request

Kode	Pesan	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 yang 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 valid atau tidak ada. Hanya muncul saat Deteksi Kehidupan atau Verifikasi Identitas disertakan dalam alur — tidak wajib untuk alur khusus Verifikasi Usia saja.
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 awalan base64 tidak valid.
20062	The useCase field is invalid.	Nilai tidak dikenal dalam kolom 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 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 muncul saat Deteksi Kehidupan atau Verifikasi Identitas disertakan dalam alur — tidak wajib untuk alur khusus Verifikasi Usia saja.
20004	O parâmetro subject não foi informado.	Objek 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.	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 satu kali.
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 yang valid yang dihasilkan oleh SDK.

403 Forbidden

Kode	Pesan	Deskripsi
30017	User does not have permission to perform this action.	JWT tidak valid atau pengguna tidak memiliki izin untuk melakukan operasi ini.
30017	Jwt header is an invalid JSON.	Access-token mengandung karakter yang 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

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.	Error pemrosesan di sisi server.

Langkah selanjutnya

• Untuk menanyakan proses yang ada, lihat Dapatkan Proses.