Profil dan Konfigurasi Karyawan

Lihat Markdown

Profil karyawan, konfigurasi aplikasi (me/config), daftar perangkat, ganti kata sandi, dan persetujuan data pribadi. Konvensi umum ada di README.md; login di auth.md.

Atribut Nilai
Endpoint GET /me, GET /me/config, GET /me/devices, PUT /me/password, POST /consents
Sumber kode ProfileController, MobileConfigController + MobileConfigService, DeviceController, PasswordController, ConsentController, ChangePasswordRequest, StoreConsentRequest
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

Seluruh endpoint di berkas ini wajib token (Authorization: Bearer <token>) dan melewati auth:sanctum + EnsureSubscriptionActive.


Enum

EmploymentStatus, WorkPattern, DevicePlatform, dan DeviceStatus ada di auth.md.

SubscriptionStatus (subscription.status)

Nilai status_label is_locked
TRIALING Masa Uji Coba false
ACTIVE Aktif false
PAST_DUE Menunggak true
SUSPENDED Ditangguhkan true
null (tidak dikirim) false, perusahaan tanpa langganan berjalan

CANCELED (Dibatalkan) ada di enum, tetapi langganan berstatus itu tidak dianggap langganan berjalan, sehingga me/config mengirim bentuk status: null dan is_locked: false.

ScheduleStatus (today.status)

Nilai status_label today.message
ON_DUTY Masuk kerja Masuk kerja pada shift {nama shift}. atau, pada hari libur dengan lembur disetujui, Lembur {Hari Libur Mingguan/Hari Libur Nasional} yang sudah disetujui.
OFF_DUTY Libur Tidak dijadwalkan masuk pada tanggal ini.
HOLIDAY Libur nasional Libur: {nama libur}.
NOT_SCHEDULED Tidak dijadwalkan Karyawan tidak mengikuti presensi harian.
NO_SHIFT_PATTERN Belum punya pola shift Karyawan belum memiliki pola shift. Hubungi Admin HR.
INCOMPLETE_PATTERN Pola shift belum lengkap Pola {nama pola} pada hari {hari} belum diisi jam kerja.

Hanya ON_DUTY yang menerima presensi (requires_attendance: true).

OvertimeType (today.overtime_type)

Nilai Label Muncul di today
REST_DAY Hari Libur Mingguan ya, bila hari libur mingguan punya lembur disetujui
HOLIDAY Hari Libur Nasional ya, bila hari libur nasional punya lembur disetujui
BEFORE_SHIFT Sebelum Jam Kerja tidak (overtime_type hanya mengisi lembur hari libur)
AFTER_SHIFT Sesudah Jam Kerja tidak

ClientVisitPurpose (open_client_visit.purpose)

SALES_CALL, PRESENTATION, NEGOTIATION, DELIVERY, MAINTENANCE, COLLECTION, SURVEY, OTHER. Label dan rincian di client-visits.md.


Profil karyawan

GET /me

Deskripsi: mengambil data karyawan pemilik token. Dipanggil saat aplikasi dibuka untuk memastikan token masih berlaku dan memperbarui profil di layar.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive (dikecualikan saat langganan terkunci)
Route name api.v1.me.show

Header: Accept: application/json, Authorization: Bearer <token>

Parameter: tidak ada.

Contoh Request

GET /api/v1/me HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Data karyawan berhasil diambil.",
  "data": {
    "id": 3,
    "employee_number": "EMP-0007",
    "name": "Citra Satu",
    "email": "citra@nusantara-logistik.test",
    "phone": "081234560007",
    "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
  }
}

Field data

Field Tipe Null Keterangan
id integer tidak ID karyawan
employee_number string tidak Nomor Karyawan, unik dalam satu perusahaan
name string tidak nama lengkap
email string ya surel; dibutuhkan untuk lupa kata sandi dan perangkat pinjaman
phone string ya nomor telepon
employment_status string (enum) tidak EmploymentStatus
employment_status_label string tidak label tampilan
work_pattern string (enum) tidak WorkPattern
work_pattern_label string tidak label tampilan
department string ya nama departemen
position string ya nama jabatan
job_level string ya nama jenjang jabatan
must_change_password boolean tidak true → arahkan ke PUT /me/password sebelum fitur lain

