Kontrak API Absenova v1

Lihat Markdown

Dokumen ini adalah satu-satunya sumber kontrak bagi client mobile (aturan lengkap: CLAUDE.md bagian 11.1). Isinya konvensi yang sudah berlaku di kode per tanggal di bawah. Rincian setiap endpoint ada di berkas per modul (bagian 15). Riwayat perubahan ada di CHANGELOG.md.

Atribut Nilai
Versi kontrak v1 (belum dirilis ke Play Store, perubahan BREAKING masih boleh asal tercatat)
Terakhir diperbarui 2026-10-21
Sumber contoh response Eksekusi nyata lewat HTTP kernel Laravel, basis data uji dua perusahaan, 2026-10-21
Halaman web https://hrisapp.my.id/docs/api (berkas modul: /docs/api/{nama}, mis. /docs/api/changelog)
Markdown mentah https://hrisapp.my.id/docs/api/README.md (berkas lain: /docs/api/{NAMA}.md)

Deskripsi ditulis dalam Bahasa Indonesia. Nama field, nilai enum, dan istilah teknis tetap Inggris.


1. Base URL

Lingkungan Base URL
Produksi https://hrisapp.my.id/api/v1
Lokal (Herd) http://absenova.test/api/v1
Terowongan ngrok (uji perangkat) https://<subdomain>.ngrok-free.app/api/v1, wajib header ngrok-skip-browser-warning: true

Seluruh route ada di routes/api/v1.php, dimuat routes/api.php dengan prefix v1 dan nama route api.v1.*. Versi dikunci di path. Versi baru akan menjadi /api/v2, tidak mengganti v1.


2. Autentikasi

Urutan di layar pembuka: GET /app/version?platform=ANDROID (tanpa token, lihat app-version.md) → bila versionCode aplikasi di bawah minimum_version_code, tampilkan layar wajib perbarui dan berhenti → bila lolos, lanjut ke login atau GET /me/config.

2.1 Token

  • Laravel Sanctum, Bearer token: Authorization: Bearer <token>.
  • Satu token per perangkat. Nama token device:{device_identifier}. Login ulang dari perangkat yang sama menghapus token lama perangkat itu dan menerbitkan token baru.
  • Token tidak kedaluwarsa (sanctum.expiration = null). Token berhenti berlaku bila:
    • POST /auth/logout (token yang dipakai saja)
    • PUT /me/password berhasil (seluruh token karyawan dihapus, wajib login ulang)
    • POST /auth/reset-password berhasil (seluruh token dihapus)
    • Admin HR mencabut perangkat (token perangkat itu dihapus)
  • Token yang tidak sah selalu dijawab 401 dengan message yang sama. Client cukup menghapus token lokal dan kembali ke layar login.
  • Perusahaan (tenant) diturunkan dari token. Client tidak pernah mengirim company_id, baik di body, query, maupun header.
  • Token pada seluruh contoh dokumentasi disamarkan menjadi {id}|contohTokenDisamarkanTidakBerlakuDiServerManaPun. Nilai aslinya terbit dari basis data uji SQLite sekali pakai di mesin pengembang, bukan dari server. Token samaran dan token contoh lama di riwayat git sudah diuji ke https://hrisapp.my.id/api/v1/me dan dijawab 401 (2026-10-21).

2.2 Login

POST /auth/login, tanpa token. identifier berisi Nomor Karyawan atau alamat surel.

Kondisi HTTP message
Perangkat pertama karyawan (belum punya perangkat disetujui) 200 Perangkat berhasil didaftarkan. (perangkat langsung APPROVED)
Perangkat yang sudah disetujui 200 Perangkat dikenali.
Perangkat lain saat sudah punya perangkat disetujui 403 Perangkat ini belum disetujui. Pengajuan sudah dikirim ke Admin HR, ... (errors.device)
Perangkat yang dicabut 403 Perangkat ini sudah dicabut aksesnya. Hubungi Admin HR bila ingin mendaftarkannya kembali.
Nomor Karyawan atau kata sandi salah 401 Nomor Karyawan atau kata sandi tidak sesuai.
Akun tidak aktif 403 Akun karyawan tidak berstatus aktif. Hubungi Admin HR.
Nomor Karyawan sama di dua perusahaan 409 Nomor Karyawan tersebut terdaftar di lebih dari satu perusahaan. Gunakan alamat surel Anda untuk masuk.

