Token Notifikasi Push

Lihat Markdown

Pendaftaran token Firebase Cloud Messaging (FCM) milik instalasi aplikasi, supaya server nanti dapat mengirim notifikasi push ke karyawan yang sedang login. Konvensi umum ada di README.md.

Atribut Nilai
Endpoint PUT /me/push-token, DELETE /me/push-token
Sumber kode PushTokenController, RegisterPushTokenRequest, PushTokenResource, PushTokenService, model PushToken (tabel push_tokens)
Contoh direkam 2026-11-15 21:05 WIB, HTTP kernel Laravel, basis data MySQL sekali pakai berisi dua perusahaan (nusantara-logistik WIB, borneo-retail WITA), APP_LOCALE=id
Data uji Token FCM di contoh adalah string uji berformat FCM, bukan token perangkat sungguhan

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

Status pengiriman: server baru menyimpan token. Pengiriman notifikasi push belum aktif karena kredensial Firebase (service account) belum dipasang di server. Aplikasi tetap wajib mendaftarkan token sekarang agar pengiriman langsung berjalan begitu server siap, tanpa rilis aplikasi baru.


Kapan client memanggil

Peristiwa di aplikasi Panggilan
Login berhasil (termasuk login perangkat pinjaman) PUT /me/push-token dengan token FCM saat ini
FirebaseMessagingService.onNewToken() selama masih login PUT /me/push-token dengan token baru
Pengguna mematikan notifikasi di pengaturan aplikasi DELETE /me/push-token
Logout cukup POST /auth/logout; token push ikut terhapus di server

Token push terikat ke token login (Sanctum) yang dipakai saat mendaftar, bukan ke karyawan secara umum. Akibatnya:

  • Logout, ganti kata sandi (PUT /me/password mencabut seluruh token login), login ulang di perangkat yang sama, dan berakhirnya perangkat pinjaman otomatis menghapus token push sesi itu. Karena itu client wajib mendaftar ulang setiap kali login.
  • Satu sesi login menyimpan satu token push. Mendaftar lagi mengganti token sebelumnya.
  • Bila token FCM yang sama didaftarkan dari sesi lain di perusahaan yang sama (aplikasi yang sama dipakai karyawan lain, mis. perangkat pinjaman), baris lama dihapus. Notifikasi karyawan sebelumnya tidak pernah sampai ke orang yang kini memegang perangkat.

Daftarkan token

PUT /me/push-token

Deskripsi: menyimpan atau mengganti token FCM untuk sesi login saat ini. Idempoten: mengirim token yang sama berulang kali tetap menghasilkan satu baris.

Auth & Middleware
Token ya
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.me.push-token.update

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

Parameter (RegisterPushTokenRequest)

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
token body string ya required, min:20, max:512, hanya huruf, angka, _, :, -
app_version body string tidak nullable, max:50. Tidak dikirim berarti null (nilai lama diganti)

Contoh Request

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

{
  "token": "eXm3Qd1RTPa9vK2LzA7bYc:APA91bHXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-ZqXy9_-Zq",
  "app_version": "1.0.0"
}

Contoh Response Sukses (200, 2026-11-15 21:05 WIB)

{
  "success": true,
  "message": "Token notifikasi tersimpan.",
  "data": {
    "app_version": "1.0.0",
    "registered_at": "2026-11-15T14:05:55+00:00"
  }
}

Field data

Field Tipe Null Keterangan
app_version string ya nilai app_version dari request terakhir
registered_at string ISO 8601 UTC tidak waktu pendaftaran terakhir

Token FCM sendiri tidak dikirim balik.

Contoh Response Gagal

Body kosong (422):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "token": [
      "Kolom token notifikasi wajib diisi."
    ]
  }
}

Format token salah, {"token": "bukan token fcm!"} (422):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "token": [
      "Kolom token notifikasi minimal 20 karakter.",
      "Format token notifikasi tidak dikenali."
    ]
  }
}

Tanpa token login (401):

{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}

Langganan perusahaan terkunci: 402, lihat README bagian 5.1.


Hapus token

DELETE /me/push-token

Deskripsi: menghapus token FCM sesi login saat ini. Sesi login tetap berlaku. Idempoten: memanggil saat belum ada token tetap dijawab 200.

Auth & Middleware
Token ya
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.me.push-token.destroy

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

Parameter: tidak ada.

Contoh Request

DELETE /api/v1/me/push-token HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, 2026-11-15 21:05 WIB)

{
  "success": true,
  "message": "Token notifikasi dihapus.",
  "data": {}
}

Contoh Response Gagal: 401 dan 402 sama dengan PUT /me/push-token.


Catatan untuk Client

  • Jangan menyimpan status "sudah terdaftar" di perangkat lintas login. Setiap login adalah sesi baru dan wajib mendaftar ulang.
  • Kegagalan PUT /me/push-token tidak boleh menghalangi pemakaian aplikasi. Coba lagi pada pembukaan aplikasi berikutnya.
  • Isi notifikasi dan halaman tujuan (deep link) akan didokumentasikan saat pengiriman push diaktifkan.