Contoh Response Error

Kondisi HTTP message
Token tidak ada, salah, dicabut, atau milik karyawan yang sudah ganti/atur ulang kata sandi 401 Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.
Perusahaan dinonaktifkan pengelola Absenova 403 Perusahaan Anda sedang tidak aktif. Hubungi administrator.
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}

Catatan

  • Isolasi tenant: data selalu milik karyawan pemilik token. Token karyawan borneo-retail mendapat profil BR-0101 Anton Dua dari perusahaannya sendiri (terekam), tidak pernah data perusahaan lain.
  • Idempotency: tidak relevan (GET).
  • Rate limit: tidak ada.
  • FeatureGate / modul: tidak ada.
  • Status langganan: tetap 200 saat langganan terkunci (terekam saat SUSPENDED).

Konfigurasi aplikasi

GET /me/config

Deskripsi: satu paket konfigurasi untuk client: identitas perusahaan, status langganan, saklar modul, kebijakan presensi dan modul lain, lokasi kerja, jadwal hari ini, perjalanan bisnis aktif, dan kunjungan klien yang masih terbuka. Dipanggil setelah login, saat aplikasi dibuka, dan saat kembali ke latar depan.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive (dikecualikan saat langganan terkunci)
Route name api.v1.me.config

Header: Accept: application/json, Authorization: Bearer <token>

Parameter: tidak ada. Seluruh nilai diturunkan dari token dan jam server.

Contoh Request

GET /api/v1/me/config HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, karyawan jam tetap, Rabu 2026-10-21 07:41 WIB)

