Dokumentasi API (format Postman)

Login tidak diproses di HP. Semua kredensial lewat backend agar bebas CORS dan server auth tidak pernah diekspos ke client.

1. MOBILE kirim POST /api/auth/login berisi username + password.
2. Laravel memanggil POST http://myauth.kuroichi.my.id/apisisdm/api/apps/sign sebagai multipart id + paswd.
3. Login sukses bila status = "success" dan ada bearer.access_token dari server auth (bukan login_result.code).
4. Laravel memetakan profil dari data_pegawai_sisdm (fallback login_result) dan mengambil absensi dari absensi_sikap; hanya employees yang di-upsert.
5. Laravel membuat baris auth_sessions (hash token) dan mengembalikan Bearer token dari objek bearer.
6. MOBILE menyimpan token di localStorage dan mengirim Authorization: Bearer <access_token> untuk semua request berikutnya.

Multi-login: login kedua dari perangkat lain membuat baris/token baru. Logout hanya mencabut token yang dipakai, token perangkat lain tetap aktif.

Cek status: saat app dibuka, mobile memanggil /auth/userinfo; backend memvalidasi Bearer token ke GET /apisisdm/api/apps/me (sekaligus memperpanjang masa aktif 30 hari). Profil dan absensi ikut segar. Bila server auth tak terjangkau, sesi lokal dipertahankan; bila token ditolak (401), sesi dicabut dan app logout.

Konfigurasi URL login: backend memakai APP_LOGIN_URL di framework/.env (otomatis di-inject ke preview /mobile). Build APK memakai VITE_LOGIN_URL di MOBILE/.env; jika kosong, dipakai VITE_API_URL + /auth/login.

Semua respons sukses mengandung success:true (kecuali /health). Error selalu {"error":"<pesan>"} + HTTP code sesuai tabel.

Admin token = token server (.env API_TOKEN) untuk Admin Panel & kirim. Access token = token dari POST /auth/login, disimpan di tabel auth_sessions (SHA-256). Satu akun boleh login di banyak perangkat; logout hanya mematikan token yang dipakai.

Alur: MOBILE → POST {{baseUrl}}/auth/login → backend → POST http://myauth.kuroichi.my.id/apisisdm/api/apps/sign. Mobile tidak pernah memanggil server auth langsung (CORS + kredensial aman).

POST {{baseUrl}}/auth/login

{
  "username": "dummy001",
  "password": "password"
}

✅ 200 Berhasil:

{
  "success": true,
  "access_token": "1509133|C8PytmNhnGkO79TlsUZh0zl6Ipn7KUdDTRlAY87w",
  "token": "1509133|C8PytmNhnGkO79TlsUZh0zl6Ipn7KUdDTRlAY87w",
  "tokens": { "access_token": "...", "token_type": "Bearer", "expires_in": null },
  "user": {
    "nup": "1990012026013357",
    "nama": "TAUFAN MAULANA HARIES",
    "user_id": "taufan",
    "username": "taufan",
    "unit_kerja": "SUBBAGIAN SISTEM INFORMASI SUMBER DAYA MANUSIA",
    "jabatan": "ANALIS SISTEM INFORMASI",
    "status_pegawai": "NON",
    "role_id": 10
  },
  "absensi_sikap": { "jam_masuk": "07:14:01", "jam_keluar": null }
}

Pemetaan field server auth (acuan utama data_pegawai_sisdm):

Email tidak dipakai dan tidak ada kolomnya di database.

❌ 401 Gagal — code "01" (user/password salah):

{ "error": "User ID atau password salah" }

❌ 422 Gagal — field kosong:

{ "error": "User ID dan password wajib diisi" }

❌ 429 Gagal — terlalu banyak percobaan (code "03"):

{ "error": "Terlalu banyak percobaan login, coba lagi nanti" }

GET {{baseUrl}}/auth/userinfo

Auth: Bearer {{access_token}}

Dipakai mobile saat halaman beranda (absensi) dibuka untuk mengecek status login: Bearer token divalidasi ke GET /apisisdm/api/apps/me, profil + absensi diperbarui, dan masa aktif token diperpanjang (sliding 30 hari). Tidak dipanggil dari polling notifikasi/background service. Bila server auth tak terjangkau, profil lokal tetap dipakai; token ditolak → 401 dan sesi lokal dicabut.

✅ 200 Berhasil: {"success":true,"user":{...},"absensi_sikap":{"jam_masuk":"08:00","jam_keluar":null}}

POST {{baseUrl}}/auth/refresh

Sama dengan /auth/userinfo (validasi ke /me), ditambah tokens berisi Bearer token yang sama.

{ "access_token": "{{access_token}}" }

✅ 200: {"success":true,"tokens":{...},"user":{...}} · ❌ 401: {"error":"Sesi berakhir, silakan login ulang"}

POST {{baseUrl}}/auth/logout

Auth: Bearer {{access_token}}

Cabut token yang dipakai saja. Token lain milik akun yang sama tetap aktif (multi-login).

