Identity Verification (Privy & Google Vision)

Modul ini mencakup endpoint API v1 untuk verifikasi identitas berbasis dokumen/foto:

• Privy: OCR KTP + liveness + registrasi akun Privy
• Google Vision: penyimpanan hasil verifikasi dan riwayat verifikasi per user

Daftar route (protected)

Semua endpoint di bawah berada di dalam middleware group: auth.xtoken, verified:api.

Method	Path	Controller@method
POST	/api/privy/ocr	PrivyController@privy_ocr
POST	/api/privy/liveness-register	PrivyController@prive_liveness_and_register
POST	/api/google-vision/verification	GoogleVisionController@storeVerification
PUT	/api/google-vision/verification/{requestId}	GoogleVisionController@updateVerification
GET	/api/google-vision/verifications	GoogleVisionController@getVerifications
GET	/api/google-vision/verification/{requestId}	GoogleVisionController@getVerificationDetail
GET	/api/google-vision/statistics	GoogleVisionController@getStatistics

Catatan:

• Endpoint Privy memakai envelope sendResponse/sendError.
• Endpoint Google Vision memakai response JSON custom {success, message, data, ...} (bukan envelope standar).

---

Privy OCR (KTP)

Route

• POST /api/privy/ocr
• Controller: PrivyController@privy_ocr
• Request validation: PrivyOcrRequest
• Content-Type: multipart/form-data

Payload

Field	Type	Required
userId	string/int	Ya
nationality	string/int	Ya
ktp_image	file	Ya (jpeg/png/jpg)

Behavior penting

• Hanya untuk user dengan negara Indonesia (berdasar lookup Country::find(nationality)).
• Generate trId dan panggil PrivyLibrary()->ocr(trId, file).
• Upload image ke OSS dan kembalikan image_ocr_url (signed URL) di response sukses.
• Simpan riwayat ke PrivyHistory (request/response + objectName OSS).

Response

• sukses: api.privy_ocr_success dengan data dari Privy + image_ocr_url
• gagal umum:
  • api.only_for_indonesian
  • api.privy_ocr_fail
  • api.oss_upload_fail
  • api.url_oss_fail

---

Privy Liveness + Register

Route

• POST /api/privy/liveness-register
• Controller: PrivyController@prive_liveness_and_register
• Request validation: PrivyLivenessAndRegisterRequest
• Content-Type: multipart/form-data

Payload

Field	Type	Required
userId	string/int	Ya
nationality	string/int	Ya
face1	file	Ya
face2	file	Ya
phone	string	Ya
email	string	Ya
selfie	file	Ya
ktp	file	Ya

Behavior penting

• Hanya untuk Indonesia.
• Ambil image_ocr terakhir dari PrivyHistory service OCR untuk user (dipakai untuk referensi).
• Panggil PrivyLibrary()->liveness(...), upload face1 dan face2 ke OSS, simpan PrivyHistory service LIVENESS.
• Setelah liveness, controller memanggil privy_acc_register(...) untuk registrasi akun Privy:
  • Ambil OCR result terakhir,
  • Panggil PrivyLibrary()->register(...),
  • Simpan PrivyHistory service REGISTRATION.
• Endpoint selalu mengembalikan sukses api.privy_liveness_register_success setelah proses (status detail tersimpan di history).

Response

• sukses: api.privy_liveness_register_success
• gagal umum:
  • api.only_for_indonesian
  • api.oss_upload_fail

---

Google Vision verification

Semua endpoint Google Vision berada di prefix /api/google-vision/*.

1) Create verification

• POST /api/google-vision/verification
• Controller: GoogleVisionController@storeVerification
• Content-Type: multipart/form-data

Payload (ringkas):

• image (file): required, jpeg/jpg/png, max 10MB
• service (string): salah satu dari service constant di model GoogleVisionVerification
• request_data (object/array): required
• response_data (object/array): required
• status (optional): pending|processing|completed|failed

Response:

• sukses: HTTP 201, { "success": true, "data": <verification.data()> }
• gagal validasi: HTTP 422, { "success": false, "errors": {...} }
• tidak authenticated: HTTP 401
• error internal: HTTP 500

2) Update verification response

• PUT /api/google-vision/verification/{requestId}
• Payload:
  • response_data (array) required
  • status optional
• Response:
  • 200 sukses
  • 404 jika record tidak ditemukan untuk user tsb
  • 422 validasi gagal

3) List verifications

• GET /api/google-vision/verifications
• Query optional:
  • per_page
  • service
  • status
• Response:
  • 200 sukses, data list + pagination

4) Get verification detail

• GET /api/google-vision/verification/{requestId}
• Response:
  • 200 sukses
  • 404 jika tidak ditemukan

5) Statistics

• GET /api/google-vision/statistics
• Response: 200 sukses (detail mengikuti implementasi controller)