API-Dokumentation

Sende Benachrichtigungen an Mitarbeiter aus anderen Systemen — Skripte, Cron-Jobs anderer Server, n8n, Webhooks, WhatsApp-Bots.

API-Schlüssel abrufen

Inhaber: gehe zu Verwalten → 🔑 API-Schlüssel, gib ihm einen Namen, klicke auf Schlüssel erstellen.

Der Schlüssel hat die Form jss_ + 64 Zeichen und wird nur einmal angezeigt. Der Server speichert nur seinen Fingerabdruck — geht er verloren, kann ihn niemand mehr anzeigen, auch wir nicht. Alten widerrufen, neuen erstellen.

Speichere ihn in einer Umgebungsvariable oder einer Konfigurationsdatei außerhalb des Docroot. Niemals in Code, der zu git committet wird.

2 · Schlüssel senden

Einer dieser beiden Header — wähle den, der für dein Tool einfacher ist:

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

Der Schlüssel bestimmt die Firma. Kein Endpunkt hat einen Tenant-Parameter — gäbe es einen, würde ein einziger geleakter Schlüssel reichen, um an alle Firmen auf dieser Plattform zu senden.

Hier gibt es keinen CSRF-Schutz, und das ist richtig so. CSRF schützt vor Anfragen, die vom Browser einer anderen Person ausgelöst werden und deren Cookies mitreiten. Schlüsselbasierte Anfragen tragen niemandes Cookies — es gibt nichts, worauf man aufspringen könnte.

Was dieser Schlüssel kann

Sendet nur Benachrichtigungen an die Mitarbeiter der besitzenden Firma, und liest die Liste der Mitarbeiternamen + IDs (damit du eine Möglichkeit hast, an die user_id zu kommen, ohne zu raten).

Er kann nicht das Gehalt, die Anwesenheit, E-Mail, Bankkonto oder Benachrichtigungen von irgendjemandem lesen; kann nichts ändern; kann keine anderen Firmen berühren. Absichtlich so eng gefasst — Zugangsdaten, die auf einem anderen Server leben, werden früher oder später durchsickern, und wie gering der Schaden ausfällt, hängt davon ab, wie wenig sie können.

3 · Prüfen, ob der Schlüssel funktioniert

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 · Mitarbeiterliste abrufen

GET/api/v1/notif.php?aksi=karyawan — um die user_id zu bekommen.

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" }
  ]
}

Nur ID, Name und Rolle. Keine E-Mail/Rate/Bankkonto — dieser Schlüssel dient zum Senden von Benachrichtigungen, nicht zum Lesen von Personendaten.

5 · Benachrichtigung senden

POST/api/v1/notif.php — akzeptiert JSON oder Formulardaten.

Feld	Erforderlich	Beschreibung
`judul`	ja	max. 120 Zeichen
`isi`	ja	max. 255 Zeichen
`user_id`	nein	Mitarbeiter-ID. 0 oder weggelassen = alle aktiven Mitarbeiter
`jenis`	nein	`info` (Standard), `kasbon` (Vorschuss), `gaji` (Gehalt), `bonus`, `timer`, `absen` (Anwesenheit). Bestimmt nur das Symbol; unbekannte Werte fallen zurück auf `info`
`url`	nein	muss ein interner Pfad sein, der mit `/` beginnt

An alle Mitarbeiter

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 }

An eine Person, mit 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 muss ein interner Pfad sein. https://… und //evil.com werden mit 400 abgelehnt.

Grund: eine offiziell wirkende Benachrichtigung, die überallhin verweisen kann, ist das perfekte Phishing-Werkzeug — Mitarbeiter klicken arglos, gerade weil das Portal sie zugestellt hat. Ein geleakter Schlüssel genügt, um „Klicken, um dein Gehalt zu prüfen“ an eine gefälschte Login-Seite zu senden.

Auch //evil.com wird abgelehnt, obwohl es mit einem Schrägstrich beginnt: Browser lesen es als Adresse zu einem anderen Host.

Was nach dem Senden passiert

Mitarbeiter mit geöffnetem Portal hören einen Ton und sehen innerhalb von ≤20 Sekunden ein Popup. Wer es nicht geöffnet hat, wird beim nächsten Login begrüßt. Alles landet auf ihrer Benachrichtigungsseite, und jeder API-Versand wird mit dem Namen des Schlüssels im Audit-Log erfasst.

Rate-Limit

60 Anfragen pro Minute pro Schlüssel. Jede Antwort enthält:

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

Über dem Limit → 429 + Retry-After: 60.

Statuscodes

Code	Bedeutung
`200`	Erfolg
`400`	Falscher Parameter, defekter JSON-Body, oder `url` ist kein interner Pfad
`401`	Schlüssel fehlt, ist falsch oder bereits widerrufen
`404`	`user_id` ist kein Mitarbeiter dieser Firma
`405`	Falsche Methode
`429`	Rate-Limit überschritten

Bei Fehlschlag

Symptom	Meist verursacht durch
`401`, obwohl der Schlüssel korrekt ist	Manche Server entfernen den `Authorization`-Header, bevor er PHP erreicht. Versuche `X-API-Key` — ein gewöhnlicher Header, den der Server nie anfasst. Wenn das funktioniert, Bearer aber nicht, sag uns Bescheid.
`401` aus dem Nichts, obwohl es vorher funktionierte	Der Inhaber hat den Schlüssel widerrufen. Prüfe die API-Schlüssel-Seite.
`400` „url muss ein interner Pfad sein“	Du hast `https://…` gesendet. Verwende stattdessen `/staff/transaksi.php`.
`200`, aber `"terkirim": 0`	Der Mitarbeiter ist nicht aktiv, oder die Firma hat noch keine aktiven Mitarbeiter.

Ehrliche Einschränkungen

Diese API hat nur Benachrichtigungen. Es gibt keinen Endpunkt für Anwesenheit, Gehalt oder Vorschüsse. Jede Erweiterung macht einen geleakten Schlüssel gefährlicher, verdient also ein Überdenken — nicht ein „wo wir gerade dabei sind“.
Keine Scopes pro Schlüssel. Alle Schlüssel können dasselbe. Solange die einzige Fähigkeit das Senden von Benachrichtigungen ist, wäre ein Scope nur eine zusätzliche Spalte ohne echte Garantie.
Das Rate-Limit gilt pro Schlüssel, nicht pro IP. Ein geleakter Schlüssel bleibt auf 60/Minute begrenzt — aber 60 Benachrichtigungen pro Minute an alle Mitarbeiter sind trotzdem störend. Die eigentliche Verteidigung ist das Widerrufen des Schlüssels — prüfe daher die Spalte „zuletzt verwendet“ und die IP auf der API-Schlüssel-Seite.

Sollen sich Mitarbeiter mit ihrem JS-Staff-Konto in deiner App anmelden (nicht nur Benachrichtigungen erhalten)? Das ist SSO — die Einrichtungsanleitung ist hier.