API Kiosk

API internal untuk perangkat kiosk pondok (mesin cek saldo & verifikasi sidik jari yang ditempel di lokasi tertentu). Bukan untuk aplikasi mobile wali — lihat halaman Dokumentasi API Wali untuk itu.

Jangan tertukar dengan halaman web "Kios" (/kios)

Namanya mirip tapi dua hal berbeda. Halaman ini mendokumentasikan REST API /api/kiosk/* di atas — butuh token perangkat Sanctum, dipakai perangkat fisik. Sedangkan /kios adalah halaman web publik tanpa login (Livewire\Kios\CekSaldo) tempat santri tap kartu RFID untuk cek saldo & sisa limit penarikan, dan bisa mengajukan (bukan mencairkan) request penarikan tunai langsung dari situ. Keduanya sama sekali tidak berbagi kode — halaman /kios tidak memanggil endpoint API di halaman ini.

Token perangkat kiosk dibuat sekali oleh admin lewat php artisan tinker atau seeder (lihat DeviceSeeder) — tidak ada endpoint self-registration perangkat. Token dibuat dengan ability kiosk, tidak bisa dipakai untuk endpoint API wali.

Autentikasi

Sama seperti API Wali: Bearer token via Sanctum, tapi tokenable-nya model Device, bukan User. Kirim header:

Authorization: Bearer <token-perangkat>
Accept: application/json

Cek Saldo

POST /api/kiosk/cek-saldo butuh token perangkat

Dipanggil saat santri menempelkan kartu & sidik jari di mesin. Kiosk melakukan pencocokan sidik jari secara lokal di perangkat — server hanya menerima referensi hasil pencocokan tsb dan memverifikasinya terhadap data kartu yang tersimpan (lihat TrustedDeviceFingerprintVerifier di halaman Tentang Aplikasi). Server tidak pernah menerima/menyimpan data biometrik mentah.

Field	Tipe	Keterangan
`nomor_kartu`	string	Nomor kartu yang ditempel
`fingerprint_ref`	string	Referensi hasil pencocokan sidik jari dari perangkat

200 OK

{
  "nama": "Ahmad Fauzi",
  "nis": "1001000001",
  "saldo": 200000,
  "tagihan_belum_lunas": 1
}

422 — kartu tidak aktif / tidak ditemukan, atau referensi sidik jari tidak cocok

{ "message": "Kartu atau verifikasi sidik jari tidak valid." }

Verifikasi Sidik Jari untuk Penarikan Tunai

POST /api/kiosk/penarikan/verifikasi-fingerprint butuh token perangkat

Endpoint ini tidak memindahkan uang. Endpoint ini hanya mencatat bahwa kiosk sudah mencocokkan sidik jari santri untuk sebuah PenarikanRequest yang sudah disetujui petugas. Pencairan uang sebenarnya tetap harus dilakukan petugas lewat halaman Admin → Penarikan Tunai — sengaja dipisah dua langkah (kiosk + petugas) sebagai lapis keamanan tambahan.

Field	Tipe	Keterangan
`penarikan_request_id`	integer	ID request penarikan yang statusnya sudah `disetujui`
`fingerprint_ref`	string	Referensi hasil pencocokan sidik jari dari perangkat

200 OK

{ "message": "Verifikasi berhasil, silakan lanjutkan ke petugas untuk pencairan." }

422 — request belum disetujui petugas, atau sidik jari tidak cocok

{ "message": "Request penarikan belum disetujui petugas." }

Heartbeat Perangkat

POST /api/kiosk/device/heartbeat butuh token perangkat

Dipanggil berkala oleh perangkat untuk menandai bahwa kiosk masih online (memperbarui last_seen_at). Tidak ada body request.

200 OK

{ "status": "ok", "time": "2026-07-11T10:00:00+00:00" }

Status Pengembangan

API ini adalah fondasi untuk Fase 2 (integrasi perangkat kiosk fisik sungguhan). Saat ini bisa diuji manual dengan token dari DeviceSeeder, mengirim fingerprint_ref yang cocok dengan fingerprint_template_ref pada data kartu_santris di database (lihat Admin → Kartu Santri).