Pemrosesan Ulang dan Impor Basis Biometrik

Panduan ini membahas cara melakukan pemrosesan ulang atau impor basis biometrik di platform Unico. Panduan ini menjelaskan persyaratan teknis dan operasional untuk integrasi yang efektif dan aman sesuai dengan praktik terbaik platform.

Cakupan

Materi ini mencakup dua jenis proses:

• Pemrosesan Ulang: memproses ulang rekaman biometrik pengguna yang telah melalui basis klien dan Unico untuk evaluasi ulang atau migrasi antar sistem.
• Impor Basis Biometrik: unggah awal atau pembaruan basis yang berisi selfie untuk tujuan verifikasi identitas dan/atau risk classification.
• Impor Basis Dokumen: unggah basis dokumen bersama selfie untuk tujuan verifikasi Facematch atau CPF Match (khusus Brasil).

Prasyarat

• Klien harus memiliki kontrak aktif atau NDA yang ditandatangani dengan Unico dan berada dalam fase integrasi (pengecualian jika disetujui oleh tim governance).
• Proyek akan mengikuti perjanjian TPS (transaksi per detik) formal. Lihat Perjanjian TPS di bawah.
• Sebelum mendapatkan kredensial produksi, homologasi integrasi penuh wajib dilakukan untuk memastikan kualitas data, kepatuhan payload, dan performa yang stabil.
• Akun layanan khusus harus dibuat untuk pemrosesan ulang atau impor (misalnya, "Reprocessing" atau "Legacy_Import").
• API Key khusus akan dibuat secara spesifik untuk pemrosesan ulang/impor.
• (Opsional) Subsidiary khusus dapat dibuat untuk pemrosesan ulang/impor. Parameter ini diidentifikasi dalam payload sebagai subsidiaryId. Lihat Parameter payload di bawah.
• API Key dan akun layanan akan dinonaktifkan setelah periode yang disepakati atau penyelesaian pemrosesan.

Capability yang tersedia

Capability	Deskripsi
Identity Verification	Memverifikasi apakah selfie yang dikirimkan milik pemegang sebenarnya dari pengidentifikasi tersebut.
Klasifikasi Risiko Penipuan	Memeriksa riwayat perilaku penipuan yang terkait dengan wajah tersebut.
Facematch	Memverifikasi apakah foto dokumen cocok dengan selfie yang dikirimkan.
CPF Match Brazil only	Memverifikasi apakah CPF yang diberikan cocok dengan nomor CPF yang tercetak pada dokumen. Catatan: tidak semua RG mencantumkan CPF.

Persyaratan selfie

• Harus dikirimkan dalam format base64.
• Gambar harus mengikuti standar ICAO (latar belakang terang, wajah di tengah, tanpa aksesori yang menghalangi identifikasi, pencahayaan yang tepat).
• Dimensi yang direkomendasikan: 1080x1920 (potret) atau 1920x1080 (lanskap).
• Ukuran maksimum: 800 KB (kompres dengan JPEG 92 jika diperlukan).
• Orientasi: portrait.

Persyaratan dokumen

• Jenis dokumen yang didukung: lihat Pengambilan Dokumen dan Penggunaan Kembali — Dokumen yang didukung.
• Gambar harus mencakup bagian depan dan belakang dokumen, terlihat sepenuhnya tanpa pemotongan.
• Dokumen harus terbaca — jelas, berpenampilan baik, dan bebas dari hambatan.

Perjanjian TPS

• TPS maksimum yang disepakati untuk proyek ini adalah 10 TPS.
• Distribusikan permintaan secara merata dari waktu ke waktu daripada mengirimkannya dalam ledakan besar.
• Batas ini tidak boleh dilampaui tanpa persetujuan formal dari tim Unico.
• Permintaan di atas batas dapat secara otomatis di-drop atau diblokir.
• Jika diperlukan peningkatan sementara, perjanjian formal sebelumnya diperlukan.

Integrasi

Endpoint

Lingkungan	Base URL	Akses	Catatan
Staging	https://api.id.uat.unico.app	Terbuka	Wajib untuk pengujian
Production	https://api.id.unico.app	Hanya setelah homologasi disetujui	Memerlukan kontrol TPS yang ketat

Header yang diperlukan

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Parameter payload

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

