REST-API · v1

Steuere SwissPlanif aus deinen Automatisierungen.

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.

curl
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"

Authentifizierung

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.

shifts:read
Schichten auflisten und eine Schicht lesen.GET/shiftsGET/shifts/{id}
shifts:write
Schichten erstellen, ändern und löschen. Gibt kein Leserecht.POST/shiftsPATCH/shifts/{id}DELETE/shifts/{id}
employees:read
Das Verzeichnis der Mitarbeitenden lesen: Namen, E-Mail-Adressen, Vertrag.GET/employees
locations:read
Standorte lesen.GET/locations
positions:read
Positionen lesen.GET/positions

Konventionen

  • 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.
employeeFullNamestring · oder null
Vor- und Nachname dieser Person.Personendaten
notestring · oder null
Freie Notiz.Personendaten
createdAtdatetime
Erstellung.
updatedAtdatetime
Letzte Änderung.

Mitarbeitende

iduuid
Kennung der Person.
firstNamestring
Vorname.Personendaten
lastNamestring
Nachname.Personendaten
emailstring · oder null
E-Mail-Adresse, falls erfasst.Personendaten
contractTypeenum
Vertragsart.PERMANENTFIXED_TERMTEMPINTERNFREELANCE
weeklyHoursnumber
Wochenstunden laut Vertrag.
locationIdsuuid[]
Standorte, denen die Person zugeordnet ist.
positionIdsuuid[]
Positionen, die sie besetzen kann.

Standort

iduuid
Kennung des Standorts.
namestring
Name.
addressstring · oder null
Adresse, falls erfasst.
timezonestring
IANA-Zeitzone, zum Beispiel Europe/Zurich.

Position

iduuid
Kennung der Position.
namestring
Name.
colorstring
Anzeigefarbe, hexadezimal.
requiredSkillsstring[]
Qualifikationen, die für die Position verlangt werden.

Endpunkte

Alle Pfade gehen von der Basis-URL aus. Neben den Fehlern, die zu einem Aufruf gehören, können alle mit 401, 403 und 429 antworten.

GET/shiftsBerechtigungshifts:read

Schichten auflisten

Gibt die Schichten der Organisation seitenweise zurück.

  • from und to filtern nach der Beginnzeit: from ist eingeschlossen, to ausgeschlossen.
  • Alle Zustände werden zurückgegeben, auch abgesagte Schichten: Filtere nach status, wenn du sie nicht willst.

Abfrageparameter

fromdatetime
Beginn des Fensters, eingeschlossen.
todatetime
Ende des Fensters, ausgeschlossen.
locationIduuid
Nur diesen Standort behalten.
employeeIduuid
Nur diese Person behalten.
positionIduuid
Nur diese Position behalten.
limitinteger
Anzahl Schichten pro Seite.von 1 bis 200Standard: 50
cursoruuid
Wert von nextCursor aus der vorherigen Seite.

Antwort

200 Ein Objekt mit data, einem Array von Objekten Schicht, und nextCursor.

Anfrage
curl "https://api.swissplanif.ch/api/v1/shifts?from=2026-11-16T00:00:00Z&to=2026-11-23T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Antwort · 200
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "start": "2026-11-16T07:00:00.000Z",
      "end": "2026-11-16T15:00:00.000Z",
      "breakMinutes": 30,
      "status": "DRAFT",
      "positionId": "00000000-0000-4000-8000-0000000000a1",
      "positionName": "Front desk",
      "locationId": "00000000-0000-4000-8000-0000000000b1",
      "locationName": "Lausanne Centre",
      "employeeId": "00000000-0000-4000-8000-0000000000c1",
      "employeeFullName": "Alex Example",
      "note": null,
      "createdAt": "2026-11-11T09:30:00.000Z",
      "updatedAt": "2026-11-11T09:30:00.000Z"
    }
  ],
  "nextCursor": "00000000-0000-4000-8000-000000000001"
}
GET/shifts/{id}Berechtigungshifts:read

