# Presensi

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](README.md);
jadwal dan kebijakan presensi dibaca dari [`GET /me/config`](me.md#konfigurasi-aplikasi).

| 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**

```http
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)

```json
{
  "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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`):

```json
{
  "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:

```json
{
  "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`](#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.` |

```json
{
  "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**

```http
GET /api/v1/attendance/history HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, 2026-10-21 17:07 WIB)

```json
{
  "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`](#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. ...` |

```json
{
  "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)

```http
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`)

```json
{
  "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):

```json
{
  "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`):

```json
"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`:

```json
"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:

```json
"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:

```json
"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`](#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):

```json
{
  "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`):

```json
{
  "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):

```json
{
  "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:

```json
{
  "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](#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)

```http
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`)

```json
{
  "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:

```json
"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:

```json
"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](#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.` |

```json
{
  "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."
    ]
  }
}
```

```json
{
  "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.