{
  "success": true,
  "message": "Konfigurasi presensi berhasil diambil.",
  "data": {
    "company": {
      "uuid": "01a15ca1-1f9c-710c-bf21-daafa03f60c9",
      "slug": "nusantara-logistik",
      "name": "Nusantara Logistik",
      "logo_url": null,
      "logo_version": null,
      "timezone": "Asia/Jakarta"
    },
    "subscription": {
      "status": "TRIALING",
      "status_label": "Masa Uji Coba",
      "plan": "Absenova",
      "trial_ends_at": "2026-11-04T04:03:46+00:00",
      "ends_at": "2026-11-04",
      "is_locked": false
    },
    "modules": {
      "module_shift_scheduling": true,
      "module_attendance_correction": true,
      "module_leave": true,
      "module_overtime": true,
      "module_business_trip": true,
      "module_reimbursement": true,
      "module_timesheet": true,
      "module_client_visit": true,
      "module_announcement": false,
      "module_face_matching": false,
      "module_data_export": true
    },
    "policy": {
      "photo_required": true,
      "photo_max_kilobytes": 300,
      "gps_accuracy_threshold_meters": 50,
      "offline_sync_tolerance_hours": 24,
      "business_trip_window_extra_minutes": 180,
      "timesheet": {
        "minimum_entry_minutes": 15,
        "maximum_entry_minutes": 720,
        "max_minutes_per_day": 960,
        "max_backdate_days": 7,
        "entry_from_client_visit": true
      },
      "device_lending": {
        "enabled": true,
        "code_expires_minutes": 10,
        "session_hours": 12,
        "max_usages": 2,
        "max_per_month": 3
      },
      "client_visit": {
        "radius_meters": 300,
        "photo_required": true,
        "photo_max_kilobytes": 500,
        "minimum_duration_minutes": 5,
        "max_open_hours": 12
      },
      "overtime": {
        "minimum_minutes": 30,
        "rounding_minutes": 15,
        "max_minutes_per_day": 240,
        "max_minutes_per_week": 1080,
        "max_backdate_days": 3
      },
      "timezone": "Asia/Jakarta"
    },
    "consent": {
      "policy_version": "2026-10",
      "title": "Persetujuan Pemrosesan Data Pribadi",
      "body": "Untuk mencatat kehadiran, aplikasi ini memproses data pribadi Anda berikut: lokasi GPS beserta tingkat akurasinya, foto wajah saat presensi, waktu pada perangkat, penanda lokasi palsu (mock location), serta pengenal dan nama perangkat yang Anda pakai.\nData tersebut dipakai untuk memverifikasi kehadiran Anda dan memastikan presensi dilakukan di lokasi kerja yang ditetapkan perusahaan.\nPengelola data adalah perusahaan tempat Anda bekerja, yang memprosesnya melalui layanan Absenova. Data presensi Anda dapat dilihat oleh Admin HR perusahaan.\nAnda berhak mengakses, memperbaiki, dan meminta penghapusan data pribadi Anda, serta menarik persetujuan ini, melalui Admin HR perusahaan Anda.\nDengan menekan Setuju, Anda menyatakan telah membaca dan menyetujui pemrosesan data pribadi di atas.",
      "accepted": false,
      "accepted_at": null
    },
    "work_locations": [
      {
        "id": 1,
        "code": "KP-JKT",
        "name": "Kantor Pusat Jakarta",
        "latitude": -6.2087634,
        "longitude": 106.845599,
        "radius_meters": 150
      },
      {
        "id": 2,
        "code": "GD-CKG",
        "name": "Gudang Cakung",
        "latitude": -6.1836102,
        "longitude": 106.9442431,
        "radius_meters": 200
      }
    ],
    "today": {
      "work_date": "2026-10-21",
      "status": "ON_DUTY",
      "status_label": "Masuk kerja",
      "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
      "shift": "Jam Kantor 08:00 - 17:00",
      "starts_at": "2026-10-21T01:00:00+00:00",
      "ends_at": "2026-10-21T10:00:00+00:00",
      "check_in_opens_at": "2026-10-20T23:30:00+00:00",
      "check_out_closes_at": "2026-10-21T12:00:00+00:00",
      "requires_attendance": true,
      "is_overtime": false,
      "overtime_type": null
    },
    "business_trip": null,
    "open_client_visit": null
  }
}

Variasi yang direkam (hanya bagian yang berbeda):

Karyawan sedang perjalanan bisnis dan punya kunjungan klien terbuka (07:41 WIB). Jendela presensi melebar 180 menit (business_trip_window_extra_minutes) ke dua arah:

"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
  "shift": "Jam Kantor 08:00 - 17:00",
  "starts_at": "2026-10-21T01:00:00+00:00",
  "ends_at": "2026-10-21T10:00:00+00:00",
  "check_in_opens_at": "2026-10-20T20:30:00+00:00",
  "check_out_closes_at": "2026-10-21T15:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
},
"business_trip": {
  "id": 1,
  "letter_number": "PB/2026/10/014",
  "destination_name": "Gudang Mitra Surabaya",
  "destination_latitude": -7.241387,
  "destination_longitude": 112.678269,
  "start_date": "2026-10-21",
  "end_date": "2026-10-23",
  "geofence_waived": true,
  "notice": "Presensi hari ini dicatat sebagai perjalanan bisnis. Foto tetap wajib dan koordinat Anda tetap direkam."
},
"open_client_visit": {
  "id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "SALES_CALL",
  "checked_in_at": "2026-10-21T00:15:00+00:00",
  "notice": "Kunjungan klien masih terbuka. Lakukan check-out agar durasinya tercatat."
}

Shift malam 23:00–07:00 (22:30 WIB). work_date tanggal mulai shift, ends_at keesokan harinya:

"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Shift Malam 23:00 - 07:00.",
  "shift": "Shift Malam 23:00 - 07:00",
  "starts_at": "2026-10-21T16:00:00+00:00",
  "ends_at": "2026-10-22T00:00:00+00:00",
  "check_in_opens_at": "2026-10-21T15:00:00+00:00",
  "check_out_closes_at": "2026-10-22T02:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
}

