Lies und ändere den Dienstplan aus deinen eigenen Werkzeugen: eine REST-API in JSON, geschützt durch einen Schlüssel, und signierte Webhooks, die dir melden, was sich ändert. Jeder HTTP-Client genügt.
Basis-URL
https://api.swissplanif.ch/api/v1
Authentifizierung
Schlüssel im Authorization-Header
Format
JSON, UTF-8, Daten in UTC
Rate
100 Anfragen pro 60 s
Geprüft gegen Code und Produktion am 13. November 2026.
Schnellstart
1
Erstelle einen Schlüssel
Erstelle unter Einstellungen → API-Schlüssel einen Schlüssel mit genau den Berechtigungen, die deine Integration braucht. Er wird nur einmal angezeigt: Lege ihn sofort in deinem Secret-Manager ab.
2
Halte ihn aus dem Code heraus
Dein Programm liest den Schlüssel aus einer Umgebungsvariable, hier SWISSPLANIF_TOKEN. Schreibe ihn weder in ein Repository noch in eine URL, noch in eine Webseite oder eine mobile App.
3
Mach einen ersten Aufruf
Liste deine Standorte mit einem Schlüssel auf, der locations:read trägt. Das ist ein Lesezugriff: Er ändert nichts.
Jede Anfrage trägt den Header Authorization: Bearer, gefolgt von deinem Schlüssel. Es gibt weder ein Cookie noch einen Schlüssel in der URL.
Ein Schlüssel beginnt mit stk_live_, gefolgt von 64 zufälligen Zeichen (48 Bytes). Wir behalten nur seinen SHA-256-Hash: Niemand, auch wir nicht, kann ihn dir erneut anzeigen. Wenn du ihn verlierst, erstelle einen neuen.
Ein Schlüssel öffnet die Daten der ganzen Organisation, im Rahmen seiner Berechtigungen. Um einen zu erstellen, braucht es deshalb ein Konto, das API-Schlüssel verwalten darf und dessen Zugriff die ganze Organisation umfasst.
Ein widerrufener oder abgelaufener Schlüssel wird ab dem nächsten Aufruf mit 401 abgelehnt. Seine Laufzeit wählst du beim Erstellen: 30, 90 (voreingestellt) oder 365 Tage, oder ohne Ablauf.
Berechtigungen
Ein Schlüssel trägt eine oder mehrere Berechtigungen. Ein Aufruf, der eine andere verlangt, wird mit 403 abgelehnt. Lesen und Schreiben sind getrennt: Ein Dashboard-Schlüssel muss nie schreiben.
Basis-URL: https://api.swissplanif.ch/api/v1. Die Version steht im Pfad: Eine inkompatible Änderung kommt unter einem neuen Präfix, nie als Änderung an Ort und Stelle.
Nur HTTPS. Schreibe immer https://: Ein im Klartext gesendeter Schlüssel gilt als verloren.
Anfragen und Antworten sind JSON (UTF-8). Sende Content-Type: application/json, sobald es einen Körper gibt.
Daten sind ISO-8601-Zeitpunkte in UTC und enden auf Z, zum Beispiel 2026-11-16T07:00:00Z. Ein Versatz wie +01:00 wird abgelehnt.
Kennungen sind UUIDs.
Ein unbekanntes Feld in einem Körper wird ignoriert, nicht abgelehnt.
Ein Anfragekörper ist höchstens 5 MB gross.
Paginierung
Nur die Liste der Schichten ist paginiert. limit legt die Seitengrösse fest, von 1 bis 200, standardmässig 50. Solange die Antwort einen nextCursor enthält, sende ihn als cursor zurück, um die nächste Seite zu lesen; null bedeutet, dass du alles gelesen hast.
Die Seiten sind nach Kennung sortiert. Die Reihenfolge bleibt von Seite zu Seite stabil, ist aber nicht chronologisch: Sortiere bei Bedarf selbst nach start.
Die Listen der Mitarbeitenden, Standorte und Positionen liefern alles in einer einzigen Antwort.
Objekte
Die vier Objekte, die die API zurückgibt. Ein Feld mit dem Vermerk «oder null» kann leer sein.
Schicht
iduuid
Kennung der Schicht.
startdatetime
Beginn.
enddatetime
Ende.
breakMinutesinteger
Pause, in Minuten.
statusenum
Zustand der Schicht.DRAFTPUBLISHEDCOMPLETEDCANCELLED
positionIduuid
Position.
positionNamestring
Name der Position.
locationIduuid
Standort.
locationNamestring
Name des Standorts.
employeeIduuid · oder null
Zugewiesene Person; leer, wenn die Schicht niemandem zugewiesen ist.
Ungültige Anfrage: fehlendes oder fehlerhaftes Feld, Kennung, die keine UUID ist, Ende vor dem Beginn.Mögliche MeldungenValidation failedValidation failed (uuid is expected)end must be strictly after start
401Unauthorized
Schlüssel fehlt, ist unbekannt, widerrufen oder abgelaufen.Mögliche MeldungenMissing Bearer tokenEmpty bearer tokenInvalid API tokenToken revokedToken expired
402Payment Required
Abonnement inaktiv: Testphase beendet, Zahlung nicht abgeschlossen oder Abonnement abgelaufen. Schreibzugriffe werden abgelehnt, Lesezugriffe bleiben möglich; alles läuft wieder, sobald es reaktiviert ist.Mögliche MeldungenVotre période d’essai est terminée. Activez un abonnement pour continuer à modifier vos données.Votre paiement n’a pas été finalisé. Terminez la souscription pour reprendre les modifications.Votre abonnement est arrivé à échéance. Réactivez-le pour continuer à modifier vos données.
403Forbidden
Dem Schlüssel fehlt die verlangte Berechtigung. Die Meldung nennt die fehlende Berechtigung.Mögliche MeldungenMissing scope: shifts:write
404Not Found
Ressource in deiner Organisation nicht gefunden. Eine Ressource aus einer anderen Organisation ergibt genau dieselbe Antwort.Mögliche MeldungenShift not foundemployee not foundposition not foundlocation not found
429Too Many Requests
Zu viele Anfragen. Warte die Anzahl Sekunden, die Retry-After angibt.Mögliche MeldungenThrottlerException: Too Many Requests
Ein 400 hat drei Formen
Anfragekörper abgelehnt: message lautet Validation failed, und issues listet jedes betroffene Feld auf.
Listenparameter abgelehnt: Der Körper ist ein Objekt, dessen Schlüssel die Namen der betroffenen Parameter sind.
400
{
"limit": [
"Too big: expected number to be <=200"
]
}
Übrige Fälle: der Standardkörper.
400
{
"message": "end must be strictly after start",
"error": "Bad Request",
"statusCode": 400
}
Ein Körper über 5 MB wird mit 413 abgelehnt. Ein 5xx meldet eine Störung auf unserer Seite: Wiederhole einen Lesezugriff nach wachsender Wartezeit; prüfe vor dem Wiederholen einer Erstellung, ob sie nicht doch durchgegangen ist.
Ratenlimits
100 Anfragen pro Fenster von 60 Sekunden. Der Zähler wird für jeden Endpunkt getrennt geführt und ist an den Aufrufer gebunden: seine IP-Adresse oder seinen Schlüssel.
Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, die Anzahl Sekunden bis zum Zurücksetzen. Über dem Limit ist die Antwort ein 429 mit Retry-After.
Eine globale Obergrenze pro Adresse schützt zudem den Dienst als Ganzes. Sie antwortet auf dieselbe Weise.
429
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Webhooks
Ein Webhook sendet dir jedes Mal eine signierte POST-Anfrage, wenn ein Ereignis eintritt, das du abonniert hast. Du richtest sie unter Einstellungen → Webhooks ein.
Die Adresse muss mit https:// beginnen, öffentlich sein, keine Zugangsdaten in der URL tragen und höchstens 500 Zeichen lang sein. Eine Adresse, die in ein privates Netz führt, wird abgelehnt, beim Speichern und bei jedem Versand.
Das Signatur-Secret beginnt mit whs_ und wird nur einmal angezeigt, bei der Erstellung. Wir bewahren es verschlüsselt auf (AES-256-GCM).
Wie bei den Schlüsseln braucht es ein Konto, das Webhooks verwalten darf und dessen Zugriff die ganze Organisation umfasst.
sha256=, gefolgt vom HMAC-SHA-256 des rohen Körpers in hexadezimaler Form, berechnet mit deinem Secret.
X-SwissPlanif-Event
Name des Ereignisses, identisch mit dem Feld event.
X-SwissPlanif-Delivery-Id
Eindeutige Kennung dieser Zustellung (UUID). Bewahre sie auf, um eine bereits verarbeitete Zustellung zu erkennen.
eventstring
Name des Ereignisses.
tenantIduuid
Kennung deiner Organisation.
occurredAtdatetime
Zeitpunkt des Versands, in UTC.
dataobject
Inhalt des Ereignisses, weiter unten beschrieben.
Die Signatur prüfen
Lies den rohen Körper, Byte für Byte, vor jeder JSON-Dekodierung.
Berechne seinen HMAC-SHA-256 mit deinem Secret und vergleiche ihn zeitkonstant mit dem Header.
Lehne die Anfrage ab, wenn die Signatur nicht stimmt oder wenn occurredAt älter als einige Minuten ist: Das ist dein Schutz gegen das erneute Abspielen einer abgefangenen Anfrage.
Antworte sofort mit 2xx und verarbeite das Ereignis danach im Hintergrund.
Node.js, ohne Abhängigkeit
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_AGE_MS = 5 * 60 * 1000;
// rawBody: the request body exactly as received (string or Buffer).
export function verifyWebhook(rawBody, signatureHeader, secret) {
const expected = Buffer.from(
`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`,
);
const received = Buffer.from(String(signatureHeader ?? ''));
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
return null;
}
const event = JSON.parse(rawBody.toString());
const age = Math.abs(Date.now() - Date.parse(event.occurredAt));
return age <= MAX_AGE_MS ? event : null;
}
// const event = verifyWebhook(
// rawBody,
// request.headers['x-swissplanif-signature'],
// process.env.SWISSPLANIF_WEBHOOK_SECRET,
// );
// if (!event) return response.writeHead(401).end();
Zustellung
Ein einziger Versuch pro Ereignis, ohne automatische Wiederholung. Eine Antwort ausserhalb von 2xx, eine Weiterleitung oder eine Wartezeit von mehr als 8 Sekunden gelten als Fehlschlag.
Nach 10 aufeinanderfolgenden Fehlschlägen wird der Endpunkt pausiert. Du setzt ihn in den Einstellungen fort, wo der Verlauf seiner Zustellungen einsehbar bleibt.
Ein Ereignis kann also verloren gehen: Lies für den genauen Stand die API erneut.
Ereignisse
Der Inhalt von data für jedes Ereignis. Kennungen verweisen auf Objekte deiner Organisation; Daten sind in UTC.
shift.publishedSchicht veröffentlicht
Ein Ereignis pro Schicht des veröffentlichten Dienstplans.
shiftIduuid
Betroffene Schicht.
scheduleIduuid
Dienstplan, zu dem die Schicht gehört.
publicationIduuid
Veröffentlichung, die diese Schicht festgehalten hat.
employeeIduuid · oder null
Betroffene Person.
locationIduuid
Standort.
startdatetime
Beginn.
enddatetime
Ende.
weekStartdatetime
Beginn der veröffentlichten Woche.
publishedAtdatetime
Zeitpunkt der Veröffentlichung.
shift.cancelledSchicht storniert
Wird gesendet, wenn eine Schicht in den Zustand «abgesagt» wechselt. Eine Löschung sendet nichts.
shiftIduuid
Betroffene Schicht.
scheduleIduuid · oder null
Dienstplan, zu dem die Schicht gehört.
employeeIduuid · oder null
Betroffene Person.
locationIduuid
Standort.
startdatetime
Beginn.
enddatetime
Ende.
absence.requestedAbwesenheitsantrag
absenceIduuid
Betroffene Abwesenheit.
employeeIduuid
Betroffene Person.
startdatetime
Beginn.
enddatetime
Ende.
absence.approvedAbwesenheit bestätigt
Das Genehmigen einer Abwesenheit sagt keine Schicht mehr ab: cancelledShifts ist immer 0.
absenceIduuid
Betroffene Abwesenheit.
cancelledShiftsinteger
Immer 0.
keptShiftsinteger
Anzahl Schichten der Person, die sich mit der Abwesenheit überschneiden und bestehen bleiben.
absence.rejectedAbwesenheit abgelehnt
Wird bei einer Ablehnung gesendet, und auch wenn eine bereits genehmigte Abwesenheit zurückgezogen wird, ganz oder für einen einzelnen Tag: revoked ist dann true.
absenceIduuid
Betroffene Abwesenheit.
reasonstring
Vom Verantwortlichen erfasster Grund, falls vorhanden.je nach FallFreitext
revokedboolean
true, wenn eine bereits genehmigte Abwesenheit zurückgezogen wird.je nach Fall
deletedboolean
true, wenn die zurückgezogene Abwesenheit gelöscht wurde.je nach Fall
partialboolean
true, wenn ein einzelner Tag aus der Abwesenheit entfernt wurde.je nach Fall
restoredShiftsinteger
Anzahl wiederhergestellter Schichten.je nach Fall
removedStartdatetime
Beginn des entfernten Zeitraums.je nach Fall
removedEnddatetime
Ende des entfernten Zeitraums.je nach Fall
tailAbsenceIduuid · oder null
Abwesenheit, die für die Tage nach dem entfernten Tag angelegt wurde, falls es welche gibt.je nach Fall
swap.requestedTausch angefragt
swapIduuid
Tauschanfrage.
shiftIduuid
Betroffene Schicht.
requestedByIduuid
Mitarbeitende Person, die den Tausch anfragt.
targetEmployeeIduuid · oder null
Angefragte Person, falls die Anfrage eine nennt.
swap.approvedTausch bestätigt
swapIduuid
Tauschanfrage.
swap.rejectedTausch abgelehnt
swapIduuid
Tauschanfrage.
reasonstring
Vom Verantwortlichen erfasster Grund, falls vorhanden.je nach FallFreitext
open_shift.appliedBewerbung offene Schicht
claimIduuid
Bewerbung.
shiftIduuid
Betroffene Schicht.
employeeIduuid
Betroffene Person.
open_shift.assignedOffene Schicht zugewiesen
claimIduuid
Bewerbung.
shiftIduuid
Betroffene Schicht.
employeeIduuid
Betroffene Person.
shift_offer.sentEinsatzangebot gesendet
offerIduuid
Angebot.
shiftIduuid
Betroffene Schicht.
recipientsinteger
Anzahl Personen, denen das Angebot gesendet wurde.
shift_offer.claimedEinsatzangebot angenommen
offerIduuid
Angebot.
shiftIduuid
Betroffene Schicht.
employeeIduuid
Betroffene Person.
mission.activatedEinsatz aktiviert
missionIduuid
Einsatz.
mission.completedEinsatz abgeschlossen
missionIduuid
Einsatz.
mission.cancelledEinsatz storniert
missionIduuid
Einsatz.
employee.skill.expiringKompetenz läuft ab
Wird einmal pro Tag für jede Qualifikation gesendet, die innerhalb von 30 Tagen abläuft.
employeeSkillIduuid
Qualifikation der Person, die bald abläuft.
employeeIduuid
Betroffene Person.
skillIduuid
Qualifikation.
expiresAtdatetime
Ablaufdatum.
observedAtdatetime
Zeitpunkt der Prüfung.
noticeDaysinteger
Vorlauf, in Tagen.
Sicherheit
Ein API-Schlüssel öffnet die Daten deiner ganzen Organisation. Diese Regeln passen auf eine Seite: Wende sie alle an.
Auf deiner Seite
01Ein Schlüssel pro Integration, so wenige Berechtigungen wie möglich
Ein Dashboard muss nur lesen. Ein Schlüssel pro Werkzeug erlaubt dir, einen zu widerrufen, ohne die anderen abzuschneiden.
02Der Schlüssel liegt in einem Secret-Manager
Nie in einem Repository, einem Ticket, einer E-Mail oder einem Screenshot, und nie im Code einer Webseite oder einer mobilen App.
03Rufe die API von einem Server aus auf
Ein in einem Browser geladener Schlüssel ist für alle lesbar, die die Seite öffnen. Die API erlaubt ohnehin keiner anderen Website, sie aus einem Browser aufzurufen.
04Ersetze deine Schlüssel regelmässig
Erstelle den neuen Schlüssel, stelle deine Integration um, prüfe, und widerrufe dann den alten. Die Einstellungen zeigen den letzten Aufruf jedes Schlüssels.
05Im Zweifel widerrufen
Der Widerruf wirkt ab dem nächsten Aufruf. Ein durchgesickerter Schlüssel gilt als gelesen.
06Protokolliere den Schlüssel nicht
Maskiere den Header Authorization in deinen Logs, deinen Debugging-Werkzeugen und deinen Fehlerberichten.
07Prüfe jeden Webhook
Signatur über den rohen Körper, zeitkonstanter Vergleich, alte Anfragen ablehnen. Vertraue vor dieser Prüfung weder der Absenderadresse noch dem Inhalt.
08Behandle Personendaten als solche
Namen, E-Mail-Adressen und Notizen fallen unter das revDSG und die DSGVO. Kopiere nur, was du brauchst, und lösche es, wenn du es nicht mehr verwendest.
09Validiere, was du erhältst
Eine Notiz oder ein Grund ist ein von einer Person getippter Text. Behandle jeden erhaltenen Wert als Daten, nie als Code oder als auszuführenden Befehl.
Auf unserer Seite
Von einem Schlüssel wird nur der SHA-256-Hash aufbewahrt; der Schlüssel erscheint ein einziges Mal, bei seiner Erstellung.
Die Berechtigungen werden bei jedem Aufruf geprüft, und jede Anfrage läuft im Bereich der Organisation des Schlüssels, isoliert durch die Row-Level Security von PostgreSQL.
Eine Ressource einer anderen Organisation antwortet wie eine Ressource, die es nicht gibt.
Die Erstellung und der Widerruf eines Schlüssels sowie jeder Schreibzugriff über die API werden mit der Kennung des Schlüssels im Audit-Log festgehalten.
Das Secret eines Webhooks ist im Ruhezustand verschlüsselt (AES-256-GCM).
Vor jedem Versand wird die Adresse eines Webhooks aufgelöst und geprüft: nur HTTPS, private Netze abgelehnt, Zertifikat geprüft, keine Weiterleitung verfolgt.
In der Produktion liefert die API weder eine interaktive Konsole noch eine OpenAPI-Beschreibung aus.
Jeder Endpunkt hat ein Ratenlimit, und jede Antwort trägt die Sicherheits-Header HSTS und CSP.
Hast du eine Schwachstelle gefunden? Schreibe an contact@swissplanif.ch. Der tatsächliche Stand unserer Sicherheit, Lücken inbegriffen, steht auf der Seite Sicherheit.
Was die API noch nicht kann
Was heute fehlt, damit du es weisst, bevor du darauf aufbaust.
Lesezugriffe werden nicht protokolliert
Das Audit-Log hält die Schreibzugriffe über die API fest, nicht die Leseaufrufe.
Kein Idempotenzschlüssel
Eine wiederholte Erstellung legt eine zweite Schicht an. Lies nach einem Unterbruch zuerst, bevor du erneut erstellst.
Keine fachliche Prüfung beim Schreiben
Die API prüft weder die Überschneidungen noch die Arbeitszeitregeln, auf die die App hinweist.
Webhooks ohne Wiederholung
Eine fehlgeschlagene Zustellung wird nicht wiederholt. Der Fehlschlag bleibt im Zustellungsverlauf in den Einstellungen sichtbar.
Kein Wechsel des Webhook-Secrets
Um das Secret zu wechseln, lösche den Endpunkt und lege ihn neu an.
Keine Testumgebung
Es gibt nur Produktionsschlüssel. Beginne mit einem Schlüssel, der nur lesen darf.
Listen ohne Paginierung
Mitarbeitende, Standorte und Positionen werden auf einmal zurückgegeben.