# Cuti dan Izin

Jenis cuti yang tersedia bagi karyawan, saldo cuti, riwayat, detail, pengajuan, dan pembatalan cuti.
Izin dan sakit memakai modul yang sama sebagai jenis cuti tersendiri. Konvensi umum ada di
[README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /leave-types`, `GET /me/leave-balances`, `GET /leaves`, `POST /leaves`, `GET /leaves/{leave}`, `POST /leaves/{leave}/cancel` |
| Sumber kode | `LeaveTypeController`, `LeaveBalanceController`, `LeaveController`, `StoreLeaveRequest`, `LeaveTypeResource`, `LeaveBalanceResource`, `LeaveResource`, `LeaveService`, `LeaveBalanceService`, `LeaveCalculator` |
| Contoh direkam | 2026-10-22, direkam ulang 2026-10-23 setelah perubahan alur persetujuan, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, `APP_LOCALE=id`. Jam server dipasang per skenario |
| Data uji | Citra Satu (status kepegawaian Alih Daya): jam tetap Senin–Jumat, saldo Cuti Tahunan 2026 = 12 hari. Jenis cuti bawaan perusahaan baru. Alur persetujuan Citra: Tahap 1 Anton Satu (atasan langsung) → Tahap 2 Budi Satu (Kepala Departemen unit Anton, karena Anton tanpa atasan langsung) |

---

## Enum

### `LeaveCategory` (`category`)

| Nilai | `category_label` |
|---|---|
| `ANNUAL` | Cuti Tahunan |
| `BIG` | Cuti Besar |
| `SICK` | Cuti Sakit |
| `MATERNITY` | Cuti Melahirkan |
| `IMPORTANT_REASON` | Cuti Karena Alasan Penting |
| `UNPAID` | Cuti di Luar Tanggungan Negara |
| `PERMISSION` | Izin |

Nama jenis cuti (`name`) diatur perusahaan dan boleh berbeda dari `category_label`. Tampilkan `name`.

### `ApprovalStatus` (`status`)

| Nilai | `status_label` | Dapat dibatalkan karyawan |
|---|---|---|
| `PENDING` | Menunggu Persetujuan | ya |
| `APPROVED` | Disetujui | ya, **hanya bila** `start_date` masih setelah hari ini (zona perusahaan) |
| `REJECTED` | Ditolak | tidak |
| `CANCELLED` | Dibatalkan | tidak |

### `ScheduleStatus` (`days[].schedule_status`)

Sama dengan `ScheduleStatus` di [attendance.md](attendance.md#schedulestatus-schedule_status). Hari
`ON_DUTY` dihitung (`is_counted: true`); hari libur di dalam rentang tidak dihitung.

---

## Jenis cuti

**`GET /leave-types`**

Deskripsi: jenis cuti aktif yang **berlaku untuk karyawan login**. Jenis yang dibatasi status
kepegawaian atau jenis kelamin tertentu tidak muncul bagi karyawan lain. Urut `sort_order` lalu nama,
tanpa batas jumlah.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.leave-types.index` |

**Parameter:** tidak ada.

**Contoh Request**

```http
GET /api/v1/leave-types HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`). Karyawan Alih Daya tidak melihat Cuti Karena Alasan Penting dan
Cuti Tanpa Gaji yang dibatasi status kepegawaian:

