PIN & Biometric

Modul ini mencakup endpoint API v1 untuk fitur keamanan aplikasi: PIN (create/validate/update/status) dan biometric lock.

Daftar route

Method	Path	Controller@method	Middleware
POST	/api/pin/status_pin	PinController@statusPin	publik
POST	/api/pin/create	PinController@createPin	auth.xtoken, verified:api
POST	/api/pin/validate	PinController@validatePin	auth.xtoken, verified:api, throttle.custom
POST	/api/pin/update	PinController@updatePin	auth.xtoken, verified:api, throttle.custom
POST	/api/biometric/create-or-update	BiometricController@createOrUpdate	auth.xtoken, verified:api

Catatan: semua response (kecuali error validasi Laravel) mengikuti envelope di docs/bitwewe/api-conventions.

---

PIN

Request validation class: PinRequest

Field yang dikenal oleh PinRequest:

• email (email)
• password (string)
• pin (numeric, 6 digit, confirmed)
• pin_lock (0|1)

1) Status PIN

• POST /api/pin/status_pin
• Controller: PinController@statusPin
• Validation: PinRequest (menggunakan email)

Payload:

{
  "email": "user@example.com"
}

Behavior:

• Cari user berdasarkan email.
• Ambil record UserPin berdasarkan id_user.

Response sukses (api.pin_status_success):

• status_pin: boolean (PIN sudah terset atau belum)
• pin_lock: boolean
• biometrics_lock: boolean

Response gagal:

• api.pin_status_failed (email tidak ditemukan / error)

2) Create PIN

• POST /api/pin/create
• Controller: PinController@createPin
• Validation: PinRequest (menggunakan pin + pin_confirmation)

Payload:

{
  "pin": "123456",
  "pin_confirmation": "123456"
}

Behavior:

• Hash PIN dengan Hash::make.
• Jika UserPin sudah ada dan pin sudah terisi: error api.pin_exists.
• Jika UserPin ada tapi pin kosong: update pin dan set pin_lock = 1.
• Jika belum ada: buat record baru UserPin dan set pin_lock = 1.

Response:

• sukses: api.pin_created
• gagal:
  • api.pin_invalid_request (pin kosong)
  • api.pin_exists

3) Validate PIN (login via PIN)

• POST /api/pin/validate
• Controller: PinController@validatePin
• Payload:

{
  "pin": "123456"
}

Behavior:

• Pastikan UserPin ada.
• Cocokkan PIN dengan Hash::check.

Response:

• sukses: message auth.logged_in
• gagal:
  • api.pin_not_exists
  • api.pin_login_failed

4) Update PIN / pin_lock

• POST /api/pin/update
• Controller: PinController@updatePin
• Validation: PinRequest

Payload (opsi A: update PIN):

{
  "password": "<password-login>",
  "pin": "654321",
  "pin_confirmation": "654321"
}

Payload (opsi B: toggle lock):

{
  "pin_lock": "0"
}

Behavior:

• Jika pin diisi, wajib verifikasi password login user.
• Jika update pin_lock, akan error bila nilainya sama dengan sebelumnya.

Response:

• sukses: api.pin_update_success (data: [])
• gagal:
  • api.pin_invalid_request (pin & pin_lock kosong)
  • api.pin_not_exists
  • api.pin_update_failed (password salah / kasus umum)
  • api.pin_update_failed_same_value

---

Biometric lock

Route

• POST /api/biometric/create-or-update
• Controller: BiometricController@createOrUpdate
• Request validation: BiometricRequest

Payload:

{
  "biometrics_lock": "1"
}

Behavior:

• Jika UserPin sudah ada:
  • update biometrics_lock (0/1)
  • error jika nilai sama (no-op)
• Jika belum ada:
  • create record UserPin berisi biometrics_lock

Response:

• sukses:
  • api.biometric_update_success (update)
  • api.biometric_created (create)
• gagal:
  • api.biometric_update_failed (request invalid)
  • api.biometric_update_failed_same_value