Documentation de l’API

Envoyez des notifications aux employés depuis d’autres systèmes — scripts, cron d’autres serveurs, n8n, webhooks, bots WhatsApp.

Obtenir une clé API

Propriétaire : allez dans Gérer → 🔑 Clé API, donnez-lui un nom, cliquez sur Créer la clé.

La clé se présente sous la forme jss_ + 64 caractères et n’est affichée qu’une seule fois. Le serveur ne stocke que son empreinte ; si vous la perdez, personne ne peut vous la remontrer — pas même nous. Révoquez l’ancienne, créez-en une nouvelle.

Stockez-la dans une variable d’environnement ou un fichier de config hors du docroot. Jamais dans du code commité sur git.

2 · Envoyer la clé

L’un de ces deux en-têtes — choisissez celui le plus simple pour votre outil :

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

La clé détermine l’entreprise. Aucun endpoint n’a de paramètre tenant — sinon, une seule clé fuitée suffirait à envoyer à toutes les entreprises de cette plateforme.

Il n’y a pas de protection CSRF ici, et c’est correct. Le CSRF protège contre les requêtes déclenchées par le navigateur de quelqu’un d’autre en profitant de ses cookies. Les requêtes basées sur une clé ne transportent les cookies de personne — rien à exploiter.

Ce que cette clé peut faire

Envoie uniquement des notifications aux employés de l’entreprise propriétaire, et lit la liste des noms + id des employés (pour que vous ayez un moyen d’obtenir user_id sans deviner).

Il ne peut pas lire le salaire, la présence, l’e-mail, le compte bancaire ou les notifications de qui que ce soit ; ne peut rien modifier ; ne peut toucher aux autres entreprises. Volontairement aussi restreint — des identifiants qui vivent sur un autre serveur finiront par fuiter, et l’ampleur des dégâts dépend de ce qu’ils peuvent si peu faire.

3 · Vérifier que la clé fonctionne

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 · Obtenir la liste des employés

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

Seulement l’id, le nom et le rôle. Pas d’e-mail/taux/compte bancaire — cette clé sert à envoyer des notifications, pas à lire les données des gens.

5 · Envoyer une notification

POST/api/v1/notif.php — accepte du JSON ou des données de formulaire.

Champ	Obligatoire	Description
`judul`	oui	120 caractères max.
`isi`	oui	255 caractères max.
`user_id`	non	id de l’employé. 0 ou omis = tous les employés actifs
`jenis`	non	`info` (par défaut), `kasbon` (avance), `gaji` (salaire), `bonus`, `timer`, `absen` (présence). Détermine seulement l’icône ; les valeurs inconnues retombent sur `info`
`url`	non	doit être un chemin interne commençant par `/`

À tous les employés

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 }

À une personne, avec un lien

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 doit être un chemin interne. https://… et //evil.com sont rejetés avec 400.

Raison : une notification d’apparence officielle pouvant pointer n’importe où est l’outil de phishing parfait — les employés cliquent sans se méfier précisément parce que c’est le portail qui l’a délivrée. Une seule clé fuitée suffit à diffuser « Cliquez pour voir votre salaire » vers une fausse page de connexion.

//evil.com est aussi rejeté, bien qu’il commence par une barre oblique : les navigateurs le lisent comme une adresse vers un autre hôte.

Ce qui se passe après l’envoi

Les employés avec le portail ouvert entendent un son et voient une popup en ≤20 secondes. Ceux qui ne l’ont pas ouvert seront accueillis à leur prochaine connexion. Tout arrive sur leur page Notifications, et chaque envoi par l’API est enregistré dans le journal d’audit avec le nom de la clé.

Limite de débit

60 requêtes par minute par clé. Chaque réponse porte :

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

Au-delà de la limite → 429 + Retry-After: 60.

Codes de statut

Code	Signification
`200`	Succès
`400`	Paramètre erroné, corps JSON invalide, ou `url` n’est pas un chemin interne
`401`	Clé absente, incorrecte, ou déjà révoquée
`404`	`user_id` n’est pas un employé de cette entreprise
`405`	Méthode incorrecte
`429`	Limite de débit dépassée

En cas d’échec

Symptôme	Généralement causé par
`401` alors que la clé est correcte	Certains serveurs suppriment l’en-tête `Authorization` avant qu’il n’atteigne PHP. Essayez `X-API-Key` — un en-tête ordinaire que le serveur ne touche jamais. Si cela fonctionne mais pas Bearer, prévenez-nous.
`401` soudainement, alors que ça marchait avant	Le propriétaire a révoqué la clé. Vérifiez sur la page Clé API.
`400` « url doit être un chemin interne »	Vous avez envoyé `https://…`. Utilisez plutôt `/staff/transaksi.php`.
`200` mais `"terkirim": 0`	L’employé n’est pas actif, ou l’entreprise n’a pas encore d’employés actifs.

Limitations honnêtes

Cette API ne propose que des notifications. Aucun endpoint pour la présence, la paie ou les avances. Chaque ajout rend une clé fuitée plus dangereuse, donc chacun mérite d’être repensé — pas ajouté juste « pendant qu’on y est ».
Pas de scope par clé. Toutes les clés peuvent faire la même chose. Tant que la seule capacité est l’envoi de notifications, un scope ne serait qu’une colonne de plus sans réelle garantie.
La limite de débit est par clé, pas par IP. Une clé fuitée reste plafonnée à 60/minute — mais 60 notifications par minute à tous les employés reste perturbateur. La vraie défense consiste à révoquer la clé, vérifiez donc la colonne « dernière utilisation » et son IP sur la page Clé API.

Besoin que les employés se connectent à votre application avec leur compte JS Staff (pas juste recevoir des notifications) ? C’est le SSO — le guide d’installation est ici.