← API Key JS Staff

توثيق API

أرسل إشعارات إلى الموظفين من أنظمة أخرى — سكربتات، مهام كرون على خوادم أخرى، n8n، ويب هوك، بوتات واتساب.

احصل على مفتاح API

المالك: اذهب إلى إدارة ← 🔑 مفتاح API، أعطه اسمًا، اضغط إنشاء مفتاح.

2 · أرسل المفتاح

أحد هذين الترويستين — اختر ما هو أسهل لأداتك:

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

المفتاح يحدّد الشركة. لا توجد معلمة مستأجر (tenant) في أي نقطة نهاية — لو وُجدت، لكفى مفتاح واحد مسرَّب لإرسال رسائل إلى جميع الشركات على هذه المنصة.

ما الذي يمكن أن يفعله هذا المفتاح

يرسل الإشعارات فقط إلى موظفي الشركة المالكة، بالإضافة إلى قراءة قائمة أسماء الموظفين ومعرّفاتهم (حتى تحصل على 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" }
  ]
}

فقط المعرّف والاسم والدور. لا بريد إلكتروني/أجر/حساب بنكي — هذا المفتاح لإرسال الإشعارات، وليس لقراءة بيانات الأشخاص.

5 · أرسل إشعارًا

POST/api/v1/notif.php — يقبل JSON أو بيانات النموذج.

إلى جميع الموظفين

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"

ما يحدث بعد الإرسال

الموظفون الذين لديهم البوابة مفتوحة يسمعون صوتًا ويرون نافذة منبثقة خلال ≤20 ثانية. من ليست البوابة مفتوحة لديه سيُستقبَل في المرة القادمة التي يسجّل فيها الدخول. كل شيء يصل إلى صفحة إشعاراتهم، وكل إرسال عبر API يُسجَّل في سجل التدقيق باسم المفتاح.

حد المعدل

60 طلبًا في الدقيقة لكل مفتاح. كل استجابة تحمل:

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

عند تجاوز الحد ← 429 + Retry-After: 60.

رموز الحالة

إذا فشل

القيود الصريحة

• لا تحتوي هذه الـ API إلا على الإشعارات. لا توجد نقطة نهاية للحضور أو الرواتب أو السلف. كل إضافة تعني أن المفتاح المسرَّب يصبح أخطر، فكل واحدة تستحق إعادة تفكير — لا أن تُضاف لأن "طالما نحن هنا".
• لا توجد نطاقات صلاحية لكل مفتاح. جميع المفاتيح تستطيع فعل الشيء نفسه. طالما أن القدرة الوحيدة هي إرسال الإشعارات، فإن النطاق سيكون مجرد عمود إضافي دون أي ضمان حقيقي.
• حد المعدل لكل مفتاح، وليس لكل عنوان IP. يظل المفتاح المسرَّب مقيّدًا بـ 60/دقيقة — لكن 60 إشعارًا في الدقيقة لجميع الموظفين ما زال مزعجًا. الدفاع الحقيقي هو إلغاء المفتاح، فتحقّق من عمود "آخر استخدام" وعنوان IP في صفحة مفتاح API.

هل تحتاج أن يسجّل الموظفون الدخول إلى تطبيقك بحساب JS Staff الخاص بهم (وليس فقط تلقّي الإشعارات)؟ هذا هو SSO — دليل الإعداد هنا.