API文档

从其他系统向员工发送通知——脚本、其他服务器的定时任务、n8n、Webhook、WhatsApp机器人。

获取API密钥

老板：前往管理 → 🔑 API Key，输入名称，点击创建密钥。

密钥格式为 jss_ + 64 位字符，只会显示一次。服务器只保存其指纹，一旦丢失就无人能再次显示——包括我们。请撤销旧密钥，创建新的。

保存在环境变量或 docroot 之外的配置文件中。切勿放在会被提交到 git 的代码里。

2 · 发送密钥

使用以下两个请求头之一——选择你的工具用起来更方便的那个：

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

密钥决定了所属公司。任何接口都没有租户参数——如果有，一旦密钥泄露就足以向本平台上的所有公司发送消息。

这里没有 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 被拒绝。

原因：一条能指向任意地址的官方通知是完美的钓鱼工具——员工正是因为是门户送达的才毫不怀疑地点击。密钥一旦泄露，就足以向所有人广播"点击查看工资"并跳转到虚假登录页。

//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 Key 页面查看。
`400`"url 必须是内部路径"	你发送了 `https://…`。请改用 `/staff/transaksi.php`。
返回 `200` 但 `"terkirim": 0`	该员工未激活，或该公司尚无在职员工。

坦诚的限制说明

这个 API 目前只有通知功能。没有考勤、工资或预支相关接口。每增加一个接口，都意味着密钥一旦泄露就更危险，所以每一项都值得重新考量——而不是"顺便"就加上去。
没有按密钥划分权限范围。所有密钥能做的事都一样。只要能做的只有发通知，权限范围就只是多一个字段而已，并不能带来额外保障。
速率限制是按密钥而非按 IP 计算的。泄露的密钥仍受限于每分钟 60 次——但每分钟向所有员工发送 60 条通知仍然会造成干扰。真正的防御手段是撤销该密钥，所以请检查 API Key 页面上的"最后使用时间"和 IP。

需要让员工使用 JS Staff 账户登录你的应用（而不只是接收通知）吗？那是 SSO——接入指南在这里。