Parameter lengkap, seluruh variasi respons, dan enum ada di auth.md. Contoh sukses (direkam):

{
  "success": true,
  "message": "Perangkat berhasil didaftarkan.",
  "data": {
    "token": "1|contohTokenDisamarkanTidakBerlakuDiServerManaPun",
    "employee": {
      "id": 3,
      "employee_number": "EMP-0007",
      "name": "Citra Satu",
      "email": "citra@nusantara-logistik.test",
      "phone": "083289396919",
      "employment_status": "OUTSOURCE",
      "employment_status_label": "Alih Daya",
      "work_pattern": "FIXED",
      "work_pattern_label": "Jam Tetap",
      "department": "Divisi Operasional",
      "position": "Spesialis",
      "job_level": "Direktur",
      "must_change_password": false
    },
    "device": {
      "id": 1,
      "device_identifier": "6f1c2a9e-citra-pixel",
      "device_name": "Pixel 8",
      "platform": "ANDROID",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "approved_at": "2026-10-21T00:55:00+00:00",
      "last_used_at": "2026-10-21T00:55:00+00:00"
    }
  }
}
  • device_identifier wajib stabil per instalasi dan unik per perangkat. Bila berubah, server menganggapnya perangkat baru yang menunggu persetujuan Admin HR.
  • Bila employee.must_change_password bernilai true (kata sandi sementara dari Admin HR), client wajib mengarahkan ke PUT /me/password sebelum fitur lain.

2.3 Logout

POST /auth/logout mencabut token yang dipakai. Bila karyawan sedang memakai perangkat pinjaman, sesi pinjaman ikut dihentikan. Respons 200, data berisi {}.

2.4 Lupa dan atur ulang kata sandi

  1. POST /auth/forgot-password dengan identifier. Selalu 200 dengan message umum (tidak membocorkan apakah akun ada) dan data.expires_minutes (bawaan 15). Kode 6 digit dikirim ke surel karyawan bila akun ditemukan, aktif, dan punya surel.
  2. POST /auth/reset-password dengan identifier, code (6 digit), password, password_confirmation (minimal 8 karakter). Kode salah atau kedaluwarsa: 422 dengan errors.code. Batas percobaan per kode: 5 (absenova.password_reset.max_attempts).
  3. Setelah berhasil, seluruh token karyawan dicabut. Client kembali ke layar login.

2.5 Perangkat pinjaman

Karyawan yang ponselnya bermasalah dapat presensi di perangkat rekan dengan kode surel: POST /auth/lend/request → POST /auth/lend/verify (menerbitkan token khusus pinjaman) → GET /me/lending / POST /auth/lend/end. Rincian di device-lending.md.


3. Header

Header Kapan Nilai
Accept selalu application/json
Authorization seluruh endpoint kecuali yang bertanda publik Bearer <token>
Content-Type request ber-body application/json, atau multipart/form-data bila ada berkas
ngrok-skip-browser-warning hanya lewat alamat ngrok true

Tidak ada header kustom lain. Server tidak membaca header tenant, perangkat, maupun versi aplikasi; versi aplikasi dikirim sebagai field app_version pada login dan presensi.


4. Envelope Response

Format ini tetap dan tidak akan diubah (App\Support\ApiResponse).

4.1 Sukses

{ "success": true, "message": "Data karyawan berhasil diambil.", "data": { } }
  • message selalu Bahasa Indonesia dan layak ditampilkan ke pengguna.
  • data berupa objek (satu sumber daya), array (daftar), atau {} bila tidak ada isi. data tidak pernah null. Contoh {} yang direkam:
{ "success": true, "message": "Anda tidak sedang memakai perangkat pinjaman.", "data": {} }