Langganan SUSPENDED (endpoint lain dijawab 402):

"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
}

Perusahaan tanpa langganan berjalan (borneo-retail, WITA), karyawan tanpa lokasi kerja. Objek subscription hanya berisi tiga kunci:

"subscription": {
  "status": null,
  "plan": null,
  "is_locked": false
},
"work_locations": [],
"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
  "shift": "Jam Kantor 08:00 - 17:00",
  "starts_at": "2026-10-21T00:00:00+00:00",
  "ends_at": "2026-10-21T09:00:00+00:00",
  "check_in_opens_at": "2026-10-20T22:30:00+00:00",
  "check_out_closes_at": "2026-10-21T11:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
}

Contoh today untuk hari libur, libur dari Jadwal Kerja, dan lembur hari libur ada di attendance.md (GET /attendance/today memakai penentu jadwal yang sama).

Field data.company (objek)

Field Tipe Null Keterangan
uuid string (UUID) tidak pengenal tetap perusahaan
slug string tidak kode perusahaan
name string tidak nama tampilan
logo_url string (URL) ya URL bertanda tangan, berlaku 120 menit; null bila belum ada logo
logo_version string ya kunci cache logo; berubah bila logo diganti
timezone string (IANA) tidak zona waktu perusahaan untuk menampilkan seluruh timestamp

Field data.subscription (objek, tidak pernah null)

Field Tipe Null Keterangan
status string (enum) ya SubscriptionStatus; null bila tidak ada langganan berjalan
status_label string — hanya ada bila status terisi
plan string ya nama paket, mis. Absenova
trial_ends_at string (ISO 8601 UTC) ya akhir masa uji coba. Hanya ada bila status terisi
ends_at string (YYYY-MM-DD) ya tanggal akhir masa langganan. Hanya ada bila status terisi
is_locked boolean tidak true → seluruh endpoint bertoken selain POST /auth/logout, GET /me, GET /me/config dijawab 402, termasuk presensi. Client menampilkan layar terkunci

Di Kotlin/Gson, jadikan status_label, trial_ends_at, dan ends_at nullable dengan nilai bawaan null agar bentuk tiga kunci tidak memicu galat.

Field data.modules (objek, 11 kunci boolean)

Saklar modul dari paket langganan. Server tidak memblokir endpoint berdasarkan saklar ini; client menyembunyikan menu modul yang false.

Kunci API terkait Keterangan
module_attendance_correction attendance-corrections.md koreksi presensi
module_leave leaves.md cuti dan izin
module_overtime overtimes.md lembur
module_business_trip business-trips.md perjalanan bisnis
module_reimbursement reimbursements.md reimbursement
module_timesheet timesheets.md timesheet
module_client_visit client-visits.md kunjungan klien
module_announcement announcements.md pengumuman perusahaan. Dirilis 2026-11-15; contoh respons di atas direkam sebelum rilis sehingga masih false
module_shift_scheduling tidak ada fitur panel admin; tidak memengaruhi client
module_data_export tidak ada fitur panel admin; tidak memengaruhi client
module_face_matching belum ada Fase 2, belum dirilis; server selalu mengirim false sampai endpoint tersedia, apa pun isi paket

Field data.policy (objek)

Aturan perusahaan untuk validasi awal di client. Server tetap memvalidasi ulang. Nilai pada contoh adalah bawaan perusahaan baru.

