Presensi

Lihat Markdown

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_at dihitung resolver yang sama dengan pemeriksaan OUTSIDE_WINDOW, dan sama dengan GET /me/config → today.* pada saat yang sama. Pakai endpoint ini (bukan cache me/config) untuk menampilkan jendela; keputusan akhir tetap di server karena jam server yang dipakai, bukan jam perangkat.
  • can_check_in/can_check_out tidak memeriksa jam. Untuk menampilkan "belum dibuka/sudah ditutup", bandingkan jam server dengan check_in_opens_at/check_out_closes_at.
  • Shift malam: setelah tengah malam, work_date tetap 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. uuid wajib dibuat sekali per event dan disimpan bersama antrean offline. Kirim ulang dengan uuid yang sama dijawab 200 DUPLICATE beserta data asli, termasuk setelah lewat toleransi offline, karena pemeriksaan duplikat berjalan sebelum pemeriksaan waktu. Kirim ulang tetap membawa seluruh field dan photo, karena validasi FormRequest berjalan lebih dulu.
  • Jangan membuat uuid baru untuk event yang sama. Event kedua dianggap presensi baru dan ditolak Anda sudah melakukan presensi masuk untuk jadwal ini.
  • Antrean offline. Simpan captured_at saat tombol ditekan; isi device_time saat benar-benar mengirim. Event lebih tua dari policy.offline_sync_tolerance_hours ditolak 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. Tampilkan message dari server; geofence dihitung jarak - accuracy_meters <= radius_meters.
  • work_date ditentukan server. Presensi masuk Shift Malam pukul 22:52 dan pulang 07:04 keesokan harinya sama-sama tercatat pada work_date tanggal mulai shift.
  • Perangkat: token login biasa memakai perangkat APPROVED milik karyawan. Token sesi perangkat pinjaman memakai jatah policy.device_lending.max_usages; setelah sesi habis server menjawab DEVICE_LENDING_ENDED.
  • Rate limit: attendance, 12 per menit per karyawan, satu kuota bersama check-in, check-out, dan POST /client-visits/check-in. Request yang gagal validasi ikut terhitung. Respons membawa X-RateLimit-Limit: 12 dan X-RateLimit-Remaining; 429 membawa Retry-After (detik, mis. 60 pada request ke-13) dan X-RateLimit-Reset. Antrean offline menunggu sesuai Retry-After sebelum 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_at lewat, presensi pulang ditolak OUTSIDE_WINDOW dan rekap tetap INCOMPLETE. 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.