Dokumentasi API

Kirim notifikasi ke karyawan dari sistem lain — script, cron server lain, n8n, webhook, bot WhatsApp.

Ambil API key

Owner: buka Kelola → 🔑 API Key, beri nama, tekan Buat key.

Keynya berbentuk jss_ + 64 huruf dan cuma ditampilkan sekali. Yang disimpan server cuma sidik jarinya, jadi kalau hilang tidak ada yang bisa menunjukkannya lagi — termasuk kami. Cabut yang lama, buat baru.

Simpan di env var atau file config di luar docroot. Jangan di kode yang ikut ter-commit ke git.

2 · Kirim keynya

Salah satu dari dua header ini — pilih yang gampang buat alatmu:

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

Key menentukan perusahaan. Tidak ada parameter tenant di endpoint mana pun — kalau ada, satu key bocor cukup untuk mengirim ke seluruh perusahaan di platform ini.

Tidak ada CSRF di sini, dan itu benar. CSRF melindungi dari request yang dipicu browser orang lain dengan menumpang cookie mereka. Request berbasis key tidak membawa cookie siapa pun — tidak ada yang bisa ditumpangi.

Apa yang bisa dilakukan key ini

Cuma mengirim notifikasi ke karyawan perusahaan pemiliknya, plus membaca daftar nama + id karyawan (supaya kamu punya cara mendapatkan user_id tanpa menebak).

Dia tidak bisa membaca gaji, absen, email, rekening, atau notifikasi siapa pun; tidak bisa mengubah apa pun; tidak bisa menyentuh perusahaan lain. Sengaja sesempit itu — kredensial yang hidup di server lain akan bocor cepat atau lambat, dan yang menentukan seberapa parah akibatnya adalah seberapa sedikit yang bisa dilakukannya.

3 · Cek keynya hidup

GET/api/v1/notif.php?aksi=ping

curl "https://staff.jidanshoppu.com/api/v1/notif.php?aksi=ping" \
  -H "Authorization: Bearer jss_xxx"

{ "ok": true, "key": "n8n produksi", "perusahaan": "Perusahaan Kamu" }

4 · Ambil daftar karyawan

GET/api/v1/notif.php?aksi=karyawan — untuk mendapatkan user_id.

curl "https://staff.jidanshoppu.com/api/v1/notif.php?aksi=karyawan" \
  -H "Authorization: Bearer jss_xxx"

{
  "ok": true,
  "karyawan": [
    { "user_id": 3, "nama": "Sela",   "peran": "staff" },
    { "user_id": 5, "nama": "Syauqi", "peran": "staff" }
  ]
}

Cuma id, nama, dan peran. Tidak ada email/rate/rekening — key ini untuk mengirim notifikasi, bukan untuk membaca data orang.

5 · Kirim notifikasi

POST/api/v1/notif.php — terima JSON maupun form.

Field	Wajib	Keterangan
`judul`	ya	maks 120 huruf
`isi`	ya	maks 255 huruf
`user_id`	tidak	id karyawan. 0 atau tidak dikirim = semua karyawan aktif
`jenis`	tidak	`info` (default), `kasbon`, `gaji`, `bonus`, `timer`, `absen`. Cuma menentukan ikonnya; nilai asing jatuh ke `info`
`url`	tidak	harus path internal diawali `/`

Ke semua karyawan

curl -X POST https://staff.jidanshoppu.com/api/v1/notif.php \
  -H "Authorization: Bearer jss_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "judul": "Besok libur",
    "isi": "Tanggal 17 libur, timer tidak perlu dinyalakan."
  }'

{ "ok": true, "terkirim": 5 }

Ke satu orang, dengan link

curl -X POST https://staff.jidanshoppu.com/api/v1/notif.php \
  -H "X-API-Key: jss_xxx" \
  -d "user_id=3" \
  -d "judul=Cek transaksi kamu" \
  -d "isi=Ada penyesuaian baru bulan ini." \
  -d "jenis=gaji" \
  -d "url=/staff/transaksi.php"

url wajib path internal. https://… dan //evil.com ditolak dengan 400.

Alasannya: notifikasi resmi yang bisa mengarah ke mana saja adalah alat phishing yang sempurna — karyawan mengklik tanpa curiga justru karena portalnya yang mengantar. Satu key bocor cukup untuk menyiarkan "Klik untuk cek gaji" ke halaman login palsu.

//evil.com ikut ditolak walau diawali garis miring: browser membacanya sebagai alamat ke host lain.

Yang terjadi setelah terkirim

Karyawan yang sedang membuka portal mendengar bunyi dan melihat popup dalam ≤20 detik. Yang tidak sedang membuka akan disapa saat dia masuk. Semuanya masuk halaman Notifikasi mereka, dan tiap pengiriman lewat API tercatat di audit log dengan nama keynya.

Rate limit

60 permintaan per menit per key. Tiap respons membawa:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

Lewat batas → 429 + Retry-After: 60.

Kode status

Kode	Arti
`200`	Berhasil
`400`	Parameter salah, body JSON rusak, atau `url` bukan path internal
`401`	Key tidak dikirim, salah, atau sudah dicabut
`404`	`user_id` bukan karyawan perusahaan ini
`405`	Method salah
`429`	Lewat rate limit

Kalau gagal

Gejala	Sebabnya biasanya
`401` padahal keynya benar	Sebagian server membuang header `Authorization` sebelum sampai ke PHP. Coba `X-API-Key` — header biasa yang tidak pernah disentuh server. Kalau itu jalan tapi Bearer tidak, kabari kami.
`401` tiba-tiba, padahal tadi jalan	Keynya dicabut owner. Cek di halaman API Key.
`400` "url harus path internal"	Kamu mengirim `https://…`. Pakai `/staff/transaksi.php`.
`200` tapi `"terkirim": 0`	Karyawannya tidak aktif, atau perusahaannya belum punya karyawan aktif.

Batas jujurnya

API ini cuma punya notifikasi. Tidak ada endpoint absen, gaji, atau kasbon. Tiap tambahan berarti key yang bocor jadi lebih berbahaya, jadi masing-masing layak dipikir ulang — bukan ditambahkan karena "sekalian".
Tidak ada scope per-key. Semua key bisa melakukan hal yang sama. Selama yang bisa dilakukan cuma kirim notifikasi, scope cuma menambah kolom tanpa menambah jaminan.
Rate limit per key, bukan per IP. Key yang bocor tetap dibatasi 60/menit — tapi 60 notifikasi per menit ke semua karyawan tetap mengganggu. Pertahanan sesungguhnya adalah mencabut keynya, jadi periksa kolom "terakhir dipakai" dan IP-nya di halaman API Key.

Butuh karyawan login ke aplikasimu pakai akun JS Staff (bukan cuma kirim notifikasi)? Itu SSO — panduan pasangnya di sini.