Field Tipe Null Bawaan Keterangan
photo_required boolean tidak true photo wajib pada POST /attendance/check-in dan /check-out
photo_max_kilobytes integer tidak 300 batas ukuran photo presensi (KB)
gps_accuracy_threshold_meters integer tidak 50 accuracy_meters di atas nilai ini ditolak, untuk semua pola kerja
offline_sync_tolerance_hours integer tidak 24 captured_at lebih tua dari ini ditolak
business_trip_window_extra_minutes integer tidak 180 pelebaran jendela presensi pada hari perjalanan bisnis, sudah diterapkan ke today
timesheet.minimum_entry_minutes integer tidak 15 durasi minimum satu aktivitas
timesheet.maximum_entry_minutes integer tidak 720 durasi maksimum satu aktivitas
timesheet.max_minutes_per_day integer tidak 960 total menit aktivitas per hari
timesheet.max_backdate_days integer tidak 7 batas mundur tanggal aktivitas
timesheet.entry_from_client_visit boolean tidak true check-out kunjungan klien membuat aktivitas timesheet otomatis
device_lending.enabled boolean tidak true perusahaan mengizinkan presensi lewat perangkat pinjaman
device_lending.code_expires_minutes integer tidak 10 masa berlaku kode izin pinjam
device_lending.session_hours integer tidak 12 masa berlaku sesi pinjam setelah kode diverifikasi
device_lending.max_usages integer tidak 2 jumlah presensi per sesi pinjam
device_lending.max_per_month integer tidak 3 jumlah sesi pinjam per bulan
client_visit.radius_meters integer tidak 300 radius lokasi klien
client_visit.photo_required boolean tidak true foto wajib saat check-in kunjungan
client_visit.photo_max_kilobytes integer tidak 500 batas ukuran foto kunjungan (KB)
client_visit.minimum_duration_minutes integer tidak 5 durasi minimum kunjungan
client_visit.max_open_hours integer tidak 12 kunjungan terbuka lebih lama dari ini ditutup sistem
overtime.minimum_minutes integer tidak 30 durasi minimum pengajuan lembur
overtime.rounding_minutes integer tidak 15 pembulatan menit lembur
overtime.max_minutes_per_day integer tidak 240 batas lembur per hari
overtime.max_minutes_per_week integer tidak 1080 batas lembur per minggu
overtime.max_backdate_days integer tidak 3 batas mundur tanggal pengajuan lembur
timezone string (IANA) tidak Asia/Jakarta sama dengan company.timezone

Field data.work_locations (array, boleh kosong)

Lokasi kerja aktif yang ditugaskan ke karyawan. Array kosong berarti presensi ditolak (Karyawan belum ditugaskan pada lokasi presensi mana pun. Hubungi Admin HR.) kecuali pola REMOTE atau hari perjalanan bisnis.

Field Tipe Null Keterangan
id integer tidak ID lokasi
code string tidak kode lokasi
name string tidak nama lokasi, muncul di attendance.work_location
latitude number tidak lintang desimal
longitude number tidak bujur desimal; nol di belakang koma tidak dikirim (106.845599)
radius_meters integer tidak radius geofence. Presensi sah bila jarak - accuracy_meters <= radius_meters

Field data.today (objek, tidak pernah null)

Field Tipe Null Keterangan
work_date string (YYYY-MM-DD) tidak tanggal kerja menurut kalender perusahaan; untuk shift malam adalah tanggal mulai shift
status string (enum) tidak ScheduleStatus
status_label string tidak label tampilan
message string tidak kalimat siap tampil, lihat tabel ScheduleStatus
shift string ya nama shift; null bila tidak masuk kerja atau pada lembur hari libur
starts_at string (ISO 8601 UTC) ya mulai shift atau mulai lembur hari libur
ends_at string (ISO 8601 UTC) ya akhir shift atau akhir lembur hari libur
check_in_opens_at string (ISO 8601 UTC) ya awal jendela presensi, dihitung resolver yang sama dengan pemeriksaan OUTSIDE_WINDOW: sudah termasuk pelebaran perjalanan bisnis atau lembur BEFORE_SHIFT/AFTER_SHIFT yang disetujui (yang terbesar). Nilainya sama dengan GET /attendance/today → check_in_opens_at
check_out_closes_at string (ISO 8601 UTC) ya akhir jendela presensi, aturan sama dengan check_in_opens_at
requires_attendance boolean tidak true hanya bila status = ON_DUTY
is_overtime boolean tidak true bila presensi hari ini adalah lembur hari libur yang disetujui
overtime_type string (enum) ya REST_DAY atau HOLIDAY bila is_overtime, selain itu null

