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.
Risk Fraud Classification	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: rasio 1920x1080 atau 1080x1920.
• 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

Nilai	Deskripsi
0	Tidak ditentukan
1	Brasil — CPF
2	Meksiko — CURP
3	Pengidentifikasi internal Unico
4	Amerika Serikat — SSN
5	Brasil — Paspor
6	Argentina — Paspor
7	Argentina — DNI
8	Nigeria — NIN
9	Chili — RUN
10	Ekuador — NI
11	Amerika Serikat — Paspor
12	Guatemala — CUI
13	Uruguay — CI
15	Alamat email
16	Indonesia — NIK
17	Nomor telepon
18	Amerika Serikat — SIM

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.