✅ 200: {"success":true}

❌ 401: {"error":"Token akses tidak valid"}

Setiap login menyimpan satu baris di auth_sessions. Token asli hanya dikirim ke client satu kali; database menyimpan hash-nya.

Contoh: HP A dan HP B login akun yang sama → dua token berbeda. Logout di HP A hanya mengisi revoked_at token A; HP B tetap bisa memakai token B.

Validasi token: Authorization: Bearer <token> → hash → cari baris dengan revoked_at = null. Tidak valid/revoked → 401, app logout.

GET {{baseUrl}}/health

Publik, tanpa auth. Dipakai mobile untuk status server aktif/tidak.

✅ 200 Berhasil:

{ "status": "ok", "timestamp": "2026-10-05T08:38:44+00:00" }

GET {{baseUrl}}/app-config

Publik. Konfigurasi client dari server: interval polling (menit). Mobile menyimpannya di localStorage. Diatur dari Admin Panel → Konfigurasi → Polling Notifikasi; fallback APP_POLL_INTERVAL_MINUTES di framework/.env.

{
  "status": "ok",
  "poll_interval_minutes": 1,
  "server_time": "2026-10-26T01:15:00+07:00"
}

POST {{baseUrl}}/register

Auth: Bearer {{api_token}}

{
  "device_id": "test-device-001",
  "device_name": "HP Test",
  "platform": "android"
}

✅ 200 Berhasil: {"success":true}

❌ 401 Gagal — token salah/kosong: {"error":"Unauthorized"}

❌ 400 Gagal — device_id kosong: {"error":"device_id required"}

GET {{baseUrl}}/apk/info

Publik. Info APK yang tersedia di public/apk/ (nama, ukuran, waktu update).

{ "apk": { "file": "AppNotifikasi-debug.apk", "size_mb": 8.14, "updated_at": "..." } }

Alur sama dengan halaman /admin: Kirim pakai server token (2 mode: Semua Device / NUP Tertentu), Tarik pakai access token (NUP dari sesi).

A. Kirim Notifikasi (Admin Panel · server token)

POST {{baseUrl}}/notifications/broadcast — Tujuan: Semua Device

Auth: Bearer {{api_token}} (server token) · setara pilihan "Semua Device" di Admin

{
  "title": "Pengumuman",
  "body": "Untuk semua device"
}

✅ 201 Berhasil:

{
  "success": true,
  "notification_id": 5,
  "devices_targeted": 3
}

Di log Admin: target_summary = "Semua Device", is_broadcast = 1.

❌ 400 Gagal — title/body kosong: {"error":"title and body required"}

❌ 401 Gagal — token bukan access token/admin: {"error":"Unauthorized"}

POST {{baseUrl}}/notifications/broadcast — Tujuan: NUP Tertentu

Auth: Bearer {{api_token}} (server token) · setara pilihan "NUP Tertentu" di Admin

Di Admin, NUP diambil dari upload Excel/CSV kolom NUPNIP atau ketik manual (pisah koma/baris). Semua NUP terkirim — termasuk yang belum terdaftar di Data Pegawai (dikirim langsung berdasarkan NUP).

{
  "title": "Khusus",
  "body": "Hanya NUP terpilih",
  "link": "https://example.com/doc.pdf",
  "target_nups": ["199001010000000001"]
}

✅ 201 Berhasil:

{
  "success": true,
  "notification_id": 6,
  "devices_targeted": 1
}

Di log Admin: target_summary = "NUP Bulk (1)", target_nups_total = 1.

Catatan: API juga menerima device_ids, unit_kerja, jabatan untuk kebutuhan lanjutan (di luar UI Admin). Endpoint POST /notifications tersedia untuk kirim satu pesan dengan body yang sama (tanpa is_broadcast).

B. Tarik di Mobile (NUP-locked · access token)

GET {{baseUrl}}/notifications

Auth: Bearer {{access_token}} · NUP diambil dari token

Hanya broadcast (is_broadcast) atau NUP dikunci untuk user. Device terima target_nups_count (bukan daftar). Retensi 6 bulan.

✅ 200 Berhasil:

{
  "notifications": [
    {
      "id": 1,
      "title": "Uji Notifikasi Laravel",
      "body": "Server Laravel",
      "link": "https://example.com/dokumen.pdf",
      "is_broadcast": 1,
      "acknowledged": 0,
      "target_nups_count": 0,
      "created_at": "2026-10-05 10:51:27",
      "updated_at": "2026-10-05 10:51:27"
    }
  ],
  "count": 1
}

❌ 400 Gagal — tanpa device_id/token/nup:

{
  "error": "device_id, employee_token or nup required"
}

GET {{baseUrl}}/notifications/:id

Detail + target_summary. 404 bila bukan target / lebih tua 6 bulan.

✅ 200 Berhasil: {"notification":{...,"target_summary":"Semua Device","acknowledged":1}}

❌ 404 Gagal — bukan target / id tak ada: {"error":"Not found"}

