Pemrosesan Ulang dan Impor Basis Biometrik

MarkdownChatGPTClaude

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
AR	6	Paspor Argentina
AR	7	DNI Argentina
AR	49	SIM Argentina (Licencia Nacional de Conducir)
AT	34	Nomor Pajak Austria (STNR)
BE	36	Nomor Nasional Belgia (NN)
BR	1	CPF Brasil
BR	5	Paspor Brasil
BR	14	CNPJ Brasil
CA	28	SIN Kanada
CH	33	Nomor AHV/AVS Swiss
CL	9	RUN Chili
CL	52	Paspor Chili
CL	57	SIM Chili (Licencia de Conducir)
CO	26	NIT Kolombia
CO	53	Paspor Kolombia
CO	55	SIM Kolombia (Licencia de Conducción)
CO	56	Kartu Kewarganegaraan Kolombia (Cédula de Ciudadanía)
DE	41	Nomor Identifikasi Pajak Jerman (IdNr)
DK	29	CPR Denmark
EC	10	NI Ekuador
ES	50	Nomor Identitas Warga Asing Spanyol (NIE)
ES	51	Dokumen Identitas Nasional Spanyol (DNI)
FI	35	Kode Identitas Pribadi Finlandia (HETU)
FR	46	Nomor Referensi Pajak Prancis (SPI)
GB	30	Nomor Asuransi Nasional Inggris (NINO)
GT	12	CUI Guatemala
ID	16	NIK Indonesia
IE	47	Nomor Layanan Publik Pribadi Irlandia (PPSN)
IT	37	Codice Fiscale Italia (CF)
LU	48	Nomor Identifikasi Nasional Luksemburg (Matricule)
MX	2	CURP Meksiko
MX	25	RFC Meksiko (Perorangan)
MX	58	SIM Meksiko (Licencia de Conducir)
NG	8	NIN Nigeria
NG	20	Nomor Verifikasi Bank Nigeria (BVN)
NG	43	Token BVN Nigeria (hash)
NG	44	Token NIN Nigeria (hash)
NL	42	Nomor Layanan Warga Negara Belanda (BSN)
NO	39	Nomor Identitas Nasional Norwegia (Fødselsnummer)
PE	27	RUC Peru
PE	40	DNI Peru
PE	54	Paspor Peru
PL	31	PESEL Polandia
PT	45	Nomor Identifikasi Pajak Portugal (NIF)
SE	32	Nomor Pribadi Swedia (PNR)
SE	38	Nomor Koordinasi Swedia (Samordningsnummer)
TR	24	Nomor Identifikasi Turki (TCKN)
US	4	SSN Amerika Serikat
US	11	Paspor Amerika Serikat
US	18	SIM Amerika Serikat
US	21	Kartu Paspor Amerika Serikat
US	22	Paspor Polikarbonat Amerika Serikat
US	23	Kartu Identitas Amerika Serikat
UY	13	CI Uruguay
ZZ	15	Alamat email
ZZ	17	Nomor telepon
—	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.