Status presensi hari ini, riwayat 31 hari, presensi masuk, dan presensi pulang dengan GPS dan selfie.
Konvensi umum (envelope, waktu UTC, idempotency, upload, rate limit) ada di README.md;
jadwal dan kebijakan presensi dibaca dari GET /me/config.
| Atribut | Nilai |
|---|---|
| Endpoint | GET /attendance/today, GET /attendance/history, POST /attendance/check-in, POST /attendance/check-out |
| Sumber kode | AttendanceController, StoreAttendanceRequest, AttendanceResource, AttendanceService, AttendanceScheduleResolver, GeofenceService, SuspectDetector |
| Contoh direkam | 2026-10-21, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan (nusantara-logistik WIB, borneo-retail WITA), APP_LOCALE=id seperti server. Jam server dipasang per skenario; setiap contoh mencantumkan waktunya |
| Data uji | Citra Satu: jam tetap 08:00–17:00 (toleransi terlambat 15 menit, jendela 06:30–19:00), lokasi Kantor Pusat Jakarta (radius 150 m) dan Gudang Cakung (radius 200 m). Budi Satu: Shift Malam 23:00–07:00 dari Jadwal Kerja |
Aturan dasar: client mengirim koordinat mentah, server yang memutuskan sah atau tidak. Jangan
mengirim field is_valid, company_id, work_date, atau status; field di luar tabel parameter
diabaikan.
Enum
AttendanceStatus (attendance.status)
| Nilai | status_label |
Kapan |
|---|---|---|
PRESENT |
Hadir | masuk dan pulang tercatat, late_minutes = 0 |
LATE |
Terlambat | masuk dan pulang tercatat, late_minutes > 0 |
INCOMPLETE |
Belum Presensi Pulang | baru presensi masuk (keterlambatan sudah terhitung di late_minutes) |
ABSENT |
Tanpa Keterangan | hari kerja lewat tanpa presensi masuk, ditandai sistem setiap jam |
LEAVE |
Cuti / Izin | cuti atau izin disetujui |
BUSINESS_TRIP |
Perjalanan Bisnis | hari perjalanan bisnis disetujui, termasuk bila karyawan presensi |
HOLIDAY |
Libur Nasional | nilai enum; client wajib dapat menampilkannya |
OFF_DUTY |
Libur | nilai enum; client wajib dapat menampilkannya |
OVERTIME |
Lembur Hari Libur | presensi pada hari libur dengan lembur hari libur disetujui; tidak dihitung Hadir, tanpa terlambat |
ScheduleStatus (schedule_status)
| Nilai | Presensi diterima | schedule_message |
|---|---|---|
ON_DUTY |
ya | Masuk kerja pada shift {nama shift}. / Lembur {Hari Libur Mingguan/Hari Libur Nasional} yang sudah disetujui. |
OFF_DUTY |
tidak | Tidak dijadwalkan masuk pada tanggal ini. |
HOLIDAY |
tidak | Libur: {nama libur}. (dari kalender libur atau catatan Jadwal Kerja) |
NOT_SCHEDULED |
tidak | Karyawan tidak mengikuti presensi harian. |
NO_SHIFT_PATTERN |
tidak | Karyawan belum memiliki pola shift. Hubungi Admin HR. |
INCOMPLETE_PATTERN |
tidak | Pola {nama pola} pada hari {hari} belum diisi jam kerja. |
OvertimeType (overtime_type)
| Nilai | Label |
|---|---|
REST_DAY |
Hari Libur Mingguan |
HOLIDAY |
Hari Libur Nasional |
BEFORE_SHIFT dan AFTER_SHIFT ada di modul lembur, tetapi tidak pernah muncul di overtime_type
presensi.
code respons presensi
| Nilai | HTTP | Arti |
|---|---|---|
ACCEPTED |
201 | presensi baru tercatat |
DUPLICATE |
200 | uuid sudah pernah diterima; data asli dikembalikan, tidak ada data ganda |
Penolakan tidak membawa code; lihat tabel penolakan di bagian check-in.
Objek attendance
Dipakai GET /attendance/today (data.attendance), GET /attendance/history (data[]), dan respons
check-in/check-out (data.attendance). Sumber: AttendanceResource.
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | ID rekap presensi harian |
work_date |
string (YYYY-MM-DD) |
tidak | tanggal kerja = tanggal mulai shift. Shift malam Selasa 22:52 → pulang Rabu 07:04 tetap work_date Selasa |
status |
string (enum) | tidak | AttendanceStatus |
status_label |
string | tidak | label tampilan |
check_in_at |
string (ISO 8601 UTC) | ya | waktu masuk = captured_at presensi masuk |
check_out_at |
string (ISO 8601 UTC) | ya | waktu pulang = captured_at presensi pulang |
late_minutes |
integer | tidak | menit terlambat dihitung dari jam mulai shift begitu melewati toleransi shift. Masuk 08:27 dengan toleransi 15 menit → 27. Masuk 08:14 → 0 |
early_leave_minutes |
integer | tidak | menit pulang lebih cepat dari jam selesai shift (setelah toleransi pulang cepat shift) |
work_minutes |
integer | tidak | menit antara masuk dan pulang; 0 sebelum pulang |
shift |
string | ya | nama shift; null pada lembur hari libur |
work_location |
string | ya | nama lokasi kerja presensi masuk (bila kosong, lokasi presensi pulang); null bila tanpa lokasi (mis. REMOTE, perjalanan bisnis) |
Presensi hari ini
GET /attendance/today
Deskripsi: jadwal kerja yang berlaku saat ini, tombol mana yang boleh aktif, dan rekap presensinya. Dipanggil saat membuka layar presensi dan setelah setiap check-in/check-out.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.attendance.today |
Header: Accept: application/json, Authorization: Bearer <token>
Parameter: tidak ada. Hari dan jadwal ditentukan dari jam server.
Contoh Request
GET /api/v1/attendance/today HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-10-21 07:40 WIB, belum presensi)
{
"success": true,
"message": "Presensi hari ini berhasil diambil.",
"data": {
"work_date": "2026-10-21",
"schedule_status": "ON_DUTY",
"schedule_message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": true,
"can_check_out": false,
"check_in_opens_at": "2026-10-20T23:30:00+00:00",
"check_out_closes_at": "2026-10-21T12:00:00+00:00",
"attendance": null
}
}
Setelah presensi masuk (08:05 WIB):
{
"success": true,
"message": "Presensi hari ini berhasil diambil.",
"data": {
"work_date": "2026-10-21",
"schedule_status": "ON_DUTY",
"schedule_message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": false,
"can_check_out": true,
"check_in_opens_at": "2026-10-20T23:30:00+00:00",
"check_out_closes_at": "2026-10-21T12:00:00+00:00",
"attendance": {
"id": 6,
"work_date": "2026-10-21",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-21T00:52:01+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
}
Variasi yang direkam (isi data saja):
Shift malam, dibuka Kamis 2026-10-22 07:10 WIB setelah pulang. work_date tetap Rabu:
{
"work_date": "2026-10-21",
"schedule_status": "ON_DUTY",
"schedule_message": "Masuk kerja pada shift Shift Malam 23:00 - 07:00.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": false,
"can_check_out": false,
"check_in_opens_at": "2026-10-21T15:00:00+00:00",
"check_out_closes_at": "2026-10-22T02:00:00+00:00",
"attendance": {
"id": 7,
"work_date": "2026-10-21",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-21T15:52:26+00:00",
"check_out_at": "2026-10-22T00:04:47+00:00",
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 492,
"shift": "Shift Malam 23:00 - 07:00",
"work_location": "Kantor Pusat Jakarta"
}
}
Sabtu 2026-10-24 08:40 WIB dengan lembur Hari Libur Mingguan 09:00–13:00 yang disetujui:
{
"work_date": "2026-10-24",
"schedule_status": "ON_DUTY",
"schedule_message": "Lembur Hari Libur Mingguan yang sudah disetujui.",
"is_overtime": true,
"overtime_type": "REST_DAY",
"can_check_in": true,
"can_check_out": false,
"check_in_opens_at": "2026-10-24T01:30:00+00:00",
"check_out_closes_at": "2026-10-24T06:30:00+00:00",
"attendance": null
}
Jumat 2026-10-23, Jadwal Kerja berstatus libur dengan catatan:
{
"work_date": "2026-10-23",
"schedule_status": "HOLIDAY",
"schedule_message": "Libur: Hari Ulang Tahun Perusahaan.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": false,
"can_check_out": false,
"check_in_opens_at": null,
"check_out_closes_at": null,
"attendance": null
}
Minggu 2026-10-25 tanpa lembur:
{
"work_date": "2026-10-25",
"schedule_status": "OFF_DUTY",
"schedule_message": "Tidak dijadwalkan masuk pada tanggal ini.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": false,
"can_check_out": false,
"check_in_opens_at": null,
"check_out_closes_at": null,
"attendance": null
}
Kamis 2026-10-22 05:30 WIB, sebelum jendela dibuka. can_check_in tetap true, tetapi
check_in_opens_at menunjukkan 06:30 WIB (23:30Z) dan check-in pada jam ini ditolak (lihat penolakan
OUTSIDE_WINDOW):
{
"work_date": "2026-10-22",
"schedule_status": "ON_DUTY",
"schedule_message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": true,
"can_check_out": false,
"check_in_opens_at": "2026-10-21T23:30:00+00:00",
"check_out_closes_at": "2026-10-22T12:00:00+00:00",
"attendance": null
}
Rabu 2026-10-21 03:05 WIB, jam tetap 08:00–17:00 dengan lembur AFTER_SHIFT 17:00–20:00 yang disetujui
(180 menit + kelonggaran 30 menit). Jendela diperlebar ke kedua arah menjadi 03:00–22:30 WIB; check-in
02:55 dan check-out 22:35 ditolak Presensi hanya dapat dilakukan antara 21 Okt 03:00 sampai 21 Okt 22:30 WIB., check-in 03:05 dan check-out 22:25 diterima:
{
"work_date": "2026-10-21",
"schedule_status": "ON_DUTY",
"schedule_message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
"is_overtime": false,
"overtime_type": null,
"can_check_in": true,
"can_check_out": false,
"check_in_opens_at": "2026-10-20T20:00:00+00:00",
"check_out_closes_at": "2026-10-21T15:30:00+00:00",
"attendance": null
}
Field data
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
work_date |
string (YYYY-MM-DD) |
tidak | tanggal kerja yang berlaku saat ini (tanggal mulai shift) |
schedule_status |
string (enum) | tidak | ScheduleStatus |
schedule_message |
string | tidak | kalimat siap tampil |
is_overtime |
boolean | tidak | true pada lembur hari libur yang disetujui |
overtime_type |
string (enum) | ya | REST_DAY / HOLIDAY bila is_overtime, selain itu null |
can_check_in |
boolean | tidak | schedule_status = ON_DUTY dan belum presensi masuk. Tidak memeriksa jam |
can_check_out |
boolean | tidak | schedule_status = ON_DUTY, sudah masuk, belum pulang. Tidak memeriksa jam |
check_in_opens_at |
string (ISO 8601 UTC) | ya | awal jendela presensi work_date ini, sama persis dengan batas yang ditegakkan check-in/check-out (OUTSIDE_WINDOW): jam mulai shift dikurangi jendela buka shift, diperlebar kelonggaran perjalanan bisnis atau lembur BEFORE_SHIFT/AFTER_SHIFT yang disetujui (yang terbesar). Pada lembur hari libur: jam mulai lembur dikurangi kelonggaran lembur. null bila tidak ada jadwal masuk |
check_out_closes_at |
string (ISO 8601 UTC) | ya | akhir jendela presensi, aturan sama dengan check_in_opens_at. null bila tidak ada jadwal masuk |
attendance |
objek | ya | objek attendance; null bila belum ada rekap untuk work_date |
Contoh Response Error
| Kondisi | HTTP | message |
|---|---|---|
| Token tidak sah | 401 | Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali. |
| Langganan terkunci | 402 | Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan. |
{
"success": false,
"message": "Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.",
"errors": {}
}
Catatan
- Jendela jam:
check_in_opens_at/check_out_closes_atdihitung resolver yang sama dengan pemeriksaanOUTSIDE_WINDOW, dan sama denganGET /me/config→today.*pada saat yang sama. Pakai endpoint ini (bukan cacheme/config) untuk menampilkan jendela; keputusan akhir tetap di server karena jam server yang dipakai, bukan jam perangkat. can_check_in/can_check_outtidak memeriksa jam. Untuk menampilkan "belum dibuka/sudah ditutup", bandingkan jam server dengancheck_in_opens_at/check_out_closes_at.- Shift malam: setelah tengah malam,
work_datetetap tanggal mulai shift selama jendela presensinya masih terbuka, sehingga tombol pulang tetap mengarah ke shift yang benar. - Idempotency: tidak relevan (GET).
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada (presensi adalah modul inti).
- Status langganan: terkunci → 402.
Riwayat presensi
GET /attendance/history
Deskripsi: rekap presensi harian 31 hari terakhir (hari ini menurut kalender perusahaan dan 30 hari
sebelumnya), urut work_date terbaru di atas.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.attendance.history |
Header: Accept: application/json, Authorization: Bearer <token>
Parameter: tidak ada. Rentang tanggal tetap; tidak ada pagination maupun filter.
Contoh Request
GET /api/v1/attendance/history HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-10-21 17:07 WIB)
{
"success": true,
"message": "Riwayat presensi berhasil diambil.",
"data": [
{
"id": 6,
"work_date": "2026-10-21",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-21T00:52:01+00:00",
"check_out_at": "2026-10-21T10:06:09+00:00",
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 554,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
},
{
"id": 5,
"work_date": "2026-10-20",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-20T00:51:00+00:00",
"check_out_at": "2026-10-20T09:32:15+00:00",
"late_minutes": 0,
"early_leave_minutes": 27,
"work_minutes": 521,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Gudang Cakung"
},
{
"id": 4,
"work_date": "2026-10-19",
"status": "LATE",
"status_label": "Terlambat",
"check_in_at": "2026-10-19T01:27:10+00:00",
"check_out_at": "2026-10-19T10:08:35+00:00",
"late_minutes": 27,
"early_leave_minutes": 0,
"work_minutes": 521,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
]
}
Karyawan perusahaan lain (borneo-retail) pada saat yang sama menerima "data": [], walaupun
nusantara-logistik sudah punya 9 rekap presensi.
Field data[]: objek attendance. Array kosong [] bila belum ada rekap.
Contoh Response Error
| Kondisi | HTTP | message |
|---|---|---|
| Token tidak sah | 401 | Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali. |
| Langganan terkunci | 402 | Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. ... |
{
"success": false,
"message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
"errors": {}
}
Catatan
- Riwayat memuat baris yang dibuat sistem, bukan hanya hasil tap:
ABSENT(hari kerja tanpa presensi),LEAVE(cuti disetujui),BUSINESS_TRIP. Tanggal tanpa rekap sama sekali tidak muncul. - Rekap dapat berubah setelah dikirim: koreksi presensi yang disetujui, hitung ulang malam hari, atau perubahan aturan perusahaan. Jangan anggap riwayat lokal sebagai sumber kebenaran.
- Idempotency: tidak relevan (GET).
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: terkunci → 402.
Presensi masuk
POST /attendance/check-in
Deskripsi: mengirim satu event presensi masuk berisi koordinat mentah, akurasi, waktu perekaman, dan selfie. Server menentukan jadwal, memeriksa jendela waktu, urutan, geofence, dan menandai kecurigaan, lalu menyimpan log mentah dan menghitung rekap harian.
| Auth & Middleware | |
|---|---|
| Token | wajib (token login biasa atau token sesi perangkat pinjaman) |
| Middleware | auth:sanctum, EnsureSubscriptionActive, throttle:attendance |
| Route name | api.v1.attendance.check-in |
Header: Accept: application/json, Authorization: Bearer <token>,
Content-Type: multipart/form-data
Parameter (StoreAttendanceRequest, sama untuk check-out)
| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
uuid |
body (part teks) | string (UUID) | ya | required, uuid. Dibuat client sekali per event dan dipakai ulang saat kirim ulang |
latitude |
body (part teks) | number | ya | required, numeric, between:-90,90. Lintang mentah dari GPS, desimal titik |
longitude |
body (part teks) | number | ya | required, numeric, between:-180,180 |
accuracy_meters |
body (part teks) | number | ya | required, numeric, min:0, max:10000. Akurasi horizontal GPS dalam meter |
captured_at |
body (part teks) | string (ISO 8601) | ya | required, date. Waktu tombol ditekan, wajib dengan offset (2026-10-21T07:52:01+07:00); tanpa offset dibaca UTC |
device_time |
body (part teks) | string (ISO 8601) | tidak | nullable, date. Jam perangkat saat request dikirim. Selisih lebih dari 10 menit dari jam server menandai is_suspect |
mock_location |
body (part teks) | boolean | tidak | nullable, boolean. Kirim 1 atau 0; teks true/false ditolak pada multipart. Kosong dianggap 0 |
app_version |
body (part teks) | string | tidak | nullable, string, max:50. Disimpan pada log presensi |
photo |
body (part berkas) | berkas gambar | bila policy.photo_required |
required atau nullable mengikuti policy.photo_required, image (jpg, jpeg, png, bmp, gif, webp), max:{policy.photo_max_kilobytes} KB (bawaan 300) |
Contoh Request (2026-10-21 07:52 WIB)
POST /api/v1/attendance/check-in HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova
--absenova
Content-Disposition: form-data; name="uuid"
3f6c9b2e-8d41-4a7f-b5e2-21c1f0a10001
--absenova
Content-Disposition: form-data; name="latitude"
-6.2087958
--absenova
Content-Disposition: form-data; name="longitude"
106.8455327
--absenova
Content-Disposition: form-data; name="accuracy_meters"
12.5
--absenova
Content-Disposition: form-data; name="captured_at"
2026-10-21T07:52:01+07:00
--absenova
Content-Disposition: form-data; name="device_time"
2026-10-21T07:52:01+07:00
--absenova
Content-Disposition: form-data; name="mock_location"
0
--absenova
Content-Disposition: form-data; name="app_version"
1.0.1
--absenova
Content-Disposition: form-data; name="photo"; filename="selfie.jpg"
Content-Type: image/jpeg
(berkas JPEG 480×640, 118 KB)
--absenova--
Retrofit: @Multipart dengan @Part("uuid") RequestBody untuk setiap field teks dan
@Part photo: MultipartBody.Part untuk berkas.
Contoh Response Sukses (201)
{
"success": true,
"message": "Presensi masuk tercatat tepat waktu.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 6,
"work_date": "2026-10-21",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-21T00:52:01+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
}
Kirim ulang dengan uuid yang sama 36 detik kemudian (200, tidak ada data ganda):
{
"success": true,
"message": "Presensi ini sudah tercatat sebelumnya. Tidak ada data ganda yang dibuat.",
"data": {
"code": "DUPLICATE",
"is_suspect": false,
"attendance": {
"id": 6,
"work_date": "2026-10-21",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-21T00:52:01+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
}
Variasi sukses yang direkam (isi message dan data saja):
Terlambat, Senin 2026-10-19 08:27 WIB (captured_at: 2026-10-19T08:27:10+07:00):
"message": "Presensi masuk tercatat. Anda terlambat 27 menit.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 4,
"work_date": "2026-10-19",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-19T01:27:10+00:00",
"check_out_at": null,
"late_minutes": 27,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
Shift malam dengan mock_location: 1, Rabu 2026-10-21 22:52 WIB. Diterima, tetapi ditandai
is_suspect:
"message": "Presensi masuk tercatat tepat waktu.",
"data": {
"code": "ACCEPTED",
"is_suspect": true,
"attendance": {
"id": 7,
"work_date": "2026-10-21",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-21T15:52:26+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Shift Malam 23:00 - 07:00",
"work_location": "Kantor Pusat Jakarta"
}
}
Antrean offline: direkam 07:55 (captured_at: 2026-10-22T07:55:12+07:00), terkirim 09:30
(device_time: 2026-10-22T09:30:18+07:00). Diterima dengan jam masuk 07:55, ditandai is_suspect
karena terkirim lebih dari 60 menit setelah direkam:
"message": "Presensi masuk tercatat tepat waktu.",
"data": {
"code": "ACCEPTED",
"is_suspect": true,
"attendance": {
"id": 8,
"work_date": "2026-10-22",
"status": "INCOMPLETE",
"status_label": "Belum Presensi Pulang",
"check_in_at": "2026-10-22T00:55:12+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
Lembur hari libur, Sabtu 2026-10-24 08:52 WIB, di Gudang Cakung:
"message": "Presensi masuk tercatat tepat waktu.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 9,
"work_date": "2026-10-24",
"status": "OVERTIME",
"status_label": "Lembur Hari Libur",
"check_in_at": "2026-10-24T01:52:27+00:00",
"check_out_at": null,
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 0,
"shift": null,
"work_location": "Gudang Cakung"
}
}
Field data
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
code |
string (enum) | tidak | ACCEPTED (201) atau DUPLICATE (200) |
is_suspect |
boolean | tidak | true bila server menandai kecurigaan (tabel di bawah). Presensi tetap tercatat; tinjauan oleh Admin HR. Alasan tidak dikirim |
attendance |
objek | ya | objek attendance untuk work_date presensi ini. Pada DUPLICATE bernilai null bila rekapnya sudah tidak ada |
Penanda is_suspect (presensi tetap diterima)
| Pemicu | Kondisi |
|---|---|
| Lokasi palsu | mock_location = 1 |
| Akurasi nol | accuracy_meters = 0 |
| Jam perangkat menyimpang | selisih device_time dengan jam server lebih dari 10 menit |
| Terlambat terkirim | captured_at lebih dari 60 menit sebelum jam server |
| Koordinat kembar | latitude/longitude sama persis dengan presensi sebelumnya |
| Perpindahan mustahil | kecepatan dari presensi sebelumnya melebihi 200 km/jam (pengaturan perusahaan) |
| Jauh dari tujuan perjalanan bisnis | di luar radius tujuan pada hari perjalanan bisnis |
Penolakan dan urutan pemeriksaan
Server memeriksa berurutan dan berhenti pada penolakan pertama. Seluruh penolakan aturan bisnis
dijawab 422 dengan errors.attendance. Kode internal tidak dikirim ke client.
| # | Kode internal | HTTP | message (direkam bila bertanda ✓) |
|---|---|---|---|
| 1 | — | 401 | ✓ Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali. |
| 2 | — | 429 | ✓ Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi. |
| 3 | — | 402 | ✓ Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan. |
| 4 | — | 422 | ✓ Data yang dikirim tidak lolos pemeriksaan. (validasi FormRequest, errors per field) |
| 5 | DEVICE_LENDING_ENDED |
422 | ✓ Izin presensi pada perangkat pinjaman sudah habis atau dihentikan. Mintalah kode izin baru. |
| 6 | DUPLICATE |
200 | ✓ bukan penolakan; lihat contoh kirim ulang |
| 7 | FUTURE_CAPTURE |
422 | ✓ Waktu perekaman berada di masa depan. Periksa pengaturan jam pada perangkat Anda. (captured_at lebih dari 5 menit di depan jam server) |
| 8 | SYNC_WINDOW_EXPIRED |
422 | ✓ Data presensi ini lebih lama dari 24 jam sehingga tidak dapat diterima. Ajukan koreksi presensi kepada atasan Anda. (angka mengikuti policy.offline_sync_tolerance_hours) |
| 9 | NOT_ON_DUTY |
422 | ✓ schedule_message hari itu, mis. Tidak dijadwalkan masuk pada tanggal ini. atau Libur: Hari Ulang Tahun Perusahaan. |
| 10 | OUTSIDE_WINDOW |
422 | ✓ Presensi hanya dapat dilakukan antara 22 Okt 06:30 sampai 22 Okt 19:00 WIB. (jam dan singkatan zona mengikuti perusahaan: WIB, WITA, WIT) |
| 11 | ALREADY_CHECKED_IN |
422 | ✓ Anda sudah melakukan presensi masuk untuk jadwal ini. |
| 12 | PHOTO_REQUIRED |
422 | Foto wajib disertakan pada setiap presensi masuk dan pulang. (praktis tertangkap validasi nomor 4) |
| 13 | GEOFENCE_ACCURACY_TOO_LOW |
422 | ✓ Akurasi GPS 85 meter melebihi ambang 50 meter. Pastikan berada di ruang terbuka lalu ulangi. |
| 14 | GEOFENCE_NO_ASSIGNED_LOCATION |
422 | ✓ Karyawan belum ditugaskan pada lokasi presensi mana pun. Hubungi Admin HR. |
| 15 | GEOFENCE_OUTSIDE_RADIUS |
422 | ✓ Lokasi terdekat Kantor Pusat Jakarta berjarak 4234 meter, melebihi radius 150 meter. |
Nomor 13 berlaku untuk semua pola kerja, termasuk REMOTE. Nomor 14 dan 15 dilewati untuk pola
REMOTE dan pada hari perjalanan bisnis.
Validasi (multipart, uuid dan longitude kosong, captured_at: "kemarin", mock_location: "true",
photo berupa PDF):
{
"success": false,
"message": "Data yang dikirim tidak lolos pemeriksaan.",
"errors": {
"uuid": [
"Kolom pengenal presensi wajib diisi."
],
"longitude": [
"Kolom bujur wajib diisi."
],
"captured_at": [
"Kolom waktu perekaman bukan tanggal yang sah."
],
"mock_location": [
"Kolom mock location harus bernilai benar atau salah."
],
"photo": [
"Kolom foto presensi harus berupa gambar."
]
}
}
Tanpa photo saat policy.photo_required bernilai true, errors.photo berisi
Kolom foto presensi wajib diisi.
Penolakan aturan bisnis (di luar radius, latitude: -6.1753924, longitude: 106.8271528):
{
"success": false,
"message": "Lokasi terdekat Kantor Pusat Jakarta berjarak 4234 meter, melebihi radius 150 meter.",
"errors": {
"attendance": [
"Lokasi terdekat Kantor Pusat Jakarta berjarak 4234 meter, melebihi radius 150 meter."
]
}
}
Di luar jendela (Kamis 05:30 WIB, jadwal 08:00–17:00):
{
"success": false,
"message": "Presensi hanya dapat dilakukan antara 22 Okt 06:30 sampai 22 Okt 19:00 WIB.",
"errors": {
"attendance": [
"Presensi hanya dapat dilakukan antara 22 Okt 06:30 sampai 22 Okt 19:00 WIB."
]
}
}
Langganan terkunci dan batas laju tidak membawa rincian:
{
"success": false,
"message": "Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.",
"errors": {}
}
Catatan
- Idempotency.
uuidwajib dibuat sekali per event dan disimpan bersama antrean offline. Kirim ulang denganuuidyang sama dijawab200 DUPLICATEbeserta data asli, termasuk setelah lewat toleransi offline, karena pemeriksaan duplikat berjalan sebelum pemeriksaan waktu. Kirim ulang tetap membawa seluruh field danphoto, karena validasi FormRequest berjalan lebih dulu. - Jangan membuat
uuidbaru untuk event yang sama. Event kedua dianggap presensi baru dan ditolakAnda sudah melakukan presensi masuk untuk jadwal ini. - Antrean offline. Simpan
captured_atsaat tombol ditekan; isidevice_timesaat benar-benar mengirim. Event lebih tua daripolicy.offline_sync_tolerance_hoursditolak permanen; arahkan karyawan ke koreksi presensi dan hapus dari antrean. Penolakan 422 lain juga permanen; hanya kegagalan jaringan, 429, dan 5xx yang layak dicoba ulang. - Jangan memblokir di client berdasarkan jarak, jam, atau
can_check_in. Tampilkanmessagedari server; geofence dihitungjarak - accuracy_meters <= radius_meters. work_dateditentukan server. Presensi masuk Shift Malam pukul 22:52 dan pulang 07:04 keesokan harinya sama-sama tercatat padawork_datetanggal mulai shift.- Perangkat: token login biasa memakai perangkat
APPROVEDmilik karyawan. Token sesi perangkat pinjaman memakai jatahpolicy.device_lending.max_usages; setelah sesi habis server menjawabDEVICE_LENDING_ENDED. - Rate limit:
attendance, 12 per menit per karyawan, satu kuota bersama check-in, check-out, danPOST /client-visits/check-in. Request yang gagal validasi ikut terhitung. Respons membawaX-RateLimit-Limit: 12danX-RateLimit-Remaining; 429 membawaRetry-After(detik, mis.60pada request ke-13) danX-RateLimit-Reset. Antrean offline menunggu sesuaiRetry-Aftersebelum kirim ulang. - FeatureGate / modul: tidak ada (modul inti).
- Status langganan: terkunci → 402, termasuk presensi.
Presensi pulang
POST /attendance/check-out
Deskripsi: mengirim satu event presensi pulang. Aturan, validasi, idempotency, dan penanda kecurigaan sama dengan presensi masuk; bedanya presensi masuk untuk jadwal yang sama wajib sudah tercatat.
| Auth & Middleware | |
|---|---|
| Token | wajib (token login biasa atau token sesi perangkat pinjaman) |
| Middleware | auth:sanctum, EnsureSubscriptionActive, throttle:attendance |
| Route name | api.v1.attendance.check-out |
Header: Accept: application/json, Authorization: Bearer <token>,
Content-Type: multipart/form-data
Parameter: sama persis dengan presensi masuk (StoreAttendanceRequest):
uuid, latitude, longitude, accuracy_meters, captured_at, device_time, mock_location,
app_version, photo. uuid wajib berbeda dari uuid presensi masuk.
Contoh Request (2026-10-21 17:06 WIB, part teks; photo seperti presensi masuk)
POST /api/v1/attendance/check-out HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova
--absenova
Content-Disposition: form-data; name="uuid"
3f6c9b2e-8d41-4a7f-b5e2-21c1f0a10002
--absenova
Content-Disposition: form-data; name="latitude"
-6.208712
--absenova
Content-Disposition: form-data; name="longitude"
106.8456033
--absenova
Content-Disposition: form-data; name="accuracy_meters"
9.5
--absenova
Content-Disposition: form-data; name="captured_at"
2026-10-21T17:06:09+07:00
--absenova
Content-Disposition: form-data; name="device_time"
2026-10-21T17:06:09+07:00
--absenova
Content-Disposition: form-data; name="mock_location"
0
--absenova
Content-Disposition: form-data; name="app_version"
1.0.1
--absenova
Content-Disposition: form-data; name="photo"; filename="selfie.jpg"
Content-Type: image/jpeg
(berkas JPEG 480×640, 118 KB)
--absenova--
Contoh Response Sukses (201)
{
"success": true,
"message": "Presensi pulang tercatat.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 6,
"work_date": "2026-10-21",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-21T00:52:01+00:00",
"check_out_at": "2026-10-21T10:06:09+00:00",
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 554,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Kantor Pusat Jakarta"
}
}
}
Variasi yang direkam (isi message dan data saja):
Pulang lebih cepat, Selasa 2026-10-20 16:32 WIB:
"message": "Presensi pulang tercatat. Anda pulang 27 menit lebih cepat.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 5,
"work_date": "2026-10-20",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-20T00:51:00+00:00",
"check_out_at": "2026-10-20T09:32:15+00:00",
"late_minutes": 0,
"early_leave_minutes": 27,
"work_minutes": 521,
"shift": "Jam Kantor 08:00 - 17:00",
"work_location": "Gudang Cakung"
}
}
Pulang shift malam, Kamis 2026-10-22 07:04 WIB. work_date tetap Rabu, tanggal mulai shift:
"message": "Presensi pulang tercatat.",
"data": {
"code": "ACCEPTED",
"is_suspect": false,
"attendance": {
"id": 7,
"work_date": "2026-10-21",
"status": "PRESENT",
"status_label": "Hadir",
"check_in_at": "2026-10-21T15:52:26+00:00",
"check_out_at": "2026-10-22T00:04:47+00:00",
"late_minutes": 0,
"early_leave_minutes": 0,
"work_minutes": 492,
"shift": "Shift Malam 23:00 - 07:00",
"work_location": "Kantor Pusat Jakarta"
}
}
Field data: sama dengan presensi masuk. Setelah pulang, status menjadi
PRESENT atau LATE (atau tetap OVERTIME / BUSINESS_TRIP).
Contoh Response Error
Seluruh penolakan presensi masuk berlaku, kecuali nomor 11 diganti dua penolakan berikut:
| Kode internal | HTTP | message |
|---|---|---|
NO_CHECK_IN |
422 | Presensi pulang tidak dapat dilakukan karena presensi masuk belum tercatat. |
ALREADY_CHECKED_OUT |
422 | Anda sudah melakukan presensi pulang untuk jadwal ini. |
{
"success": false,
"message": "Presensi pulang tidak dapat dilakukan karena presensi masuk belum tercatat.",
"errors": {
"attendance": [
"Presensi pulang tidak dapat dilakukan karena presensi masuk belum tercatat."
]
}
}
{
"success": false,
"message": "Anda sudah melakukan presensi pulang untuk jadwal ini.",
"errors": {
"attendance": [
"Anda sudah melakukan presensi pulang untuk jadwal ini."
]
}
}
Catatan
- Lupa presensi pulang: setelah jendela
check_out_closes_atlewat, presensi pulang ditolakOUTSIDE_WINDOWdan rekap tetapINCOMPLETE. Karyawan mengajukan koreksi presensi. - Koordinat pulang yang sama persis dengan koordinat masuk menandai
is_suspect; kirim nilai GPS apa adanya, jangan memakai ulang koordinat tersimpan. - Idempotency:
uuid, sama dengan presensi masuk. - Rate limit:
attendance, kuota bersama 12 per menit per karyawan. - FeatureGate / modul: tidak ada.
- Status langganan: terkunci → 402.