Field data.business_trip (objek atau null)

Terisi bila hari ini termasuk perjalanan bisnis yang disetujui.

Field Tipe Null Keterangan
id integer tidak ID perjalanan bisnis
letter_number string ya nomor surat tugas
destination_name string tidak nama tujuan
destination_latitude number ya lintang tujuan
destination_longitude number ya bujur tujuan
start_date string (YYYY-MM-DD) tidak tanggal mulai
end_date string (YYYY-MM-DD) tidak tanggal selesai
geofence_waived boolean tidak selalu true: radius lokasi kerja tidak diperiksa
notice string tidak kalimat siap tampil

Field data.open_client_visit (objek atau null)

Terisi bila karyawan punya kunjungan klien berstatus berjalan.

Field Tipe Null Keterangan
id integer tidak ID kunjungan, untuk POST /client-visits/{id}/check-out
client_name string tidak nama klien
purpose string (enum) tidak ClientVisitPurpose
checked_in_at string (ISO 8601 UTC) tidak waktu check-in kunjungan
notice string tidak kalimat siap tampil

Field data.consent (objek, tidak pernah null)

Kebijakan persetujuan data pribadi (UU 27/2022 PDP) yang aktif dan status persetujuan karyawan login untuk versi itu. Versi dan teks dikelola pengelola Absenova di panel platform dan berlaku tanpa rilis aplikasi.

Field Tipe Null Keterangan
policy_version string tidak versi aktif, mis. 2026-10. Kirim nilai ini apa adanya ke POST /consents
title string tidak judul layar persetujuan
body string tidak isi kebijakan, teks polos tanpa HTML; paragraf dipisah satu karakter \n
accepted boolean tidak true bila karyawan sudah menyetujui versi aktif. Persetujuan versi lama tidak dihitung
accepted_at string (ISO 8601 UTC) ya waktu persetujuan versi aktif; null bila accepted false

Saat versi aktif diganti, accepted kembali false untuk seluruh karyawan sampai mereka menyetujui versi baru. Contoh sesudah versi 2026-11 diaktifkan (karyawan baru menyetujui 2026-10):

{
  "policy_version": "2026-11",
  "title": "Persetujuan Pemrosesan Data Pribadi",
  "body": "Untuk mencatat kehadiran, aplikasi ini memproses lokasi GPS dan akurasinya, foto wajah, waktu perangkat, penanda lokasi palsu, serta pengenal dan nama perangkat.\nData dipakai untuk memverifikasi kehadiran dan lokasi kerja. Foto presensi disimpan paling lama 12 bulan.\nPengelola data adalah perusahaan Anda melalui Absenova; data dapat dilihat Admin HR.\nAnda dapat meminta akses, perbaikan, penghapusan, atau menarik persetujuan melalui Admin HR.",
  "accepted": false,
  "accepted_at": null
}

Contoh Response Error

Kondisi HTTP message
Token tidak sah 401 Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.
Perusahaan dinonaktifkan pengelola Absenova 403 Perusahaan Anda sedang tidak aktif. Hubungi administrator.
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}

