Perangkat Pinjaman

Lihat Markdown

Presensi lewat ponsel rekan kerja bila ponsel karyawan bermasalah. Karyawan memasukkan Nomor Karyawan dan kata sandi di perangkat pinjaman, menerima kode 6 digit lewat surel, lalu mendapat token sesi pinjaman dengan jatah presensi terbatas. Perangkat pemilik tidak berubah dan pemiliknya tetap dapat masuk seperti biasa. Konvensi umum ada di README.md; login biasa ada di auth.md.

Atribut Nilai
Endpoint POST /auth/lend/request, POST /auth/lend/verify, GET /me/lending, POST /auth/lend/end
Sumber kode DeviceLendingController, RequestDeviceLendingRequest, VerifyDeviceLendingRequest, DeviceLendingResource, DeviceLendingService, EmployeeAuthService
Contoh direkam 2026-11-12 sampai 2026-12-01, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, APP_LOCALE=id. Kode surel diambil dari notifikasi palsu
Data uji Citra Satu meminjam ponsel Budi Satu (0a9c71de-budi-redmi13, Xiaomi Redmi 13). Pengaturan bawaan (policy.device_lending): aktif, kode berlaku 10 menit, sesi 12 jam, 2 presensi per sesi, 3 sesi per bulan, 5 kali salah kode

Alur:

  1. POST /auth/lend/request (tanpa token) → kode dikirim ke surel karyawan.
  2. POST /auth/lend/verify (tanpa token) → token sesi pinjaman + data karyawan + status izin.
  3. Presensi memakai token sesi pinjaman (POST /attendance/check-in, /check-out); setiap presensi yang diterima memakai satu jatah.
  4. Sesi berakhir saat jatah habis, masa sesi lewat, atau POST /auth/lend/end. Token sesi dihapus server saat berakhir; panggilan berikutnya dijawab 401.

Enum

DeviceLendingStatus (status)

Nilai status_label Arti
PENDING Menunggu Kode kode sudah dikirim, belum diverifikasi
ACTIVE Sedang Berlaku terverifikasi; token sesi dapat dipakai presensi
COMPLETED Selesai Dipakai jatah presensi habis
EXPIRED Kedaluwarsa kode tidak dimasukkan tepat waktu, atau masa sesi lewat
REVOKED Dicabut dihentikan karyawan/Admin HR, terlalu banyak salah kode, atau digantikan permintaan baru

DevicePlatform (platform, device_platform) sama dengan auth.md.


Objek lending

Sumber: DeviceLendingResource.

Field Tipe Null Keterangan
id integer tidak ID izin pinjam
status string (enum) tidak DeviceLendingStatus
status_label string tidak label tampilan
device_name string ya nama perangkat pinjaman
device_identifier string tidak pengenal perangkat pinjaman
platform string (enum) tidak DevicePlatform
owner_name string ya nama pemilik perangkat bila perangkat terdaftar atas karyawan lain; null bila tidak dikenal
usage_count integer tidak jumlah presensi yang sudah memakai sesi ini
max_usages integer tidak jatah presensi per sesi
remaining_usages integer tidak max_usages - usage_count
requested_at string (ISO 8601 UTC) tidak waktu kode diminta
verified_at string (ISO 8601 UTC) ya waktu kode diverifikasi
expires_at string (ISO 8601 UTC) ya akhir sesi = verified_at + session_hours
ended_at string (ISO 8601 UTC) ya waktu sesi berakhir
end_reason string ya alasan berakhir
is_usable boolean tidak true bila ACTIVE, belum lewat expires_at, dan jatah masih ada

Minta kode izin

POST /auth/lend/request

Deskripsi: memeriksa Nomor Karyawan/surel dan kata sandi, lalu mengirim kode 6 digit ke surel karyawan. Permintaan baru menutup izin lain milik karyawan yang masih terbuka.

Auth & Middleware
Token tidak
Middleware throttle:device-lending
Route name api.v1.auth.lend.request

Header: Accept: application/json, Content-Type: application/json

Parameter (RequestDeviceLendingRequest)

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
identifier body string ya required, string, max:150. Nomor Karyawan atau surel
password body string ya required, string
device_identifier body string ya required, string, max:150. Pengenal perangkat pinjaman, sama dengan yang dipakai login
device_platform body string (enum) ya required, salah satu DevicePlatform
device_name body string tidak nullable, string, max:100
app_version body string tidak nullable, string, max:50

Contoh Request (2026-11-12 07:30 WIB)