POST {{baseUrl}}/notifications/:id/acknowledge

{
  "nup": "{{nup}}"
}

✅ 200 Berhasil: {"success":true}

❌ 401 Gagal — token bukan pegawai & bukan admin: {"error":"Unauthorized"}

❌ 400 Gagal — device_id kosong: {"error":"device_id required"}

C. Kelola (Admin · server token)

DELETE {{baseUrl}}/notifications/:id — soft delete

Sembunyi dari device, badge di Admin. Pulihkan via POST {{baseUrl}}/notifications/:id/restore

✅ 200 Berhasil: {"success":true} · ❌ 404: {"error":"Not found"}

GET {{baseUrl}}/admin/notifications

Log full (tanpa retensi): targets_count, target_summary, daftar NUP max 200 + target_nups_total.

GET {{baseUrl}}/admin/devices  ·  GET {{baseUrl}}/admin/stats

GET {{baseUrl}}/admin/settings

Auth: Bearer {{api_token}}

✅ 200: {"settings":{"poll_interval_minutes":1}}

POST {{baseUrl}}/admin/settings — simpan polling

Auth: Bearer {{api_token}}

{ "poll_interval_minutes": 5 }

✅ 200: {"success":true,"settings":{"poll_interval_minutes":5}} · ❌ 422: nilai harus 1-1440 menit

GET {{baseUrl}}/admin/sessions?nup={{nup}}

Auth: Bearer {{api_token}}

Daftar sesi login per pegawai (max 200): device_uuid, ip_address, user_agent, last_used_at, revoked_at, active. Tanpa nup = semua sesi.

POST {{baseUrl}}/admin/sessions/:id/revoke — logout 1 sesi

Auth: Bearer {{api_token}}

✅ 200: {"success":true} · ❌ 404: {"error":"Not found"}

POST {{baseUrl}}/admin/sessions/revoke-user — logout semua sesi user

Auth: Bearer {{api_token}}

{ "nup": "{{nup}}" }

✅ 200: {"success":true,"revoked":2} · ❌ 400: {"error":"nup or employee_id required"}

Di Admin Panel: tombol 🔑 pada baris pegawai → modal Sesi Login → tombol Logout per sesi atau Logout Semua. Token yang dicabut langsung dapat 401 di request berikutnya (mobile auto-logout).

GET {{baseUrl}}/employees  ·  GET {{baseUrl}}/employees?nup={{nup}}

Access token → hanya data diri sendiri. Admin token → semua + filter nup/search.

✅ 200 Berhasil: {"employees":[{...,"token":"ef105f..."}],"count":1} · ❌ 401: {"error":"Unauthorized"}

POST {{baseUrl}}/employees — tambah (token auto)

{
  "nama": "Budi Santoso",
  "nup": "12345",
  "username": "budi",
  "unit_kerja": "IT",
  "jabatan": "Staff",
  "status_pegawai": "Aktif"
}

✅ 201 Berhasil: {"success":true,"id":1,"token":"a1b2c3..."}

❌ 400 Gagal — nama/nup kosong: {"error":"nama and nup required"}

PUT {{baseUrl}}/employees  ·  DELETE {{baseUrl}}/employees

PUT:    { "id": 1, "jabatan": "Supervisor" }
DELETE: { "id": 1 }

✅ 200 Berhasil: {"success":true} · ❌ 400: {"error":"id required"} · ❌ 404: {"error":"Not found"}

POST {{baseUrl}}/employees/:id/regenerate-token

Rotate token tak memutus kiriman (fetch kunci NUP).

✅ 200 Berhasil: {"success":true,"token":"token-baru..."} · ❌ 404: {"error":"Not found"}

Absensi hari ini dibaca langsung dari objek absensi_sikap.data di server auth (jam_masuk/jam_keluar) memakai Bearer token yang sama. Tidak ada tabel attendances dan data tidak disimpan di database.

GET {{baseUrl}}/attendance/today

Auth: Bearer {{access_token}} (self)

✅ 200: {"attendance":{"jam_masuk":"08:00","jam_keluar":null},"status":"Sudah Masuk","tanggal":"2026-10-25"}

❌ 401: Bearer token tidak valid / sudah logout · ❌ 502: server auth tidak terjangkau

POST {{baseUrl}}/test/notification — dummy broadcast

{"title":"Uji Coba","body":"Pesan dummy"}

POST {{baseUrl}}/test/reset — bersihkan

Default 3 tabel (notifications, device_notifications, notification_nups). employees/devices aman — kecuali kirim {"tables":["all"]} (semua 6 tabel termasuk auth_sessions, semua token hangus, HP wajib login ulang).

{}

# Reset SEMUA tabel (bahaya):
{"tables":["all"]}

Alur test cepat (urutan Postman)

1. POST /auth/login  {"username":"dummy001","password":"password"}
2. GET  /auth/userinfo        (Bearer access_token)
3. POST /test/notification {}
4. GET  /notifications        (Bearer access_token)
5. POST /auth/logout          (Bearer access_token)