Catatan

  • Jendela waktu today sama dengan aturan server pada saat request, termasuk pelebaran lembur sebelum/sesudah jam kerja dan perjalanan bisnis. Karena me/config boleh di-cache, ambil jendela terbaru dari GET /attendance/today saat membuka layar presensi. Client tetap tidak memblokir tombol berdasarkan jam perangkat; kirim presensi dan tampilkan message bila ditolak.
  • today dihitung dari jam server saat request. Shift malam yang sedang berjalan setelah tengah malam tetap menampilkan work_date tanggal mulai shift selama jendela presensinya masih terbuka.
  • Cache: company, modules, dan policy boleh di-cache. today, business_trip, dan open_client_visit berubah sepanjang hari; ambil ulang saat aplikasi kembali ke latar depan. consent dapat berubah kapan saja saat versi aktif diganti; periksa setiap kali me/config diambil.
  • Idempotency: tidak relevan (GET).
  • Rate limit: tidak ada.
  • FeatureGate / modul: endpoint ini sumber saklar modul.
  • Status langganan: tetap 200 saat langganan terkunci; baca subscription.is_locked.

Daftar perangkat

GET /me/devices

Deskripsi: daftar perangkat yang pernah didaftarkan karyawan, terbaru di atas. Dipakai layar pengaturan untuk menunjukkan perangkat aktif dan perangkat yang menunggu persetujuan atau sudah dicabut.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.me.devices

Header: Accept: application/json, Authorization: Bearer <token>

Parameter: tidak ada.

Contoh Request

GET /api/v1/me/devices HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Daftar perangkat berhasil diambil.",
  "data": [
    {
      "id": 2,
      "device_identifier": "b3d0e8f1-samsung-a55-citra",
      "device_name": "Samsung Galaxy A55",
      "platform": "ANDROID",
      "status": "REVOKED",
      "status_label": "Dicabut",
      "approved_at": null,
      "last_used_at": null
    },
    {
      "id": 1,
      "device_identifier": "6f1c2a9e-4b7d-4e21-9a51-citra-pixel8",
      "device_name": "Google Pixel 8",
      "platform": "ANDROID",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "approved_at": "2026-10-21T00:40:00+00:00",
      "last_used_at": "2026-10-21T00:41:00+00:00"
    }
  ]
}

Field data[]

Field Tipe Null Keterangan
id integer tidak ID perangkat
device_identifier string tidak pengenal yang dikirim saat login
device_name string ya nama perangkat
platform string (enum) tidak DevicePlatform
status string (enum) tidak DeviceStatus
status_label string tidak label tampilan
approved_at string (ISO 8601 UTC) ya null bila belum pernah disetujui
last_used_at string (ISO 8601 UTC) ya login terakhir; null bila belum pernah berhasil login

Contoh Response Error

Kondisi HTTP message
Token tidak sah 401 Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.
Langganan terkunci 402 Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.
{
  "success": false,
  "message": "Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.",
  "errors": {}
}

Catatan

  • Untuk mengenali perangkat sendiri, bandingkan device_identifier dengan nilai yang disimpan client.
  • Pada contoh, Samsung Galaxy A55 tercatat saat login ditolak (PENDING) lalu dicabut Admin HR (REVOKED), sehingga approved_at tetap null.
  • Client tidak dapat menghapus atau mengganti perangkat; penggantian lewat persetujuan Admin HR.
  • Idempotency: tidak relevan (GET).
  • Rate limit: tidak ada.
  • FeatureGate / modul: tidak ada.
  • Status langganan: terkunci → 402.

Ganti kata sandi

PUT /me/password

Deskripsi: mengganti kata sandi dengan memasukkan kata sandi lama. Wajib dipanggil bila must_change_password bernilai true. Setelah berhasil, seluruh token karyawan dicabut, termasuk token yang dipakai request ini.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.me.password

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

Parameter

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
current_password body string ya required, string; dicocokkan dengan kata sandi saat ini di Controller
password body string ya required, string, confirmed, minimal 8 karakter
password_confirmation body string ya wajib sama dengan password

Contoh Request

PUT /api/v1/me/password HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_password": "Rahasia123!",
  "password": "SandiBaru2026",
  "password_confirmation": "SandiBaru2026"
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Kata sandi berhasil diperbarui. Silakan masuk kembali.",
  "data": {}
}

Field data: objek kosong {}.

Contoh Response Error