Field	Tipe	Wajib	Deskripsi
subject	object	Ya	Data identifikasi pengguna.
subject.duiType	integer	Ya	Pengidentifikasi tipe dokumen. Lihat nilai duiType di bawah.
subject.code	string	Ya	CPF atau pengidentifikasi pengguna lainnya.
subject.name	string	Ya	Nama lengkap pengguna.
subject.email	string	Tidak	Email pengguna.
subject.phone	string	Tidak	Nomor telepon pengguna.
subject.birthDate	string	Tidak	Tanggal lahir pengguna (DD/MM/YYYY).
subject.gender	string	Tidak	Jenis kelamin pengguna (M atau F).
useCase	string	Ya	Nama use case ("Reprocessamento" atau "Importação de base").
subsidiaryId	string	Tidak	UUID subsidiary (disediakan oleh Unico).
imageBase64	base64	Ya	Gambar selfie pengguna yang dikonversi ke base64.
document	object	Tidak	Data dokumen yang terkait dengan proses.
document.purpose	string	Tidak	Tujuan dokumen (misalnya, "Reprocessamento").
document.documentId	string	Tidak	Pengidentifikasi dokumen.
document.files	array	Tidak	Daftar file gambar dokumen.
document.files[].data	base64	Tidak	Gambar dokumen yang dikonversi ke base64.
document.files[].faceDocumentMatch	boolean	Tidak	Menunjukkan apakah wajah dalam dokumen cocok dengan selfie yang dikirimkan.

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

Catatan penting

• Selfie harus mematuhi standar ICAO dengan kualitas dan pencahayaan yang tepat.
• Selfie harus dalam format base64.
• Hindari pengiriman massal tanpa kontrol TPS — ini dapat memicu pembatasan laju (lihat Penanganan error di bawah).
• Selalu uji data dan integrasi di lingkungan staging terlebih dahulu.

Respons

Berhasil — 200 OK

Tanpa dokumen

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Field	Tipe	Deskripsi
id	string	Pengidentifikasi proses. Simpan untuk kueri di masa mendatang atau jika Anda mengimplementasikan Validation (1:1) nanti.
status	integer	Status transaksi.
unicoId.result	string	Respons capability Verifikasi Identitas.
riskLevel.result	string	Hasil klasifikasi risiko penipuan. Nilai yang mungkin: reproved, risk-critical, risk-high, inconclusive.

Dengan dokumen (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "riskLevel": {
    "result": "inconclusive"
  }
}

Field	Tipe	Deskripsi
id	string	Pengidentifikasi proses. Simpan untuk kueri di masa mendatang atau jika Anda mengimplementasikan Validation (1:1) nanti.
status	integer	Status transaksi.
score	number	Skor Facematch.
unicoId.result	string	Respons capability Verifikasi Identitas.
faceDocumentMatch.faceMatch	boolean	Apakah foto dokumen cocok dengan selfie yang dikirimkan.
riskLevel.result	string	Hasil klasifikasi risiko penipuan. Nilai yang mungkin: reproved, risk-critical, risk-high, inconclusive.

Error pemrosesan gambar

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

Error umum

Kode dalam rentang 4xx menunjukkan error validasi dengan data yang diberikan. Kode dalam rentang 5xx menunjukkan kegagalan di sisi server.

Kode HTTP	Tipe Error	Kemungkinan Penyebab	Tindakan yang Disarankan
400	Bad Request	Payload tidak valid	Validasi struktur dan konten.
401	Unauthorized	Token kedaluwarsa atau tidak valid	Buat ulang token.
403	Forbidden	API Key salah atau izin tidak memadai	Verifikasi kredensial.
429	Too Many Requests	Laju permintaan terlampaui	Tunggu dan patuhi batas TPS.
500+	Internal Server Error	Kegagalan internal	Coba lagi setelah beberapa detik; buka tiket jika terus berlanjut.

Penanganan error

• Rate Limit (HTTP 429) harus dipantau dengan cermat. Kelebihan beban permintaan dapat memblokir pipeline.
• Selalu patuhi TPS yang disepakati dengan Unico (lihat Perjanjian TPS).
• Untuk kegagalan yang terus-menerus (5xx), proses ulang dengan kontrol retry/backoff.