Pengumuman

Lihat Markdown

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: false di GET /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.