POST /api/v1/auth/lend/request HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "citra@nusantara-logistik.test",
  "password": "Rahasia123!",
  "device_identifier": "0a9c71de-budi-redmi13",
  "device_platform": "ANDROID",
  "device_name": "Xiaomi Redmi 13",
  "app_version": "1.0.1"
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Kode izin sudah dikirim ke alamat surel Anda.",
  "data": {
    "email": "ci***@nusantara-logistik.test",
    "expires_minutes": 10,
    "session_hours": 12,
    "max_usages": 2
  }
}

Field data

Field Tipe Null Keterangan
email string tidak surel tujuan yang disamarkan (dua huruf pertama terlihat)
expires_minutes integer tidak masa berlaku kode
session_hours integer tidak lama sesi setelah verifikasi
max_usages integer tidak jatah presensi per sesi

Penolakan dan urutan pemeriksaan

# HTTP message (direkam bila bertanda ✓)
1 429 ✓ Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.
2 422 ✓ Data yang dikirim tidak lolos pemeriksaan.
3 401 ✓ Nomor Karyawan atau kata sandi tidak sesuai. (juga akun nonaktif atau identifier ganda)
4 403 ✓ Perusahaan Anda tidak mengizinkan presensi lewat perangkat pinjaman. Hubungi Admin HR untuk mendaftarkan perangkat baru. (errors.device_lending)
5 422 Akun Anda belum memiliki alamat surel sehingga kode izin tidak dapat dikirim. Hubungi Admin HR.
6 422 ✓ Perangkat ini sudah terdaftar atas nama Anda. Masuklah seperti biasa tanpa kode izin.
7 422 ✓ Pinjam perangkat hanya dapat dipakai 3 kali dalam satu bulan dan jatah bulan ini sudah habis. Hubungi Admin HR untuk mendaftarkan perangkat baru.

Kuota bulanan menghitung sesi yang berhasil diverifikasi pada bulan berjalan; kode yang tidak pernah dimasukkan tidak memakai kuota.

Validasi (password, device_identifier kosong, device_platform: "WINDOWS"):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": [
      "Kolom kata sandi wajib diisi."
    ],
    "device_identifier": [
      "Kolom pengenal perangkat wajib diisi."
    ],
    "device_platform": [
      "Pilihan pada kolom jenis perangkat tidak sah."
    ]
  }
}

Verifikasi kode

POST /auth/lend/verify

Deskripsi: mencocokkan kode, mengaktifkan izin, dan menerbitkan token sesi pinjaman.

Auth & Middleware
Token tidak
Middleware throttle:device-lending
Route name api.v1.auth.lend.verify

Parameter (VerifyDeviceLendingRequest)

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
identifier body string ya required, string, max:150
password body string ya required, string. Diperiksa ulang
device_identifier body string ya required, string, max:150. Wajib sama dengan saat meminta kode
code body string ya required, string, size:6. Kirim sebagai teks agar nol di depan tidak hilang

Contoh Request (2026-11-12 07:32 WIB)

POST /api/v1/auth/lend/verify HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "citra@nusantara-logistik.test",
  "password": "Rahasia123!",
  "device_identifier": "0a9c71de-budi-redmi13",
  "code": "509434"
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Izin presensi pada perangkat ini berlaku. Jangan lupa keluar setelah selesai.",
  "data": {
    "token": "4|contohTokenDisamarkanTidakBerlakuDiServerManaPun",
    "employee": {
      "id": 3,
      "employee_number": "EMP-0007",
      "name": "Citra Satu",
      "email": "citra@nusantara-logistik.test",
      "phone": "081234560007",
      "employment_status": "OUTSOURCE",
      "employment_status_label": "Alih Daya",
      "work_pattern": "FIXED",
      "work_pattern_label": "Jam Tetap",
      "department": "Divisi Operasional",
      "position": "Spesialis",
      "job_level": "Direktur",
      "must_change_password": false
    },
    "lending": {
      "id": 1,
      "status": "ACTIVE",
      "status_label": "Sedang Berlaku",
      "device_name": "Xiaomi Redmi 13",
      "device_identifier": "0a9c71de-budi-redmi13",
      "platform": "ANDROID",
      "owner_name": "Budi Satu",
      "usage_count": 0,
      "max_usages": 2,
      "remaining_usages": 2,
      "requested_at": "2026-11-12T00:30:00+00:00",
      "verified_at": "2026-11-12T00:32:00+00:00",
      "expires_at": "2026-11-12T12:32:00+00:00",
      "ended_at": null,
      "end_reason": null,
      "is_usable": true
    }
  }
}

Field data

Field Tipe Null Keterangan
token string tidak token sesi pinjaman; kirim sebagai Authorization: Bearer
employee objek tidak sama dengan data.employee pada login (auth.md)
lending objek tidak objek lending

Penolakan (422, errors.device_lending, kecuali disebut lain)