```json
{
  "success": true,
  "message": "Daftar jenis cuti berhasil diambil.",
  "data": [
    {
      "id": 1,
      "code": "CT",
      "name": "Cuti Tahunan",
      "category": "ANNUAL",
      "category_label": "Cuti Tahunan",
      "affects_balance": true,
      "requires_attachment": false,
      "max_consecutive_days": null,
      "min_advance_days": 3,
      "allows_backdate": false,
      "is_paid": true,
      "description": "Hak minimal 12 hari kerja per tahun setelah 12 bulan bekerja, sesuai UU 13/2003 Pasal 79 jo. UU 6/2023. Kuota per karyawan dapat disesuaikan Admin HR pada menu Saldo Cuti."
    },
    {
      "id": 2,
      "code": "CS",
      "name": "Cuti Sakit",
      "category": "SICK",
      "category_label": "Cuti Sakit",
      "affects_balance": false,
      "requires_attachment": true,
      "max_consecutive_days": 14,
      "min_advance_days": 0,
      "allows_backdate": true,
      "is_paid": true,
      "description": "Wajib melampirkan surat keterangan dokter. Sakit lebih dari 14 hari kerja diajukan sebagai pengajuan terpisah."
    },
    {
      "id": 3,
      "code": "CM",
      "name": "Cuti Melahirkan",
      "category": "MATERNITY",
      "category_label": "Cuti Melahirkan",
      "affects_balance": false,
      "requires_attachment": true,
      "max_consecutive_days": 90,
      "min_advance_days": 0,
      "allows_backdate": false,
      "is_paid": true,
      "description": "Diberikan untuk kelahiran anak pertama sampai ketiga, dengan surat keterangan dokter atau bidan."
    },
    {
      "id": 6,
      "code": "IZIN",
      "name": "Izin Tidak Masuk Kerja",
      "category": "PERMISSION",
      "category_label": "Izin",
      "affects_balance": false,
      "requires_attachment": false,
      "max_consecutive_days": 3,
      "min_advance_days": 0,
      "allows_backdate": true,
      "is_paid": true,
      "description": "Keperluan singkat yang tidak memotong saldo cuti tahunan, paling lama tiga hari kerja per pengajuan."
    }
  ]
}
```

**Field `data[]`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | dipakai sebagai `leave_type_id` saat mengajukan |
| `code` | string | tidak | kode singkat |
| `name` | string | tidak | nama tampilan |
| `category` | string (enum) | tidak | `LeaveCategory` |
| `category_label` | string | tidak | label kategori |
| `affects_balance` | boolean | tidak | `true`: memotong saldo (`GET /me/leave-balances`) |
| `requires_attachment` | boolean | tidak | `true`: `attachment` wajib saat mengajukan |
| `max_consecutive_days` | integer | ya | batas hari kerja per pengajuan; `null` tanpa batas |
| `min_advance_days` | integer | tidak | minimal hari sebelum `start_date`; `0` tanpa syarat. Hanya berlaku bila `allows_backdate` `false` |
| `allows_backdate` | boolean | tidak | `true`: `start_date` boleh sebelum hari ini |
| `is_paid` | boolean | tidak | informasi; tidak memengaruhi API |
| `description` | string | ya | keterangan dari perusahaan |

---

## Saldo cuti

**`GET /me/leave-balances`**

Deskripsi: saldo cuti karyawan login untuk satu tahun, satu baris per jenis cuti yang memotong saldo.
Saldo yang belum ada dibuat otomatis saat endpoint dipanggil.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.me.leave-balances` |

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
| `year` | query | integer | tidak | 2000–2100. Kosong atau di luar rentang → tahun berjalan menurut zona perusahaan. Tidak ada validasi 422 |

**Contoh Request**

```http
GET /api/v1/me/leave-balances?year=2025 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, tahun berjalan, sesudah mengajukan Cuti Tahunan 3 hari yang masih
menunggu)

```json
{
  "success": true,
  "message": "Saldo cuti tahun 2026 berhasil diambil.",
  "data": [
    {
      "id": 3,
      "year": 2026,
      "leave_type_id": 1,
      "leave_type": {
        "id": 1,
        "code": "CT",
        "name": "Cuti Tahunan"
      },
      "quota_days": 12,
      "carried_over_days": 0,
      "entitled_days": 12,
      "used_days": 0,
      "pending_days": 3,
      "remaining_days": 9
    }
  ]
}
```

**Field `data[]`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID saldo |
| `year` | integer | tidak | tahun saldo |
| `leave_type_id` | integer | tidak | jenis cuti |
| `leave_type` | objek | tidak | `id`, `code`, `name` |
| `quota_days` | integer | tidak | jatah tahun ini |
| `carried_over_days` | integer | tidak | sisa tahun lalu yang dibawa |
| `entitled_days` | integer | tidak | `quota_days + carried_over_days` |
| `used_days` | integer | tidak | hari dari cuti yang disetujui |
| `pending_days` | integer | tidak | hari dari cuti yang masih menunggu; dikembalikan bila ditolak/dibatalkan |
| `remaining_days` | integer | tidak | `entitled_days - used_days - pending_days`; dipakai server untuk menolak pengajuan |

---

## Riwayat cuti

**`GET /leaves`**

