APIドキュメント

他システムから従業員に通知を送信——スクリプト、他サーバーのcron、n8n、Webhook、WhatsAppボットなど。

APIキーを取得

オーナー：管理 → 🔑 APIキーに移動し、名前を付けてキーを作成を押します。

キーは jss_ + 64文字の形式で、一度だけ表示されます。サーバーはそのフィンガープリントのみを保存するため、紛失すると私たちを含め誰も再表示できません。古いキーを取り消して新しいキーを作成してください。

環境変数か、docroot の外にある設定ファイルに保存してください。gitにコミットされるコードには絶対に書かないでください。

2 · キーを送信

次の2つのヘッダーのどちらか——お使いのツールで使いやすい方を選んでください：

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

キーが会社を決定します。どのエンドポイントにもテナントパラメータはありません——もしあれば、キーが1つ漏れただけでこのプラットフォーム上の全社に送信できてしまいます。

ここにはCSRF対策がありませんが、それで正しいのです。CSRFは他人のブラウザのCookieに便乗して発生するリクエストから守るものです。キーによるリクエストは誰のCookieも運ばないため、便乗する余地がありません。

このキーでできること

所有会社の従業員に通知を送信するだけで、加えて従業員の氏名とidの一覧を読み取れます（推測せずに user_id を取得する手段として）。

誰の給与・勤怠・メール・口座・通知も読み取れず、何も変更できず、他社に触れることもできません。意図的にここまで狭くしています——他のサーバーに存在する認証情報は遅かれ早かれ漏洩します。それがどれほどの被害になるかは、それがどれだけ何もできないかで決まります。

3 · キーが有効か確認

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 · 従業員一覧を取得

GET/api/v1/notif.php?aksi=karyawan ——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" }
  ]
}

idと氏名と役割だけです。メール／レート／口座はありません——このキーは通知を送るためのもので、個人データを読み取るためのものではありません。

5 · 通知を送信

POST/api/v1/notif.php ——JSONまたはフォームデータを受け付けます。

フィールド	必須	説明
`judul`	はい	最大120文字
`isi`	はい	最大255文字
`user_id`	いいえ	従業員のid。0または未指定＝有効な全従業員
`jenis`	いいえ	`info`（既定）、`kasbon`（前借り）、`gaji`（給与）、`bonus`（ボーナス）、`timer`（タイマー）、`absen`（出勤）。アイコンを決めるだけで、未知の値は `info` になります
`url`	いいえ	`/` で始まる内部パスである必要があります

全従業員へ

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 }

一人へ、リンク付き

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 は内部パスである必要があります。https://… や //evil.com は 400 で拒否されます。

理由：どこへでも誘導できる公式風の通知は完璧なフィッシングツールです——従業員が疑わずにクリックするのは、まさにそれをポータルが届けているからです。キーが1つ漏れれば「給与を確認するにはクリック」を偽のログインページへ一斉送信するのに十分です。

//evil.com はスラッシュで始まっていても拒否されます。ブラウザはこれを別ホストへのアドレスとして解釈するためです。

送信後に起こること

ポータルを開いている従業員は20秒以内に音とポップアップに気づきます。開いていない従業員には次回ログイン時に表示されます。すべて通知ページに届き、API経由の送信は毎回キー名とともに監査ログに記録されます。

レート制限

キーごとに毎分60リクエスト。 各レスポンスには次が含まれます：

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

制限を超えると → 429 + Retry-After: 60。

ステータスコード

コード	意味
`200`	成功
`400`	パラメータが誤っている、JSONボディが壊れている、または `url` が内部パスでない
`401`	キーが送信されていない、誤っている、またはすでに取り消されている
`404`	`user_id` はこの会社の従業員ではありません
`405`	メソッドが誤っている
`429`	レート制限超過

失敗した場合

症状	よくある原因
キーが正しいのに `401`	一部のサーバーはPHPに届く前に `Authorization` ヘッダーを取り除いてしまいます。サーバーが一切手を加えない通常のヘッダーである `X-API-Key` を試してください。それで動いてBearerが動かない場合はご連絡ください。
これまで動いていたのに突然 `401`	オーナーがキーを取り消しました。APIキーのページを確認してください。
`400`「urlは内部パスである必要があります」	`https://…` を送信しています。代わりに `/staff/transaksi.php` を使ってください。
`200` なのに `"terkirim": 0`	その従業員が無効になっているか、会社にまだ有効な従業員がいません。

正直な制限事項

このAPIには通知機能しかありません。勤怠・給与・前借りのエンドポイントはありません。追加のたびにキー漏洩時の危険度が上がるため、「ついでに」追加するのではなく、一つひとつ再検討する価値があります。
キーごとのスコープはありません。すべてのキーは同じことができます。できることが通知送信だけである限り、スコープは実質的な保証を何も加えない余計な列にすぎません。
レート制限はIPごとではなくキーごとです。漏洩したキーも 60/分に制限されますが、それでも毎分60件の通知が全従業員に送られれば十分な迷惑になります。本当の防御策はキーの取り消しです。APIキーのページで「最終使用日時」とそのIPを確認してください。

従業員に（通知を受け取るだけでなく）JS Staffアカウントであなたのアプリにログインさせたいですか？それがSSOです——設定ガイドはこちら。