Kondisi message (direkam bila bertanda ✓)
Batas laju 429 Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.
Validasi ✓ Data yang dikirim tidak lolos pemeriksaan. (code bukan 6 karakter)
Kata sandi salah 401 Nomor Karyawan atau kata sandi tidak sesuai.
Kode salah, tidak ada permintaan, atau perangkat berbeda ✓ Kode izin tidak sesuai atau sudah tidak berlaku.
Kode lewat expires_minutes ✓ Kode izin sudah kedaluwarsa. Mintalah kode baru.
Salah kode mencapai batas (bawaan 5) Kode salah terlalu banyak kali. Mintalah kode baru.
{
  "success": false,
  "message": "Kode izin tidak sesuai atau sudah tidak berlaku.",
  "errors": {
    "device_lending": [
      "Kode izin tidak sesuai atau sudah tidak berlaku."
    ]
  }
}

Status sesi pinjaman

GET /me/lending

Deskripsi: izin pinjam yang dipakai token saat ini. Dengan token login biasa, data bernilai null.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.me.lending

Contoh Request

GET /api/v1/me/lending HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, token sesi pinjaman, sesudah satu presensi masuk)

{
  "success": true,
  "message": "Anda sedang memakai izin presensi pada perangkat pinjaman.",
  "data": {
    "id": 1,
    "status": "ACTIVE",
    "status_label": "Sedang Berlaku",
    "device_name": "Xiaomi Redmi 13",
    "device_identifier": "0a9c71de-budi-redmi13",
    "platform": "ANDROID",
    "owner_name": "Budi Satu",
    "usage_count": 1,
    "max_usages": 2,
    "remaining_usages": 1,
    "requested_at": "2026-11-12T00:30:00+00:00",
    "verified_at": "2026-11-12T00:32:00+00:00",
    "expires_at": "2026-11-12T12:32:00+00:00",
    "ended_at": null,
    "end_reason": null,
    "is_usable": true
  }
}

Token login biasa:

{
  "success": true,
  "message": "Anda tidak sedang memakai perangkat pinjaman.",
  "data": {}
}

Akhiri sesi pinjaman

POST /auth/lend/end

Deskripsi: menghentikan izin pinjam milik token saat ini dan menghapus token sesi. Panggil saat karyawan selesai, sebelum mengembalikan ponsel.

Auth & Middleware
Token wajib (token sesi pinjaman)
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.auth.lend.end

Parameter: tidak ada.

Contoh Request

POST /api/v1/auth/lend/end HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Izin presensi pada perangkat pinjaman dihentikan.",
  "data": {}
}

Token yang sama sesudahnya:

{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}

Penolakan

Kondisi HTTP message
Token login biasa 422 ✓ Anda tidak sedang memakai perangkat pinjaman.
Token sesi sudah berakhir 401 ✓ Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.

Presensi dengan token sesi pinjaman

Check-in dan check-out memakai endpoint biasa di attendance.md. Setiap presensi yang diterima menambah usage_count. Saat jatah habis, status menjadi COMPLETED dan token dihapus.

Sesudah presensi pulang yang memakai jatah terakhir (2026-11-12 17:04 WIB), GET /me/lending dengan token yang sama:

{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}

Masa sesi 12 jam lewat sebelum jatah habis: presensi berikutnya ditolak DEVICE_LENDING_ENDED (2026-12-01 19:33 WIB), lalu token dihapus:

{
  "success": false,
  "message": "Izin presensi pada perangkat pinjaman sudah habis atau dihentikan. Mintalah kode izin baru.",
  "errors": {
    "attendance": [
      "Izin presensi pada perangkat pinjaman sudah habis atau dihentikan. Mintalah kode izin baru."
    ]
  }
}

Catatan

  • Token sesi pinjaman diterima seluruh endpoint bertoken, bukan hanya presensi. Tampilkan hanya layar presensi selama sesi pinjaman, dan jangan simpan token ini sebagai token login perangkat.
  • Idempotency: tidak ada kunci. Permintaan kode berulang menutup permintaan sebelumnya; hanya kode terakhir yang berlaku.
  • Rate limit: device-lending, 3 per menit per identifier + IP, untuk request dan verify. Request yang gagal ikut terhitung. Respons membawa X-RateLimit-Limit dan X-RateLimit-Remaining; 429 membawa Retry-After dan X-RateLimit-Reset.
  • FeatureGate / modul: tidak ada saklar paket. Pengaturan perusahaan policy.device_lending.enabled menentukan; bila false, permintaan kode dijawab 403.
  • Status langganan: request dan verify tidak memakai middleware langganan; GET /me/lending, POST /auth/lend/end, dan presensi dengan token sesi → 402 bila terkunci.