Deskripsi: pengajuan cuti milik karyawan login, **50 terbaru** urut `start_date` terbaru di atas, tanpa
`days`. Tanpa pagination dan tanpa filter.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.leaves.index` |

**Contoh Request**

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

**Contoh Response Sukses** (`200`, 2026-10-22 11:10 WIB, dipotong menjadi 1 dari 2 item)

```json
{
  "success": true,
  "message": "Riwayat pengajuan cuti berhasil diambil.",
  "data": [
    {
      "id": 3,
      "leave_type_id": 1,
      "leave_type": {
        "id": 1,
        "code": "CT",
        "name": "Cuti Tahunan",
        "category": "ANNUAL"
      },
      "start_date": "2026-10-26",
      "end_date": "2026-10-28",
      "total_days": 3,
      "reason": "Menghadiri pernikahan saudara di Yogyakarta.",
      "address_during_leave": "Jl. Kaliurang Km 5, Sleman, Yogyakarta",
      "contact_phone": "081234560007",
      "status": "CANCELLED",
      "status_label": "Dibatalkan",
      "submitted_at": "2026-10-22T04:00:00+00:00",
      "decided_at": null,
      "cancelled_at": "2026-10-22T04:10:00+00:00",
      "decision_notes": null,
      "approvals": [
        {
          "sequence": 1,
          "stage_name": "Tahap 1",
          "approver": "Anton Satu",
          "status": "CANCELLED",
          "status_label": "Dibatalkan",
          "decided_at": null,
          "decided_by": null,
          "notes": null
        },
        {
          "sequence": 2,
          "stage_name": "Tahap 2",
          "approver": "Budi Satu",
          "status": "CANCELLED",
          "status_label": "Dibatalkan",
          "decided_at": null,
          "decided_by": null,
          "notes": null
        }
      ]
    }
  ]
}
```

**Field `data[]`:** [objek `leave`](#objek-leave) tanpa `days`.

---

## Objek `leave`

Sumber: `LeaveResource`. `days` hanya ada pada detail dan respons pengajuan.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID pengajuan |
| `leave_type_id` | integer | tidak | jenis cuti |
| `leave_type` | objek | tidak | `id`, `code`, `name`, `category` |
| `start_date` | string (`YYYY-MM-DD`) | tidak | tanggal mulai |
| `end_date` | string (`YYYY-MM-DD`) | tidak | tanggal selesai |
| `total_days` | integer | tidak | jumlah hari kerja yang dihitung (hari libur di dalam rentang tidak dihitung) |
| `reason` | string | tidak | alasan |
| `address_during_leave` | string | ya | alamat selama cuti |
| `contact_phone` | string | ya | nomor yang dapat dihubungi |
| `status` | string (enum) | tidak | `ApprovalStatus` |
| `status_label` | string | tidak | label tampilan |
| `submitted_at` | string (ISO 8601 UTC) | tidak | waktu pengajuan |
| `decided_at` | string (ISO 8601 UTC) | ya | waktu keputusan akhir |
| `cancelled_at` | string (ISO 8601 UTC) | ya | waktu pembatalan |
| `decision_notes` | string | ya | catatan keputusan |
| `days` | array objek | — | hanya detail/pengajuan: `work_date`, `is_counted`, `schedule_status`, `schedule_status_label` per tanggal di rentang |
| `approvals` | array objek | tidak | tahap persetujuan, lihat [koreksi presensi](attendance-corrections.md#objek-correction) |

Lampiran tidak dikembalikan.

---

## Detail cuti

**`GET /leaves/{leave}`**

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.leaves.show` |

**Parameter:** `leave` (path, integer).