Eine Schicht lesen

Gibt eine Schicht anhand ihrer Kennung zurück.

  • Eine unbekannte Kennung und eine Kennung aus einer anderen Organisation ergeben dieselbe Antwort: 404.

Abfrageparameter

iduuid
Kennung der Schicht, im Pfad.erforderlich

Antwort

200 Ein Objekt Schicht.

Anfrage
curl "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Antwort · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
POST/shiftsBerechtigungshifts:write

Eine Schicht erstellen

Erstellt eine Schicht im Zustand DRAFT.

  • end muss strikt nach start liegen.
  • positionId, locationId und employeeId müssen in deiner Organisation existieren, sonst 404.
  • Die API veröffentlicht die Schicht nicht und sendet keine Benachrichtigung.

Anfragekörper

startdatetime
Beginn der Schicht.erforderlich
enddatetime
Ende, strikt nach dem Beginn.erforderlich
breakMinutesinteger
Pause, in Minuten.von 0 bis 600Standard: 0
positionIduuid
Position, in deiner Organisation.erforderlich
locationIduuid
Standort, in deiner Organisation.erforderlich
employeeIduuid · oder null
Zugewiesene Person, oder null für eine Schicht ohne Person.Standard: null
notestring · oder null
Freie Notiz.höchstens 2000 ZeichenStandard: null

Antwort

201 Ein Objekt Schicht.

Anfrage
curl -X POST "https://api.swissplanif.ch/api/v1/shifts" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "employeeId": "00000000-0000-4000-8000-0000000000c1"
}'
Antwort · 201
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
PATCH/shifts/{id}Berechtigungshifts:write

Eine Schicht ändern

Ändert die gesendeten Felder; die anderen bleiben unverändert.

  • Wenn du nur start oder nur end sendest, wird das resultierende Intervall mit dem bereits gespeicherten Wert geprüft.
  • employeeId: null entfernt die Person; note: null löscht die Notiz.

Abfrageparameter

iduuid
Kennung der Schicht, im Pfad.erforderlich

Anfragekörper

Alle Felder sind optional: Sende nur die, die du änderst.

startdatetime
Beginn der Schicht.
enddatetime
Ende, strikt nach dem Beginn.
breakMinutesinteger
Pause, in Minuten.von 0 bis 600
positionIduuid
Position, in deiner Organisation.
locationIduuid
Standort, in deiner Organisation.
employeeIduuid · oder null
Zugewiesene Person, oder null für eine Schicht ohne Person.
notestring · oder null
Freie Notiz.höchstens 2000 Zeichen

Antwort

200 Ein Objekt Schicht.

Anfrage
curl -X PATCH "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "employeeId": null,
  "note": "Cover needed"
}'
Antwort · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": null,
  "employeeFullName": null,
  "note": "Cover needed",
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T10:05:00.000Z"
}
DELETE/shifts/{id}Berechtigungshifts:write

Eine Schicht löschen

Löscht die Schicht endgültig.

  • Eine Löschung sendet das Ereignis shift.cancelled nicht.

Abfrageparameter

iduuid
Kennung der Schicht, im Pfad.erforderlich

Antwort

204 Kein Körper.

Anfrage
curl -X DELETE "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
GET/employeesBerechtigungemployees:read

Mitarbeitende auflisten

Gibt die aktiven Mitarbeitenden der Organisation zurück, nach Nachname sortiert.

  • Die Antwort enthält Personendaten: Namen und E-Mail-Adressen.

Antwort

200 Ein Array von Objekten Mitarbeitende, in einer einzigen Antwort.

Anfrage
curl "https://api.swissplanif.ch/api/v1/employees" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Antwort · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "firstName": "Alex",
    "lastName": "Example",
    "email": "alex@example.com",
    "contractType": "PERMANENT",
    "weeklyHours": 42,
    "locationIds": [
      "00000000-0000-4000-8000-0000000000b1"
    ],
    "positionIds": [
      "00000000-0000-4000-8000-0000000000a1"
    ]
  }
]
GET/locationsBerechtigunglocations:read

