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:
POST /auth/lend/request(tanpa token) → kode dikirim ke surel karyawan.POST /auth/lend/verify(tanpa token) →tokensesi pinjaman + data karyawan + status izin.- Presensi memakai token sesi pinjaman (
POST /attendance/check-in,/check-out); setiap presensi yang diterima memakai satu jatah. - 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 peridentifier+ IP, untukrequestdanverify. Request yang gagal ikut terhitung. Respons membawaX-RateLimit-LimitdanX-RateLimit-Remaining; 429 membawaRetry-AfterdanX-RateLimit-Reset. - FeatureGate / modul: tidak ada saklar paket. Pengaturan perusahaan
policy.device_lending.enabledmenentukan; bilafalse, permintaan kode dijawab 403. - Status langganan:
requestdanverifytidak memakai middleware langganan;GET /me/lending,POST /auth/lend/end, dan presensi dengan token sesi → 402 bila terkunci.