4.2 Error

{ "success": false, "message": "Sumber daya tidak ditemukan.", "errors": {} }
  • errors selalu objek: {} bila tidak ada rincian, atau peta nama_field → [pesan, ...].
  • Error validasi FormRequest (422), kunci = nama field request:
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": ["Kolom kata sandi wajib diisi."],
    "device_identifier": ["Kolom pengenal perangkat wajib diisi."],
    "device_platform": ["Pilihan pada kolom jenis perangkat tidak sah."]
  }
}
  • Penolakan aturan bisnis (422/403/409 dari Service) memakai kunci domain berisi message yang sama: attendance, correction, leave, overtime, reimbursement, business_trip, client_visit, timesheet, device, device_lending. Beberapa memakai nama field: code (reset kata sandi), current_password, reimbursement_category_id.
{
  "success": false,
  "message": "Anda sudah melakukan presensi masuk untuk jadwal ini.",
  "errors": { "attendance": ["Anda sudah melakukan presensi masuk untuk jadwal ini."] }
}
  • Penolakan presensi tidak mengirim kode mesin (NOT_ON_DUTY, OUTSIDE_WINDOW, dst.); client menampilkan message. Kode hanya ada pada respons sukses (data.code: ACCEPTED / DUPLICATE).

5. Kode HTTP

Kode Arti Contoh message (direkam)
200 Berhasil Data karyawan berhasil diambil.
200 Duplikat idempotency, data asli dikembalikan, tidak ada data ganda Presensi ini sudah tercatat sebelumnya. Tidak ada data ganda yang dibuat.
201 Data baru tercipta: presensi, pengajuan koreksi/cuti/lembur/reimbursement/perjalanan bisnis, check-in kunjungan, aktivitas timesheet Presensi masuk tercatat tepat waktu.
401 Token tidak ada, salah, atau sudah dicabut Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.
401 Login: kredensial salah Nomor Karyawan atau kata sandi tidak sesuai.
402 Langganan perusahaan terkunci (lihat 5.1) Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.
403 Data milik karyawan lain di perusahaan yang sama Pengajuan cuti ini bukan milik Anda.
403 Login: perangkat belum disetujui atau dicabut Perangkat ini belum disetujui. Pengajuan sudah dikirim ke Admin HR, ...
403 Login: akun tidak aktif Akun karyawan tidak berstatus aktif. Hubungi Admin HR.
404 Route atau data tidak ada, termasuk data perusahaan lain Sumber daya tidak ditemukan.
409 Login: Nomor Karyawan ganda lintas perusahaan Nomor Karyawan tersebut terdaftar di lebih dari satu perusahaan. Gunakan alamat surel Anda untuk masuk.
422 Validasi FormRequest atau aturan bisnis Data yang dikirim tidak lolos pemeriksaan. / Tidak dijadwalkan masuk pada tanggal ini.
429 Batas laju terlampaui Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.
500 Galat server Tidak memakai envelope; bentuknya bawaan Laravel. Belum direkam

5.1 Langganan terkunci

  • Status langganan PAST_DUE dan SUSPENDED mengunci API. Seluruh endpoint bertoken dijawab 402, termasuk presensi, kecuali POST /auth/logout, GET /me, dan GET /me/config.
  • Tidak ada mode read-only di kode saat ini. Yang ada hanya terbuka penuh atau terkunci.
  • GET /me/config → data.subscription.is_locked memberi tahu client sebelum memanggil endpoint lain. Contoh direkam saat SUSPENDED:
"subscription": {
  "status": "SUSPENDED",
  "status_label": "Ditangguhkan",
  "plan": "Absenova",
  "trial_ends_at": "2026-11-04T04:03:46+00:00",
  "ends_at": "2026-11-04",
  "is_locked": true
}

6. Tanggal, Waktu, dan Zona Waktu

