Pengumuman perusahaan untuk karyawan. Admin HR membuat pengumuman di panel (Pengumuman), menentukan masa tayang, dan dapat menyematkannya di urutan teratas. Aplikasi menampilkan pengumuman yang sedang tayang dan menandainya dibaca saat dibuka. Konvensi umum ada di README.md.
| Atribut | Nilai |
|---|---|
| Endpoint | GET /announcements, GET /announcements/{announcement} |
| Sumber kode | AnnouncementController, AnnouncementResource, AnnouncementService, model Announcement dan AnnouncementRead, panel App\Filament\App\Resources\Announcements |
| Saklar modul | me/config → modules.module_announcement. Server tidak memblokir endpoint berdasarkan saklar ini (README bagian 12) |
| Contoh direkam | 2026-11-15 21:12 WIB, HTTP kernel Laravel, basis data MySQL sekali pakai berisi dua perusahaan (nusantara-logistik WIB, borneo-retail WITA), APP_LOCALE=id. Pengumuman Libur Bersama Akhir Tahun dibuat lewat formulir panel (permintaan Livewire nyata) |
Seluruh endpoint di berkas ini wajib token (Authorization: Bearer <token>) dan melewati
auth:sanctum + EnsureSubscriptionActive.
Masa Tayang
| Keadaan (panel) | Syarat | Tampil di API |
|---|---|---|
| Terjadwal | published_at di masa depan |
tidak; detail dijawab 404 |
| Tayang | published_at sudah lewat dan expires_at kosong atau belum lewat |
ya |
| Berakhir | expires_at sudah lewat |
tidak; detail dijawab 404 |
| Dihapus | dihapus Admin HR di panel | tidak; detail dijawab 404 |
Pengumuman berlaku untuk seluruh karyawan perusahaan. Belum ada penargetan per departemen.
Daftar pengumuman
GET /announcements
Deskripsi: pengumuman yang sedang tayang di perusahaan karyawan login. Urutan: disematkan lebih dulu,
lalu published_at terbaru, lalu id terbesar. Maksimal 50 item, tanpa pagination.
| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.announcements.index |
Header: Accept: application/json, Authorization: Bearer <token>
Parameter: tidak ada.
Contoh Request
GET /api/v1/announcements HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-15 21:12 WIB, karyawan Anton Satu, nusantara-logistik)
{
"success": true,
"message": "Daftar pengumuman berhasil diambil.",
"data": [
{
"id": 2,
"title": "Libur Bersama Akhir Tahun",
"body": "Kantor tutup 24-26 Desember 2026.\n\nPresensi dibuka kembali 28 Desember.",
"is_pinned": true,
"is_read": false,
"published_at": "2026-11-15T13:00:00+00:00",
"expires_at": "2026-12-31T16:59:00+00:00"
},
{
"id": 4,
"title": "Jadwal Pemeriksaan Kesehatan",
"body": "Pemeriksaan kesehatan tahunan dilaksanakan 2 Desember 2026 di ruang serbaguna.\n\nBawa kartu BPJS Kesehatan.",
"is_pinned": false,
"is_read": false,
"published_at": "2026-11-13T14:12:10+00:00",
"expires_at": null
}
]
}
Pada saat yang sama perusahaan ini juga punya satu pengumuman terjadwal (tayang besok) dan satu yang
sudah berakhir; keduanya tidak muncul. Karyawan borneo-retail hanya menerima pengumuman perusahaannya
sendiri.
Tanpa pengumuman tayang, data berupa array kosong [].
Field data[]
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | dipakai untuk GET /announcements/{announcement} |
title |
string | tidak | maksimal 150 karakter |
body |
string | tidak | teks polos, maksimal 5000 karakter, paragraf dipisah \n\n. Tampilkan apa adanya, bukan HTML/Markdown |
is_pinned |
boolean | tidak | disematkan Admin HR |
is_read |
boolean | tidak | karyawan login sudah pernah membuka detailnya |
published_at |
string ISO 8601 UTC | tidak | mulai tayang |
expires_at |
string ISO 8601 UTC | ya | akhir tayang; null = tanpa batas |
Contoh Response Gagal: 401 tanpa token, 402 langganan terkunci (README bagian 5.1).
Detail pengumuman
GET /announcements/{announcement}
Deskripsi: satu pengumuman yang sedang tayang. Memanggil endpoint ini menandai pengumuman dibaca oleh karyawan login. Pemanggilan berulang tidak mengubah waktu baca pertama.
| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.announcements.show |
Header: Accept: application/json, Authorization: Bearer <token>
Parameter
| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
announcement |
path | integer | ya | id dari daftar |
Contoh Request
GET /api/v1/announcements/2 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-15 21:12 WIB)
{
"success": true,
"message": "Detail pengumuman berhasil diambil.",
"data": {
"id": 2,
"title": "Libur Bersama Akhir Tahun",
"body": "Kantor tutup 24-26 Desember 2026.\n\nPresensi dibuka kembali 28 Desember.",
"is_pinned": true,
"is_read": true,
"published_at": "2026-11-15T13:00:00+00:00",
"expires_at": "2026-12-31T16:59:00+00:00"
}
}
Field data sama dengan item daftar; is_read selalu true.
Contoh Response Gagal
Pengumuman terjadwal atau sudah berakhir (404):
{
"success": false,
"message": "Pengumuman tidak ditemukan atau sudah tidak tayang.",
"errors": {}
}
Pengumuman milik perusahaan lain, sudah dihapus, atau id tidak dikenal (404):
{
"success": false,
"message": "Sumber daya tidak ditemukan.",
"errors": {}
}
401 dan 402 sama dengan daftar.
Catatan untuk Client
- Lencana "belum dibaca" dihitung client dari jumlah item
is_read: falsediGET /announcements. - Segarkan daftar saat aplikasi dibuka dan saat layar pengumuman ditampilkan. Belum ada notifikasi push saat pengumuman terbit (lihat push-tokens.md).
- Pengumuman yang terbuka di layar bisa berakhir atau dihapus sewaktu-waktu. Tangani 404 dengan menghapus item dari daftar lokal.