CHANGELOG Kontrak API v1

Lihat Markdown

Setiap perubahan pada route, controller, FormRequest, JsonResource, ApiResponse, exception handler API, atau middleware API dicatat di sini dalam task yang sama (CLAUDE.md 11.1). Entri terbaru di atas.

Format Entri

## YYYY-MM-DD

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| `METHOD /path` | ADDED / CHANGED / REMOVED / BREAKING | apa yang berubah dan dampaknya bagi client |
Jenis Arti
ADDED endpoint atau field baru; client lama tetap berjalan
CHANGED perilaku berubah tanpa merusak client lama (mis. batas validasi melonggar, message berubah)
REMOVED endpoint atau field dihapus
BREAKING perubahan yang merusak client lama: field dihapus/diganti nama, tipe atau arti berubah, validasi mengetat

Sebelum aplikasi rilis ke Play Store, REMOVED dan BREAKING masih boleh terjadi di v1. Setelah rilis, keduanya hanya boleh terjadi di /api/v2.


2026-11-15

Endpoint Jenis Ringkasan
GET /announcements, GET /announcements/{announcement} ADDED Pengumuman perusahaan untuk karyawan: daftar yang sedang tayang (disematkan di atas, maksimal 50) dengan is_read, dan detail yang sekaligus menandai dibaca. Pengumuman terjadwal, berakhir, atau milik perusahaan lain dijawab 404. Berkas announcements.md
GET /me/config CHANGED modules.module_announcement kini mengikuti paket (sebelumnya selalu false). Bentuk respons tidak berubah
PUT /me/push-token, DELETE /me/push-token ADDED Pendaftaran dan penghapusan token FCM untuk sesi login saat ini. Token push terikat ke token login dan ikut terhapus saat logout, ganti kata sandi, login ulang di perangkat yang sama, atau perangkat pinjaman berakhir; client wajib mendaftar ulang setiap login dan pada onNewToken(). Pengiriman push belum aktif. Berkas push-tokens.md

2026-10-23

Endpoint Jenis Ringkasan
GET /approvals, GET /approvals/{approval}, POST /approvals/{approval}/approve, POST /approvals/{approval}/reject ADDED Persetujuan pengajuan oleh penyetuju dari aplikasi. GET /approvals mengirim tahap yang menunggu keputusan karyawan login (status=pending, bawaan) atau riwayat keputusannya (status=decided), dapat disaring type. Item berisi can_decide, requester, dan request (objek modul lengkap). Tolak wajib notes; setujui menerima notes dan approved_amount (reimbursement, tahap terakhir). Keputusan sebagai Admin HR tetap hanya di panel. Berkas approvals.md
Seluruh endpoint pengajuan CHANGED approvals[].notes dan decision_notes kini dapat berisi sampai 1000 karakter (kolom TEXT); sebelumnya dibatasi kolom 255 karakter. Tipe tidak berubah
GET/POST /attendance/corrections, GET/POST /leaves, GET /leaves/{leave}, POST /leaves/{leave}/cancel, dan pasangan yang sama pada /overtimes, /business-trips, /reimbursements ADDED approvals[].decided_by (string, null selama belum diputuskan atau bila tahap CANCELLED): nama yang benar-benar memutuskan tahap. Berbeda dari approver bila Admin HR memutuskan menggantikan penyetuju lewat panel
Endpoint yang sama CHANGED Penyetuju kini disusun dari satu aturan untuk seluruh jenis pengajuan: Tahap 1 = Atasan Langsung, atau Kepala Departemen terdekat dari unit pemohon ke atas; Tahap 2 = penyetuju Tahap 1 untuk orang Tahap 1. Pemohon tidak pernah menjadi penyetujunya sendiri dan Tahap 1 ≠ Tahap 2. approvals[].stage_name untuk pengajuan baru bernilai Tahap 1, Tahap 2, atau Admin HR (sebelumnya nama tahap dari menu Jenjang Persetujuan, mis. Atasan Langsung); pengajuan lama tidak diubah. Alur bisa satu tahap. Tipe dan arti field tidak berubah. Lihat alur persetujuan
POST /attendance/corrections, POST /leaves, POST /overtimes, POST /business-trips, POST /reimbursements CHANGED Karyawan tanpa penyetuju berjenjang kini mendapat satu tahap Admin HR dengan approver null dan message sukses biasa. Sebelumnya tahap-tahap dengan approver null dan message peringatan Pengajuan tersimpan, tetapi penyetuju pada tahap ... belum ditentukan. Hubungi Admin HR.
Endpoint POST yang sama CHANGED message sukses menyebut nama penyetuju Tahap 1 atau Admin HR, mis. Pengajuan koreksi presensi terkirim dan menunggu persetujuan Anton Satu. (sebelumnya ...menunggu persetujuan atasan langsung.). Penolakan 422 Jenjang persetujuan ... belum dikonfigurasi. Hubungi Admin HR. dihapus karena tidak dapat terjadi lagi