Kondisi HTTP message
Validasi gagal 422 Data yang dikirim tidak lolos pemeriksaan.
Kata sandi lama salah 422 Kata sandi lama tidak sesuai. (errors.current_password)
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. ...

Validasi (password: "pendek", password_confirmation: "lain"):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": [
      "Konfirmasi kata sandi baru tidak cocok.",
      "Kolom kata sandi baru minimal 8 karakter."
    ]
  }
}

Kata sandi lama salah:

{
  "success": false,
  "message": "Kata sandi lama tidak sesuai.",
  "errors": {
    "current_password": [
      "Kata sandi lama tidak sesuai."
    ]
  }
}

Catatan

  • Setelah 200, token yang sama langsung dijawab 401 (terekam). Client menghapus token lokal dan membuka layar login. must_change_password menjadi false.
  • Idempotency: tidak ada. Panggilan kedua dengan token lama dijawab 401.
  • Rate limit: tidak ada.
  • FeatureGate / modul: tidak ada.
  • Status langganan: terkunci → 402. Karyawan dengan must_change_password: true di perusahaan yang terkunci tidak dapat mengganti kata sandi sampai tagihan dilunasi.

Persetujuan data pribadi

POST /consents

Deskripsi: mencatat persetujuan karyawan atas pemrosesan data pribadi (UU 27/2022 PDP) untuk versi kebijakan yang aktif. Teks dan versi dibaca dari GET /me/config → consent. Dipanggil dari layar persetujuan bila consent.accepted bernilai false.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.consents.store

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

Parameter

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
policy_version body string ya required, string, max:50, in:{versi aktif}. Wajib sama dengan me/config → consent.policy_version; versi lain ditolak 422
accepted body boolean ya required, accepted: hanya true, 1, "1", "yes", "on", "true" yang lolos

Contoh Request

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

{
  "policy_version": "2026-10",
  "accepted": true
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Persetujuan tercatat.",
  "data": {
    "policy_version": "2026-10",
    "consented_at": "2026-10-21T00:41:00+00:00"
  }
}

Field data

Field Tipe Null Keterangan
policy_version string tidak versi yang dicatat
consented_at string (ISO 8601 UTC) tidak waktu persetujuan menurut server

Contoh Response Error

Kondisi HTTP message
accepted bernilai false atau kosong, policy_version kosong 422 Data yang dikirim tidak lolos pemeriksaan.
policy_version bukan versi aktif 422 Data yang dikirim tidak lolos pemeriksaan., errors.policy_version: Versi kebijakan ini sudah tidak berlaku. Muat ulang kebijakan terbaru lalu setujui kembali.
Token tidak sah 401 Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.
Langganan terkunci 402 Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. ...
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "accepted": [
      "Kolom persetujuan wajib disetujui."
    ]
  }
}

Versi lama sesudah versi 2026-11 diaktifkan (policy_version: "2026-10"):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "policy_version": [
      "Versi kebijakan ini sudah tidak berlaku. Muat ulang kebijakan terbaru lalu setujui kembali."
    ]
  }
}

Catatan

  • Penolakan tidak dikirim ke server. Bila karyawan menolak, client tidak memanggil endpoint ini.
  • Sumber kebenaran di server. Status ada di me/config → consent.accepted; jangan memakai teks atau versi yang tertanam di aplikasi. Sesudah 200, panggil ulang GET /me/config atau anggap accepted true untuk versi yang baru dikirim.
  • Bila respons 422 errors.policy_version, versi aktif sudah berganti: muat ulang me/config, tampilkan teks baru, lalu kirim versi baru.
  • Server belum mewajibkan consent sebelum presensi: presensi tetap diterima walau accepted false. Penegakan sedang menunggu keputusan pemilik produk (lihat README bagian 13).
  • Idempotency: satu catatan per karyawan per policy_version. Mengirim ulang versi yang sama memperbarui consented_at, tidak membuat catatan ganda.
  • Rate limit: tidak ada.
  • FeatureGate / modul: tidak ada.
  • Status langganan: terkunci → 402.