**Contoh Request**

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

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Detail pengajuan cuti berhasil diambil.",
  "data": {
    "id": 3,
    "leave_type_id": 1,
    "leave_type": {
      "id": 1,
      "code": "CT",
      "name": "Cuti Tahunan",
      "category": "ANNUAL"
    },
    "start_date": "2026-10-26",
    "end_date": "2026-10-28",
    "total_days": 3,
    "reason": "Menghadiri pernikahan saudara di Yogyakarta.",
    "address_during_leave": "Jl. Kaliurang Km 5, Sleman, Yogyakarta",
    "contact_phone": "081234560007",
    "status": "PENDING",
    "status_label": "Menunggu Persetujuan",
    "submitted_at": "2026-10-22T04:00:00+00:00",
    "decided_at": null,
    "cancelled_at": null,
    "decision_notes": null,
    "days": [
      {
        "work_date": "2026-10-26",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-10-27",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-10-28",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      }
    ],
    "approvals": [
      {
        "sequence": 1,
        "stage_name": "Tahap 1",
        "approver": "Anton Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      },
      {
        "sequence": 2,
        "stage_name": "Tahap 2",
        "approver": "Budi Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      }
    ]
  }
}
```

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Milik karyawan lain di perusahaan yang sama | 403 | `Pengajuan cuti ini bukan milik Anda.` |
| ID tidak ada atau milik perusahaan lain | 404 | `Sumber daya tidak ditemukan.` |

---

## Ajukan cuti

**`POST /leaves`**

Deskripsi: mengajukan cuti untuk rentang tanggal. Server menghitung hari kerja dari Jadwal Kerja,
memeriksa saldo, lalu memesan saldo (`pending_days`) dan menyusun penyetuju sesuai [alur persetujuan](attendance-corrections.md#alur-persetujuan).

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.leaves.store` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`, `Content-Type:
application/json` atau `multipart/form-data` (wajib multipart bila mengirim `attachment`)

**Parameter** (`StoreLeaveRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `leave_type_id` | body | integer | ya | `required`, `integer`, `exists:leave_types,id`. Ambil dari `GET /leave-types`. ID jenis cuti perusahaan lain lolos validasi tetapi dijawab **404** |
| `start_date` | body | string (`YYYY-MM-DD`) | ya | `required`, `date` |
| `end_date` | body | string (`YYYY-MM-DD`) | ya | `required`, `date`, `after_or_equal:start_date` |
| `reason` | body | string | ya | `required`, `string`, `min:10`, `max:1000` |
| `address_during_leave` | body | string | tidak | `nullable`, `string`, `max:255` |
| `contact_phone` | body | string | tidak | `nullable`, `string`, `max:30` |
| `attachment` | body (part berkas) | berkas | bila `requires_attachment` | `nullable`, `file`, `mimes:jpg,jpeg,png,pdf`, `max:2048` KB (pengaturan perusahaan). Kewajiban per jenis diperiksa aturan bisnis |

**Contoh Request** (JSON, 2026-10-22 11:00 WIB)

```http
POST /api/v1/leaves HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "leave_type_id": 1,
  "start_date": "2026-10-26",
  "end_date": "2026-10-28",
  "reason": "Menghadiri pernikahan saudara di Yogyakarta.",
  "address_during_leave": "Jl. Kaliurang Km 5, Sleman, Yogyakarta",
  "contact_phone": "081234560007"
}
```

**Contoh Response Sukses** (`201`)

```json
{
  "success": true,
  "message": "Pengajuan cuti terkirim dan menunggu persetujuan Anton Satu.",
  "data": {
    "id": 3,
    "leave_type_id": 1,
    "leave_type": {
      "id": 1,
      "code": "CT",
      "name": "Cuti Tahunan",
      "category": "ANNUAL"
    },
    "start_date": "2026-10-26",
    "end_date": "2026-10-28",
    "total_days": 3,
    "reason": "Menghadiri pernikahan saudara di Yogyakarta.",
    "address_during_leave": "Jl. Kaliurang Km 5, Sleman, Yogyakarta",
    "contact_phone": "081234560007",
    "status": "PENDING",
    "status_label": "Menunggu Persetujuan",
    "submitted_at": "2026-10-22T04:00:00+00:00",
    "decided_at": null,
    "cancelled_at": null,
    "decision_notes": null,
    "days": [
      {
        "work_date": "2026-10-26",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-10-27",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-10-28",
        "is_counted": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      }
    ],
    "approvals": [
      {
        "sequence": 1,
        "stage_name": "Tahap 1",
        "approver": "Anton Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      },
      {
        "sequence": 2,
        "stage_name": "Tahap 2",
        "approver": "Budi Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      }
    ]
  }
}
```

Cuti Sakit mundur satu hari dengan surat dokter (multipart):

```http
POST /api/v1/leaves HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova

--absenova
Content-Disposition: form-data; name="leave_type_id"

2
--absenova
Content-Disposition: form-data; name="start_date"

2026-10-21
--absenova
Content-Disposition: form-data; name="end_date"

2026-10-21
--absenova
Content-Disposition: form-data; name="reason"

Demam tinggi, istirahat sesuai surat dokter.
--absenova
Content-Disposition: form-data; name="attachment"; filename="surat-dokter.pdf"
Content-Type: application/pdf

(berkas PDF, 310 KB)
--absenova--
```

```json
"message": "Pengajuan cuti terkirim dan menunggu persetujuan Anton Satu.",
"data": {
  "id": 4,
  "leave_type_id": 2,
  "leave_type": {
    "id": 2,
    "code": "CS",
    "name": "Cuti Sakit",
    "category": "SICK"
  },
  "start_date": "2026-10-21",
  "end_date": "2026-10-21",
  "total_days": 1,
  "reason": "Demam tinggi, istirahat sesuai surat dokter.",
  "address_during_leave": null,
  "contact_phone": null,
  "status": "PENDING",
  "status_label": "Menunggu Persetujuan",
  "submitted_at": "2026-10-22T04:02:00+00:00",
  "decided_at": null,
  "cancelled_at": null,
  "decision_notes": null,
  "days": [
    {
      "work_date": "2026-10-21",
      "is_counted": true,
      "schedule_status": "ON_DUTY",
      "schedule_status_label": "Masuk kerja"
    }
  ],
  "approvals": [
    {
      "sequence": 1,
      "stage_name": "Tahap 1",
      "approver": "Anton Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    },
    {
      "sequence": 2,
      "stage_name": "Tahap 2",
      "approver": "Budi Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    }
  ]
}
```

**Field `data`:** [objek `leave`](#objek-leave) dengan `days`.

**Penolakan dan urutan pemeriksaan** (422, `errors.leave`)

| # | HTTP | `message` (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 422 | ✓ `Data yang dikirim tidak lolos pemeriksaan.` (validasi FormRequest) |
| 2 | 404 | ✓ `Sumber daya tidak ditemukan.` (`leave_type_id` milik perusahaan lain) |
| 3 | 422 | `Jenis cuti {nama} tidak berlaku untuk status karyawan {status}.` |
| 4 | 422 | `Jenis cuti {nama} tidak tersedia untuk Anda.` |
| 5 | 422 | ✓ `Jenis cuti Cuti Sakit wajib melampirkan dokumen pendukung.` |
| 6 | 422 | `Tanggal mulai cuti sudah lewat. Jenis cuti ini tidak dapat diajukan mundur.` |
| 7 | 422 | ✓ `Jenis cuti Cuti Tahunan harus diajukan paling lambat 3 hari sebelum tanggal mulai.` |
| 8 | 422 | `Periode rekap untuk tanggal mulai tersebut sudah dikunci sehingga tidak dapat diajukan lagi.` |
| 9 | 422 | ✓ `Sudah ada pengajuan cuti lain yang beririsan tanggalnya dan belum dibatalkan.` |
| 10 | 422 | `Jadwal kerja pada {tanggal} belum lengkap: {status}. Hubungi Admin HR.` |
| 11 | 422 | ✓ `Tidak ada hari kerja pada rentang tanggal tersebut, sehingga cuti tidak perlu diajukan.` |
| 12 | 422 | ✓ `Jenis cuti Izin Tidak Masuk Kerja dibatasi maksimal 3 hari kerja per pengajuan, sedangkan pengajuan ini 5 hari kerja.` |
| 13 | 422 | ✓ `Sisa saldo Cuti Tahunan tahun 2026 tinggal 9 hari, sedangkan pengajuan ini memerlukan 25 hari.` |

Validasi (`leave_type_id: "tahunan"`, `end_date` sebelum `start_date`, `reason: "Liburan"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "leave_type_id": [
      "Kolom jenis cuti harus berupa bilangan bulat."
    ],
    "end_date": [
      "Kolom tanggal selesai harus berisi tanggal tanggal mulai atau setelahnya."
    ],
    "reason": [
      "Kolom alasan minimal 10 karakter."
    ]
  }
}
```

Penolakan aturan bisnis:

```json
{
  "success": false,
  "message": "Sisa saldo Cuti Tahunan tahun 2026 tinggal 9 hari, sedangkan pengajuan ini memerlukan 25 hari.",
  "errors": {
    "leave": [
      "Sisa saldo Cuti Tahunan tahun 2026 tinggal 9 hari, sedangkan pengajuan ini memerlukan 25 hari."
    ]
  }
}
```

**Catatan**

- Hitung hari kerja di server. Sabtu/Minggu dan hari libur di dalam rentang tidak memotong saldo dan
  tidak dihitung batas `max_consecutive_days`.
- Idempotency: tidak ada kunci. Pengajuan kedua untuk tanggal yang beririsan ditolak (nomor 9).
- Penyetuju disusun server saat pengajuan dibuat dan disimpan pada `approvals`; lihat
  [alur persetujuan](attendance-corrections.md#alur-persetujuan). `message` sukses menyebut
  penyetuju Tahap 1, atau `Admin HR` bila karyawan tidak memiliki penyetuju berjenjang.
- Rate limit: tidak ada. FeatureGate / modul: `module_leave` (server tidak memblokir). Status
  langganan: terkunci → 402.

---

## Batalkan cuti

**`POST /leaves/{leave}/cancel`**

Deskripsi: karyawan membatalkan cuti miliknya. Saldo yang dipesan atau terpakai dikembalikan.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.leaves.cancel` |

**Parameter:** `leave` (path, integer). Tanpa body.

**Status yang dapat dibatalkan:** `PENDING` kapan saja; `APPROVED` hanya bila `start_date` masih
setelah hari ini. `REJECTED` dan `CANCELLED` tidak.

**Contoh Request**

```http
POST /api/v1/leaves/3/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`). Respons pembatalan tidak memuat `days`:

```json
{
  "success": true,
  "message": "Pengajuan cuti dibatalkan dan saldo dikembalikan.",
  "data": {
    "id": 3,
    "leave_type_id": 1,
    "leave_type": {
      "id": 1,
      "code": "CT",
      "name": "Cuti Tahunan",
      "category": "ANNUAL"
    },
    "start_date": "2026-10-26",
    "end_date": "2026-10-28",
    "total_days": 3,
    "reason": "Menghadiri pernikahan saudara di Yogyakarta.",
    "address_during_leave": "Jl. Kaliurang Km 5, Sleman, Yogyakarta",
    "contact_phone": "081234560007",
    "status": "CANCELLED",
    "status_label": "Dibatalkan",
    "submitted_at": "2026-10-22T04:00:00+00:00",
    "decided_at": null,
    "cancelled_at": "2026-10-22T04:10:00+00:00",
    "decision_notes": null,
    "approvals": [
      {
        "sequence": 1,
        "stage_name": "Tahap 1",
        "approver": "Anton Satu",
        "status": "CANCELLED",
        "status_label": "Dibatalkan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      },
      {
        "sequence": 2,
        "stage_name": "Tahap 2",
        "approver": "Budi Satu",
        "status": "CANCELLED",
        "status_label": "Dibatalkan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      }
    ]
  }
}
```

Saldo kembali penuh sesudah pembatalan:

```json
[
  {
    "id": 3,
    "year": 2026,
    "leave_type_id": 1,
    "leave_type": {
      "id": 1,
      "code": "CT",
      "name": "Cuti Tahunan"
    },
    "quota_days": 12,
    "carried_over_days": 0,
    "entitled_days": 12,
    "used_days": 0,
    "pending_days": 0,
    "remaining_days": 12
  }
]
```

**Contoh Response Error** (`422`, `errors.leave`)

| Kondisi | `message` |
|---|---|
| Sudah `CANCELLED`/`REJECTED` | ✓ `Pengajuan cuti ini sudah berstatus Dibatalkan.` |
| `APPROVED` dan `start_date` hari ini atau sudah lewat | ✓ `Cuti yang sudah berjalan atau selesai tidak dapat dibatalkan. Ajukan koreksi presensi bila diperlukan.` |
| Milik karyawan lain (403) | `Pengajuan cuti ini bukan milik Anda.` |

```json
{
  "success": false,
  "message": "Cuti yang sudah berjalan atau selesai tidak dapat dibatalkan. Ajukan koreksi presensi bila diperlukan.",
  "errors": {
    "leave": [
      "Cuti yang sudah berjalan atau selesai tidak dapat dibatalkan. Ajukan koreksi presensi bila diperlukan."
    ]
  }
}
```

**Catatan:** rate limit tidak ada; FeatureGate `module_leave`; langganan terkunci → 402.