Jenis Format response Contoh
Timestamp (*_at) ISO 8601, selalu UTC (+00:00) "2026-10-21T00:54:30+00:00"
Tanggal (work_date, *_date) YYYY-MM-DD menurut kalender perusahaan "2026-10-21"
  • Client mengonversi timestamp ke zona perusahaan untuk tampilan: me/config → data.company.timezone (sama dengan data.policy.timezone), mis. Asia/Jakarta, Asia/Makassar.
  • work_date adalah tanggal mulai shift. Shift malam Senin 22:00 → Selasa 06:00 tercatat work_date Senin.
  • Request timestamp wajib ISO 8601 dengan offset, mis. 2026-10-21T07:54:30+07:00. Timestamp tanpa offset dibaca server sebagai UTC (zona aplikasi UTC).
  • Request tanggal: YYYY-MM-DD. Request jam lembur (start_time, end_time): HH:mm waktu perusahaan. Jam selesai lebih kecil dari jam mulai berarti melewati tengah malam.
  • Jam server adalah acuan. captured_at maksimal 5 menit di depan jam server dan maksimal policy.offline_sync_tolerance_hours (bawaan 24) jam ke belakang. device_time hanya untuk deteksi penyimpangan jam perangkat.

7. Pagination

Tidak ada pagination. Endpoint daftar mengembalikan array biasa di data tanpa meta/links, dibatasi jumlah terbaru:

Endpoint Batas
GET /attendance/history 31 hari terakhir (hari ini dan 30 hari sebelumnya)
GET /attendance/corrections, /leaves, /overtimes, /reimbursements, /business-trips, /client-visits 50 terbaru
GET /approvals 50 (pending terlama di atas, decided terbaru di atas)
GET /timesheets 31 terbaru
GET /clients 200, dapat disaring ?search= (nama atau kode)
GET /me/leave-balances satu tahun, ?year= (bawaan tahun berjalan)

Bila pagination ditambahkan kelak, sifatnya additive dan tercatat di CHANGELOG.md.


8. Penamaan Field JSON

Aturan Contoh
snake_case, Bahasa Inggris employee_number, work_date
ID bilangan bulat "id": 3
Enum string huruf besar + pasangan *_label Bahasa Indonesia untuk tampilan "status": "APPROVED", "status_label": "Disetujui"
Boolean berawalan is_, has_, can_, requires_, allows_, must_ is_suspect, can_check_in, must_change_password
Durasi menit bilangan bulat *_minutes late_minutes, payable_minutes
Jarak meter *_meters radius_meters, distance_meters
Uang rupiah bilangan bulat tanpa desimal amount, hourly_rate, max_amount_per_claim
Koordinat angka desimal "latitude": -6.2087634
Field kosong dikirim null, tidak dihilangkan "check_out_at": null

Client membandingkan nilai enum, bukan *_label. Label boleh berubah tanpa dianggap BREAKING. Daftar nilai enum ada di berkas modul masing-masing.


9. Idempotency

Endpoint Kunci Perilaku duplikat
POST /attendance/check-in, POST /attendance/check-out field uuid (UUID dibuat client per event) 200, data.code = "DUPLICATE", data presensi asli
POST /client-visits/check-in field uuid 200, Kunjungan ini sudah pernah terkirim sebelumnya., data kunjungan asli
  • Simpan uuid bersama data antrean offline dan pakai ulang uuid yang sama saat mengirim ulang. Membuat uuid baru untuk event yang sama akan ditolak sebagai presensi kedua.
  • Endpoint POST lain tidak punya kunci idempotency. Client wajib mencegah kirim ganda (mis. menonaktifkan tombol selama request berjalan).

10. Rate Limit