Standorte auflisten

Gibt die Standorte der Organisation zurück, nach Name sortiert.

  • Dieser Aufruf nimmt keine Parameter entgegen.

Antwort

200 Ein Array von Objekten Standort, in einer einzigen Antwort.

Anfrage
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Antwort · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000b1",
    "name": "Lausanne Centre",
    "address": "Example street 1, 1000 Lausanne",
    "timezone": "Europe/Zurich"
  }
]
GET/positionsBerechtigungpositions:read

Positionen auflisten

Gibt die Positionen der Organisation zurück, nach Name sortiert.

  • Dieser Aufruf nimmt keine Parameter entgegen.

Antwort

200 Ein Array von Objekten Position, in einer einzigen Antwort.

Anfrage
curl "https://api.swissplanif.ch/api/v1/positions" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Antwort · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000a1",
    "name": "Front desk",
    "color": "#6366f1",
    "requiredSkills": []
  }
]

Fehler

Lies zuerst den HTTP-Status: Er ist massgebend. Die meisten Fehler haben den Standardkörper unten, mit einer message auf Englisch.

403
{
  "message": "Missing scope: shifts:write",
  "error": "Forbidden",
  "statusCode": 403
}
400Bad Request
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

  1. Anfragekörper abgelehnt: message lautet Validation failed, und issues listet jedes betroffene Feld auf.

    400
    {
      "message": "Validation failed",
      "issues": [
        {
          "expected": "string",
          "code": "invalid_type",
          "path": [
            "positionId"
          ],
          "message": "Invalid input: expected string, received undefined"
        }
      ]
    }
  2. 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"
      ]
    }
  3. Ü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.

Was du erhältst

POST
POST /webhooks/swissplanif HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-SwissPlanif-Event: shift.published
X-SwissPlanif-Signature: sha256=<hex digest>
X-SwissPlanif-Delivery-Id: 00000000-0000-7000-8000-000000000101

{
  "event": "shift.published",
  "tenantId": "00000000-0000-4000-8000-0000000000d1",
  "occurredAt": "2026-11-13T16:02:11.000Z",
  "data": {
    "shiftId": "00000000-0000-4000-8000-000000000001",
    "scheduleId": "00000000-0000-4000-8000-0000000000e1",
    "publicationId": "00000000-0000-4000-8000-0000000000f1",
    "employeeId": "00000000-0000-4000-8000-0000000000c1",
    "locationId": "00000000-0000-4000-8000-0000000000b1",
    "start": "2026-11-16T07:00:00.000Z",
    "end": "2026-11-16T15:00:00.000Z",
    "weekStart": "2026-11-15T23:00:00.000Z",
    "publishedAt": "2026-11-13T16:02:10.000Z"
  }
}
X-SwissPlanif-Signature
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

  1. Lies den rohen Körper, Byte für Byte, vor jeder JSON-Dekodierung.
  2. Berechne seinen HMAC-SHA-256 mit deinem Secret und vergleiche ihn zeitkonstant mit dem Header.
  3. 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.
  4. 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

  1. Ein 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.

  2. Der 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.

  3. Rufe 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.

  4. Ersetze 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.

  5. Im Zweifel widerrufen

    Der Widerruf wirkt ab dem nächsten Aufruf. Ein durchgesickerter Schlüssel gilt als gelesen.

  6. Protokolliere den Schlüssel nicht

    Maskiere den Header Authorization in deinen Logs, deinen Debugging-Werkzeugen und deinen Fehlerberichten.

  7. Prü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.

  8. Behandle 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.

  9. Validiere, 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.
Keine veröffentlichte OpenAPI-Beschreibung
Diese Seite ist die Referenz.
Öffentliche API — SwissPlanif · SwissPlanif