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/passwordmencabut 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-tokentidak boleh menghalangi pemakaian aplikasi. Coba lagi pada pembukaan aplikasi berikutnya. - Isi notifikasi dan halaman tujuan (deep link) akan didokumentasikan saat pengiriman push diaktifkan.