Limiter Endpoint Batas Dihitung per
login POST /auth/login 5 / menit identifier + IP
password-reset POST /auth/forgot-password, POST /auth/reset-password 3 / menit identifier + IP
device-lending POST /auth/lend/request, POST /auth/lend/verify 3 / menit identifier + IP
attendance POST /attendance/check-in, POST /attendance/check-out, POST /client-visits/check-in (satu kuota bersama) 12 / menit karyawan
api GET /app/version, GET /companies/{slug}/branding 60 / menit IP
  • Respons pada route berlimiter membawa X-RateLimit-Limit dan X-RateLimit-Remaining.
  • Respons 429 membawa Retry-After (detik sampai kuota pulih) dan X-RateLimit-Reset (Unix timestamp detik), untuk seluruh limiter. Tunggu sesuai Retry-After sebelum mencoba lagi; nilainya menurun sesuai sisa jendela satu menit. Contoh nyata, percobaan login keenam lalu 35 detik kemudian:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
Retry-After: 60
X-RateLimit-Reset: 1792629660
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
Retry-After: 25
X-RateLimit-Reset: 1792629660
  • Endpoint bertoken lain tidak dibatasi.

11. Upload Media

Upload memakai multipart/form-data. Seluruh field non-berkas dikirim sebagai part teks.

Endpoint Field Jenis Batas ukuran Wajib
POST /attendance/check-in, /check-out photo gambar policy.photo_max_kilobytes (bawaan 300 KB) bila policy.photo_required
POST /attendance/corrections attachment gambar 2048 KB tidak
POST /leaves attachment jpg, jpeg, png, pdf 2048 KB (pengaturan perusahaan) bila leave_type.requires_attachment
POST /reimbursements receipt jpg, jpeg, png, pdf 2048 KB (pengaturan perusahaan) bila category.requires_receipt
POST /business-trips attachment jpg, jpeg, png, pdf 2048 KB (pengaturan perusahaan) tidak
POST /client-visits/check-in photo gambar policy.client_visit.photo_max_kilobytes (bawaan 500 KB) bila policy.client_visit.photo_required
  • Selfie presensi memakai kamera depan dan dikompres di client sebelum dikirim.
  • Boolean di multipart dikirim 1 atau 0. Aturan boolean Laravel tidak menerima teks true/false pada part multipart. Di body JSON, true/false diterima.
  • Berkas disimpan privat. API tidak mengembalikan URL berkas, kecuali logo_url perusahaan.

12. Modul dan Kebijakan dari me/config

  • data.modules berisi saklar modul paket (module_leave, module_overtime, dst.). Server tidak memblokir endpoint berdasarkan saklar ini. Client menyembunyikan menu modul yang false. Modul yang belum punya endpoint (module_face_matching) selalu false sampai endpoint dirilis, apa pun isi paket; saat itu nilainya berubah menjadi true tanpa perubahan bentuk respons. module_announcement dirilis 2026-11-15 dan kini mengikuti paket. Pemetaan kunci ke berkas modul ada di me.md.
  • data.policy berisi aturan perusahaan yang dipakai client untuk validasi awal (ukuran foto, ambang akurasi GPS, toleransi offline, aturan timesheet, kunjungan, lembur, perangkat pinjaman). Server tetap memvalidasi ulang, jadi nilai ini bukan jaminan diterima.
  • Panggil GET /me/config saat aplikasi dibuka dan setelah login. Nilainya boleh di-cache, tetapi today berubah setiap hari.

13. Persetujuan Data Pribadi (UU PDP)

  • Sumber kebenaran di server. GET /me/config → consent mengirim versi kebijakan aktif (policy_version), title, body (teks polos, paragraf dipisah \n), dan status karyawan login (accepted, accepted_at) untuk versi itu. Versi dan teks dikelola di panel platform dan dapat diganti tanpa rilis aplikasi; versi aktif pertama 2026-10.
  • Bila accepted false, tampilkan layar persetujuan dengan title/body dari server, lalu kirim POST /consents dengan policy_version yang sama. Versi selain versi aktif ditolak 422 (errors.policy_version).
  • Saat versi aktif diganti, accepted kembali false untuk seluruh karyawan.
  • Server belum mewajibkan consent sebelum presensi. Usulan penegakan (menunggu keputusan): check-in dan check-out ditolak 422 dengan kode CONSENT_REQUIRED dan message berisi ajakan menyetujui kebijakan, bila accepted false. Bila diterapkan, perubahan itu dicatat sebagai BREAKING atau diberi masa transisi.