2026-10-22

Endpoint Jenis Ringkasan
Seluruh route berlimiter (POST /auth/login, POST /attendance/check-in, /check-out, POST /client-visits/check-in, /auth/lend/*, /auth/forgot-password, /auth/reset-password, GET /app/version, GET /companies/{slug}/branding) CHANGED Respons 429 kini membawa header Retry-After (detik sampai kuota pulih) dan X-RateLimit-Reset (Unix timestamp), selain X-RateLimit-Limit/X-RateLimit-Remaining. Body tidak berubah
GET /me/config ADDED Blok consent: policy_version, title, body (teks polos, paragraf \n), accepted, accepted_at untuk karyawan login dan versi kebijakan aktif. Versi aktif pertama 2026-10; teks awal belum ditinjau tim legal
POST /consents CHANGED policy_version wajib sama dengan versi aktif (in); versi lain dijawab 422 errors.policy_version. Body request dan bentuk respons sukses tidak berubah; aplikasi yang mengirim 2026-10 tetap diterima selama versi itu aktif
GET /attendance/today ADDED check_in_opens_at dan check_out_closes_at (ISO 8601 UTC, null bila tidak ada jadwal masuk) dari resolver yang sama dengan pemeriksaan OUTSIDE_WINDOW. Arti can_check_in/can_check_out tidak berubah: keduanya tetap tidak memeriksa jam
GET /me/config CHANGED today.check_in_opens_at/check_out_closes_at kini memperhitungkan pelebaran jendela dari lembur BEFORE_SHIFT/AFTER_SHIFT yang disetujui, sama dengan aturan yang ditegakkan. Contoh: lembur 17:00–20:00 pada jam kerja 08:00–17:00 → sebelumnya 06:30–19:00 WIB, kini 03:00–22:30 WIB. Tanpa lembur tersebut nilainya tidak berubah
GET /me/config CHANGED modules.module_announcement dan modules.module_face_matching kini selalu false selama endpoint-nya belum tersedia (sebelumnya true pada paket produksi). Kunci, tipe, dan arti tidak berubah; modul yang dirilis kelak akan kembali mengikuti paket
GET /app/version ADDED Endpoint publik tanpa token untuk layar pembuka: latest_version_name, latest_version_code, minimum_version_code, store_url, message per platform. Nilai dikelola di panel platform; platform yang belum diatur dijawab angka 0. Limiter api 60/menit per IP. Berkas app-version.md
— ADDED Berkas modul attendance-corrections.md, overtimes.md, leaves.md, business-trips.md, reimbursements.md, timesheets.md, client-visits.md, device-lending.md dari 164 panggilan HTTP nyata. Seluruh 53 endpoint v1 kini terdokumentasi
POST /client-visits/check-in, POST /client-visits/{clientVisit}/check-out CHANGED Perbaikan: captured_at dan device_time yang membawa offset kini dikonversi ke UTC sebelum disimpan. Sebelumnya jam lokal disimpan sebagai UTC (WIB bergeser +7 jam), sehingga checked_in_at di respons 7 jam lebih lambat dan check-out selalu ditolak Waktu check-out harus lebih besar daripada waktu check-in. Client yang mengirim waktu UTC (Z) tidak terdampak. Bentuk request dan response tidak berubah

Perilaku yang sudah berlaku di kode dan baru tercatat di kontrak (bukan perubahan):

  • POST /leaves → leave_type_id milik perusahaan lain lolos validasi lalu dijawab 404 Sumber daya tidak ditemukan., bukan 422.
  • POST /reimbursements dan POST /timesheet-entries → business_trip_id/client_visit_id milik karyawan lain diabaikan (tersimpan null) tanpa penolakan.
  • POST /client-visits/{clientVisit}/cancel → reason dibaca tanpa FormRequest dan tanpa validasi panjang.
  • GET /timesheets/today membuat timesheet DRAFT kosong; GET /me/leave-balances membuat baris saldo yang belum ada, termasuk untuk ?year= lain.
  • POST /attendance/corrections → work_date berformat DD-MM-YYYY lolos validasi date. Tidak ada endpoint detail maupun pembatalan koreksi.
  • GET /reimbursements → approved_amount bernilai 0 (bukan null) sebelum disetujui.
  • POST /client-visits/{clientVisit}/check-out → pesan validasi follow_up_date berbunyi ...tanggal today atau setelahnya. (kata today belum diterjemahkan).

2026-10-21

Endpoint Jenis Ringkasan
— ADDED Berkas modul auth.md, me.md, attendance.md: parameter lengkap dari FormRequest, struktur field response, daftar enum, dan contoh request/response dari eksekusi nyata (100 panggilan HTTP). Dokumentasi saja, kode dan perilaku API tidak berubah
— CHANGED Token pada contoh README.md disamarkan menjadi 1|contohTokenDisamarkanTidakBerlakuDiServerManaPun; token samaran dan token lama diuji ke produksi dan dijawab 401
— ADDED Kerangka kontrak docs/api/: konvensi umum di README.md dan berkas changelog ini. Kondisi awal 53 endpoint v1 tercatat di README bagian 15
GET /attendance/today ADDED field is_overtime (boolean) dan overtime_type (REST_DAY, HOLIDAY, atau null)
GET /overtimes, GET /overtimes/{overtime} ADDED field hourly_rate dan amount (rupiah bilangan bulat, null sebelum lembur direalisasi atau tarif belum diatur)
POST /attendance/corrections CHANGED tanggal libur yang punya lembur hari libur disetujui kini dapat dikoreksi; jendela koreksi hari kerja diperlebar oleh lembur yang disetujui pada tanggal itu
POST /timesheet-entries, POST /client-visits/check-in CHANGED work_date mengikuti lembur hari libur yang melewati tengah malam (tanggal mulai lembur)

Perilaku yang sudah berlaku di kode dan baru tercatat di kontrak (bukan perubahan):

  • GET /me/config → subscription hanya berisi status, plan, is_locked bila perusahaan tidak punya langganan berjalan; status_label, trial_ends_at, ends_at tidak dikirim.
  • GET /me/config → module_announcement dan module_face_matching bernilai true pada paket produksi, padahal endpoint belum ada.
  • GET /me/config → today.check_in_opens_at/check_out_closes_at belum memperhitungkan pelebaran jendela dari lembur sebelum/sesudah jam kerja yang disetujui.
  • GET /attendance/today → can_check_in/can_check_out tidak memeriksa jam; sebelum jendela dibuka nilainya tetap true.
  • POST /attendance/check-in|check-out → kirim ulang dengan uuid lama dijawab 200 DUPLICATE walau lewat toleransi offline, tetapi tetap wajib lolos validasi (termasuk photo).
  • POST /attendance/check-in|check-out → batas laju (429) diperiksa sebelum kunci langganan (402).