14. Template Dokumentasi per Endpoint

Setiap endpoint di berkas modul ditulis dengan kerangka berikut. Contoh request dan response wajib hasil eksekusi nyata (CLAUDE.md 11.1).

### <Judul singkat>

**`METHOD /path/{param}`**

Deskripsi: <apa yang dilakukan, kapan dipanggil client>

| Auth & Middleware | |
|---|---|
| Token | wajib / publik |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive`, `throttle:<nama>` |
| Route name | `api.v1.<nama>` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`, `Content-Type: ...`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `field` | body / query / path | string | ya | `required`, `max:255` |

**Contoh Request**

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

{ ... }
```

**Contoh Response Sukses** (`<kode HTTP>`)

```json
{ "success": true, "message": "...", "data": { } }
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|

```json
{ "success": false, "message": "...", "errors": { } }
```

**Catatan**

- Idempotency: ...
- Rate limit: ...
- FeatureGate / modul: ...
- Status langganan: terkunci → 402 / dikecualikan

15. Berkas per Modul

Berkas Endpoint Status
app-version.md GET /app/version selesai 2026-10-22
auth.md GET /companies/{slug}/branding, POST /auth/login, POST /auth/logout, POST /auth/forgot-password, POST /auth/reset-password selesai 2026-10-21
device-lending.md POST /auth/lend/request, POST /auth/lend/verify, GET /me/lending, POST /auth/lend/end selesai 2026-10-22
me.md GET /me, GET /me/config, GET /me/devices, PUT /me/password, POST /consents selesai 2026-10-21
attendance.md GET /attendance/today, GET /attendance/history, POST /attendance/check-in, POST /attendance/check-out selesai 2026-10-21
attendance-corrections.md GET /attendance/corrections, POST /attendance/corrections selesai 2026-10-22
leaves.md GET /leave-types, GET /me/leave-balances, GET /leaves, POST /leaves, GET /leaves/{leave}, POST /leaves/{leave}/cancel selesai 2026-10-22
overtimes.md GET /overtimes, POST /overtimes, GET /overtimes/{overtime}, POST /overtimes/{overtime}/cancel selesai 2026-10-22
reimbursements.md GET /reimbursement-categories, GET /reimbursements, POST /reimbursements, GET /reimbursements/{reimbursement}, POST /reimbursements/{reimbursement}/cancel selesai 2026-10-22
business-trips.md GET /business-trips, POST /business-trips, GET /business-trips/{businessTrip}, POST /business-trips/{businessTrip}/cancel selesai 2026-10-22
client-visits.md GET /clients, GET /client-visits, GET /client-visits/open, POST /client-visits/check-in, GET /client-visits/{clientVisit}, POST /client-visits/{clientVisit}/check-out, POST /client-visits/{clientVisit}/cancel selesai 2026-10-22
approvals.md GET /approvals, GET /approvals/{approval}, POST /approvals/{approval}/approve, POST /approvals/{approval}/reject selesai 2026-10-23
announcements.md GET /announcements, GET /announcements/{announcement} selesai 2026-11-15
push-tokens.md PUT /me/push-token, DELETE /me/push-token selesai 2026-11-15 (penyimpanan token; pengiriman push belum aktif)
timesheets.md GET /timesheets, GET /timesheets/today, GET /timesheets/{timesheet}, POST /timesheets/{timesheet}/submit, POST /timesheet-entries, PUT /timesheet-entries/{timesheetEntry}, DELETE /timesheet-entries/{timesheetEntry} selesai 2026-10-22

Total 62 endpoint. Sapuan HTTP 2026-10-21: seluruhnya merespons tanpa galat server; GET menjawab 200, POST/PUT berbody kosong menjawab 422 validasi, route berparameter dengan ID tidak dikenal menjawab 404.


16. Belum Tersedia

Kebutuhan Status
Pengiriman notifikasi push (FCM) registrasi token sudah ada (push-tokens.md); pengiriman menunggu kredensial Firebase di server