Kostenpflichtige API · Abonnement

API-Referenz für Entwickler (kostenpflichtig)

Binden Sie die produktive API zur Übermittlung von Dienstplänen per API-Schlüssel an, der an Ihr kostenpflichtiges Abonnement gebunden ist. Mandantenweite Standardzeiten speichern Sie mit PATCH /v1/schedule-defaults; Wochen-Schichtwünsche pro Mitarbeiter lesen/ersetzen Sie mit GET/PUT /v1/staff/{staffId}/weekly-shift-wish. Die Abrechnung folgt Ihrem Plan und Vertrag (keine nutzungsabhängige API-Gebühr pro Aufruf). Diese Seite beschreibt Berechtigungen, Validierungsregeln und Fehlercodes — nutzen Sie die Seitenleiste, um Felder zu finden.

Diese Seite beschreibt nur die Produkt-REST-API auf API Gateway ({stage}/v1/*, Authentifizierung mit x-api-key).

Next.js-/api/*-Routen (Stripe-Webhooks, OG-Bilder, Web Vitals usw.) sind intern zur Webanwendung und gehören nicht zu dieser Entwickler-API. Verwenden Sie sie nicht für externe Integrationen.

GET /v1/processing-history wird nicht angeboten (mit der alten Oberfläche entfernt) und ist nicht in der Endpunktliste auf dieser Seite enthalten.

Diese HTTP-API ist Teil des kostenpflichtigen Produkts: Der Zugriff setzt eine aktive kommerzielle Vereinbarung voraus; Schlüssel werden nach dem Onboarding für Ihre Organisation ausgestellt.

Die Abrechnung basiert auf Abonnement und Vertrag. Bei kostenpflichtigen Plänen richten sich die Gebühren typischerweise nach registrierten Mitarbeiterplätzen pro Monat (siehe Preisseite).

Playground-/Free-Tier-Limits gelten nicht für kostenpflichtige API-Schlüssel. Effektive Grenzen (Spanne, Mitarbeiterzahl, 15-Minuten-Raster) ergeben sich aus Ihren kostenpflichtigen Berechtigungen. Siehe Limits und Standardwerte auf dieser Seite.

Anfragen müssen einen gültigen API-Schlüssel enthalten, der im Rahmen Ihres kostenpflichtigen Abonnements ausgestellt wurde. Erstellung, Rotation und Widerruf erfolgen im Konto nach der Anmeldung.

Senden Sie den Schlüssel im Header x-api-key. Schlüssel sind an Ihre Organisation für Mandantenauflösung und vertragliche Zugriffsgrenzen gebunden.

Schlüssel verwalten: API-Verwaltung

Übermitteln Sie eine Planbedingung als JSON. Dies ist die kostenpflichtige Integrationsschnittstelle; die genaue Basis-URL wird pro Umgebung nach Freischaltung Ihres API-Zugangs mitgeteilt.

POST {baseUrl}/v1/schedule

Verwenden Sie die Basis-URL, die bei der Freischaltung Ihres API-Zugangs mitgeteilt wurde oder von Ihrem Betriebsteam bereitgestellt wird.

Ersetzen Sie BASE_URL durch die API-Basis-URL (Pfadpräfix), die Ihnen bei der Freischaltung mitgeteilt wurde.

Senden Sie Ihren API-Schlüssel im Header **x-api-key**. Ihre Organisation (Mandant) wird aus dem Schlüssel ermittelt — Sie übergeben keine separate Mandanten-ID in der Abfragezeichenkette.

Das Lesen und Aktualisieren von Unternehmensdaten (GET/PATCH /v1/company) erfordert ein aktives kostenpflichtiges Abonnement. Wenn die Abrechnung für Ihren Mandanten nicht konfiguriert ist, kann **503** zurückkommen (z. B. Code **STRIPE_NOT_CONFIGURED**).

curl-Beispiel (bash / macOS / Linux / WSL)

Windows PowerShell: Ein abschließender `\` ist **kein** Zeilenfortsetzungszeichen. Schreiben Sie eine Zeile, oder setzen Sie am Zeilenende ein Backtick (`) für die Fortsetzung.

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/schedule-results?limit=10"

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/company"

Gleiche Basis-URL und x-api-key wie bei POST /v1/schedule. Optionale Abfrageparameter: limit (1–100, Standard 50), cursor (undurchsichtiges Token aus dem Feld nextCursor der vorherigen Antwort).

GET /v1/company und Unternehmensaktualisierungen erfordern ein aktives kostenpflichtiges Abonnement. Wenn die Abrechnung nicht konfiguriert ist, kann **503 / STRIPE_NOT_CONFIGURED** zurückkommen.

Methode	Pfad	Beschreibung
GET	{baseUrl}/v1/schedule-results	Listet SCHEDULE_RESULT-Elternzeilen: conditionId, status, candidateCount, createdAt/updatedAt usw. DynamoDB-Elternzeilen-Paginierung.
GET	{baseUrl}/v1/schedule-results/history	Verlaufssuche für Planungsergebnisse (wie Browser-Verlauf). Optional from / to (ISO 8601, Standard Dienstbeginn bis jetzt), keyword, eventName (kommagetrennt INSERT,MODIFY,REMOVE), limit, cursor. Führt aktuelle und Archivdaten automatisch zusammen; nur items / nextCursor.
GET	{baseUrl}/v1/schedule-results/{conditionId}	Holt eine SCHEDULE_RESULT-Elternzeile per conditionId (JSON-Attribute; PK/SK weggelassen).
GET	{baseUrl}/v1/schedule-results/{conditionId}/resolution	Aufgelöste Optimierungsausgabe: status, candidates, confirmedAssignments falls vorhanden. Bei status completed und noch nicht bestätigt kann rank-1 bei diesem GET automatisch bestätigt werden (Nebenwirkung). Manuelle Bestätigung über POST …/confirm-assignments.
GET	{baseUrl}/v1/schedule-results/{conditionId}/review	Review-Payload für manuelle Bestätigung (Kandidaten, requiredByCellKey, allowedCellKeys der Mitarbeitenden usw.).
GET	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context	Kontext für Notfall-Schicht (Kalendertage, Personal, Slots). Kostenpflichtiges Abo erforderlich; null wenn Bedingung fehlt.
GET	{baseUrl}/v1/schedule-conditions	Listet SCHEDULE_CONDITION-Elternzeilen (conditionId, Daten, optional publicApiCancelledAt).
GET	{baseUrl}/v1/schedule-conditions/{conditionId}	Bedingungs-Elternzeile plus reqDays und staffSnapshots (ohne PK/SK).
GET	{baseUrl}/v1/audit-logs	Listet Audit-Log-Einträge (neueste zuerst; Cursor-Paginierung).
GET	{baseUrl}/v1/schedule-defaults	Mandanten-Planungsstandardzeile (SCHEDULE_DEFAULTS) oder null, wenn noch nicht gespeichert.
GET	{baseUrl}/v1/schedule-actual/{conditionId}	SCHEDULE_ACTUAL-Zeile für Ist-Schichten oder null, wenn keine vorhanden.
GET	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Wochen-Wunschzeile des Mitarbeitenden oder null, wenn keine vorhanden.
GET	{baseUrl}/v1/company	Liefert Stripe-Customer-Felder (Name, E-Mail, Telefon, Adresse) zur customerId Ihres API-Schlüssels.
GET	{baseUrl}/v1/users	Listet Mandantenbenutzer (optional: limit, cursor, userName, permissionProfileId, scope fullAccess\|nonFullAccess).
GET	{baseUrl}/v1/users/{userId}	Holt einen Benutzer anhand der userId im Pfad.
GET	{baseUrl}/v1/staff	Listet aktive Mitarbeitende des Mandanten (sortiert nach Anzeigename).
GET	{baseUrl}/v1/staff/{staffId}	Holt einen Mitarbeitenden per staffId inkl. Arbeitsdetails (laborLawCompliance, laborFlsaExempt, persönliche Obergrenzen, laborConstraintMask). Soft-Delete → 404.

Gleicher API-Schlüssel mit JSON-Body. PATCH /v1/company lehnt leere Strings für Felder wie den Firmennamen ab (wie in der Web-App). PATCH /v1/schedule-defaults speichert mandantenweite Standardwerte (requirementsByCellKey, Planungshorizont usw.); kostenpflichtige Felder folgen Ihrem Abonnement. PUT /v1/staff/{staffId}/weekly-shift-wish ersetzt das komplette Wochen-Wunschraster (siehe Validierungshinweis). DELETE /v1/users/{userId} liefert 409, wenn danach kein aktiver Nutzer übrig bliebe oder der letzte Admin entfernt würde. POST /v1/staff liefert 409 STAFF_LIMIT, wenn die Liste das Mandantenlimit überschreiten würde.

POST /v1/users erfordert userName, email, permissionProfileId; optional: locale, password. PATCH Nutzer: nur geänderte Felder. POST /v1/staff: nur JSON { "displayName": "..." }. PATCH /v1/staff/{staffId}: displayName, laborLawCompliance, laborFlsaExempt, personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes (Ganzzahl oder null), laborConstraintMask (Objekt oder null bei laborLawCompliance true) — Arbeitsfelder kostenpflichtig. POST /v1/schedule-results/{conditionId}/emergency-shift: absentStaffIds, absentDatesYmd und/oder absentSlots (kostenpflichtig, Quellplan abgeschlossen). POST …/confirm-assignments: assignments-Array und optionales relaxAvailability. PATCH /v1/schedule-defaults: PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12. PUT /v1/staff/{staffId}/weekly-shift-wish: scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey.

Methode	Pfad	Beschreibung
PATCH	{baseUrl}/v1/company	Aktualisiert Unternehmensprofilfelder (Abrechnungskunde).
PATCH	{baseUrl}/v1/schedule-defaults	Speichert Planungs-Standardwerte des Mandanten (JSON-Body wie saveSchema in schedule-defaults-actions). Kostenpflichtige Felder folgen Ihrem Abonnement.
POST	{baseUrl}/v1/users	Legt einen Benutzer an. Antwort 201 mit JSON-Benutzer.
PATCH	{baseUrl}/v1/users/{userId}	Aktualisiert Benutzerfelder (userName, email, permissionProfileId, locale).
DELETE	{baseUrl}/v1/users/{userId}	Löscht einen Benutzer. 409 bei keinem verbleibenden Nutzer oder letztem Admin.
POST	{baseUrl}/v1/staff	Legt einen Mitarbeitenden an (displayName). Antwort 201 mit staff-JSON.
POST	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift	Klont abgeschlossenen Quellplan mit Abwesenheiten; antwortet 201 mit conditionId. Kostenpflichtiges Abo erforderlich.
POST	{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments	Validiert und speichert manuell bearbeitete Zuweisungen (200 mit { ok: true }).
PATCH	{baseUrl}/v1/staff/{staffId}	Aktualisiert displayName und Arbeitsdetails (laborLawCompliance, laborFlsaExempt, persönliche Obergrenzen, laborConstraintMask).
DELETE	{baseUrl}/v1/staff/{staffId}	Soft-Delete eines Mitarbeitenden (setzt deletedAt).
DELETE	{baseUrl}/v1/schedule-conditions/{conditionId}	Markiert die Bedingung als storniert (publicApiCancelledAt); löscht keine Kindzeilen.
PUT	{baseUrl}/v1/schedule-actual/{conditionId}	Speichert Ist-Zuweisungen JSON { "assignments": [ ... ] } (gegen das Bedingungsraster validiert).
PUT	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Ersetzt Wochen-Wünsche: volles Raster (1–7 Tage), wishByCellKey pro Zelle (NONE\|LOW\|HIGH); Granularität aus Mandanten-Standardwerten.
POST	{baseUrl}/v1/users/{userId}/restore	Stellt einen per Soft-Delete entfernten Benutzer wieder her.

Header	Beschreibung
x-api-key	API-Schlüssel für Ihr kostenpflichtiges Abonnement (identifiziert Mandant und Planlimits).
Content-Type	application/json

Antwort-Header

Einige Antwort-Header (z. B. Request-IDs) sind Trace-Metadaten, nicht Ihr API-Schlüssel. Behandeln Sie JSON-**Antworttexte** vertraulich, wenn sie Firmen- oder Nutzerdaten enthalten.

Typische Validierungsgrenzen für Ihren Vertrag (15-Minuten-Raster, Planungsspanne, registrierte Mitarbeiterzahl und verwandte Obergrenzen).

Einstellung	Kostenpflichtige API (typisch)
Abrechnungsmodell	Stripe-Abonnement; Produktgebühren skalieren typischerweise mit den registrierten Mitarbeiter-Plätzen gemäß Preisseite (keine Gebühr pro API-Aufruf).
maxScheduleDays	Bis zu 14 Kalendertage pro Übermittlung für die Standard-Zwei-Wochen-Detailplanung (längere Spannen nur bei vertraglicher Freigabe).
maxStaffPerSchedule	Bis zu 500 staff-Zeilen pro POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; Inline-staffId im Body).
maxRosterStaff	Bis zu 30 aktive Mitarbeitende über POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT bei Überschreitung.
allowedGranularities	[60, 15] — 15-Minuten-Slots sind kostenpflichtig; 60 Minuten werden ebenfalls unterstützt.
maxPayloadBytes	524288 (512 KiB) UTF-8, sofern kein höheres Limit gewährt wurde.
strictUnknownRootKeys	true — unbekannte Keys auf Root-Ebene oder in staff werden abgelehnt

Der erforderliche Personalbedarf pro Zelle bleibt eine ganze Zahl von 0 bis 15. Bei Überschreitung von Ratenlimits kann eine Fehlerantwort zurückkommen.

Ist der Strict-Modus aktiv, werden nur die folgenden Keys auf oberster Ebene akzeptiert. Jeder andere Key liefert UNKNOWN_FIELD.

apiVersion
timeZone
scheduleStartDate
scheduleEndDate
timeRangeStart
timeRangeEnd
slotGranularityMinutes
requirementsByCell
staff

Der Payload folgt dem kostenpflichtigen öffentlichen Modell: Kalendertage, Zeitzone, Slot-Raster (60 oder 15 Minuten), Bedarf pro Zelle und Mitarbeiterverfügbarkeit. Arbeitsrechts-Hoheit, kostenpflichtige Optimierungs-Flags und arbeitsrechtliche Felder auf Mitarbeiterebene gehören nicht zum JSON — der Server schreibt Standardwerte in die übergeordnete SCHEDULE_CONDITION-Zeile (siehe „Arbeitsrecht und kostenpflichtige Flags“). DynamoDB-Keys und interne Entitätstypen dürfen nicht im Body stehen.

apiVersion — Optional. Wenn gesetzt, nur die unterstützte Schemaversionszeichenkette.
cellKey-Format — Keys in requirementsByCell und availableCells müssen `${date}__${slotId}` entsprechen, wobei date im Planungsbereich YYYY-MM-DD ist und slotId aus den für Zeitraum und Raster ermittelten Slots stammt (wie `cellKey` in den Playground-Hilfen).

Feld	Typ	Erforderlich	Hinweise
timeZone	string	Ja	IANA-Zeitzone zur Interpretation von Daten und Slots.
scheduleStartDate / scheduleEndDate	string (YYYY-MM-DD)	Ja	Kalenderbereich inklusiv; Start ≤ Ende.
timeRangeStart / timeRangeEnd	string (HH:mm)	Ja	Wanduhr-Zeitraum, der die Slot-Spalte definiert; muss mindestens einen Slot ergeben.
slotGranularityMinutes	60 \| 15	Ja	Kostenpflichtige API: 60 (stündlich) oder 15 (Viertelstunden). Muss in allowedGranularities enthalten sein.
requirementsByCell	object	Ja	Keys = cellKey im berechneten Raster; Werte = ganze Zahl 0–15.
staff	array	Ja	Nicht leer; maximale Größe siehe Limits; pro Eintrag: staffId, displayName, optional availableCells.

Felderreferenz (erlaubte Werte)

Die folgenden Abschnitte entsprechen dem Validator in `app/lib/public-schedule-api/validate.ts` und den Bereinigungen in `sanitize.ts`, mit den Standardwerten aus `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS`, sofern keine Optionen gesetzt sind. JSON-Zahlen bitte als echte Zahlen senden (nicht als Strings). Nach der Validierung ergänzt `build-schedule-transact-items.ts` Felder der übergeordneten Zeile (Kopie der kostenpflichtigen Optimierung, Arbeitsrechts-Hoheit, Modellversion), die keine Request-Keys sind — siehe „Arbeitsrecht und kostenpflichtige Flags“.

Erlaubte Werte

Ausgelassen: akzeptiert (aktuelles Verhalten).
Wenn gesetzt, exakt "2026-04-01" (PUBLIC_SCHEDULE_API_VERSION).
Jede andere Zeichenkette wird abgelehnt (TYPE_ERROR).

Verhalten

Vergleich nach trim-äquivalenter Verarbeitung in sanitizeApiVersion.

Typische Fehler

TYPE_ERRORNicht unterstützter apiVersion-Wert.

Erlaubte Werte

Übertragung als einzelne Zeichenkette. Die API veröffentlicht keine vollständige Enum aller erlaubten Zonen: der Server validiert dynamisch.
Validierung entspricht `isValidIanaTimeZone`: Luxon `DateTime.now().setZone(zone).isValid` muss true sein.
Verwenden Sie kanonische IANA-Bezeichner, z. B. `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`.
Nur Abkürzungen wie `EST`, `JST`, `GMT` sind keine stabilen IANA-IDs und können abgelehnt werden.
Listen: IANA-TZ-Distribution (https://www.iana.org/time-zones) oder die Zeitzone-API Ihrer Plattform.

Verhalten

Wird für Daten und Slot-Zeiten in der Normalisierung verwendet.
Für eine feste Client-Liste dieselben Regeln (IANA-IDs) ableiten, nicht auf eine Server-Enum im JSON-Schema vertrauen.

Typische Fehler

INVALID_TIME_ZONEFehlt, leer oder keine gültige IANA-Zone.

Erlaubte Werte

Muss /^\d{4}-\d{2}-\d{2}$/ (getrimmt) entsprechen.
Echte Kalendertage; der inklusive Bereich muss mindestens einen Tag über enumerateDates ergeben.
Anzahl der Tage darf maxScheduleDays nicht überschreiten (kostenpflichtige API typisch bis 14 Tage; genaues Limit = Mandantenberechtigung).

Verhalten

scheduleStartDate muss vor oder am scheduleEndDate liegen.

Typische Fehler

INVALID_DATE_RANGEFalsches Format, ungültige Daten oder leerer Bereich.
SCHEDULE_SPAN_TOO_LONGMehr als maxScheduleDays Tage.

Erlaubte Werte

Nicht leere Strings (getrimmt), gleiche Slot-Ermittlung wie in der UI (`enumerateSlotsByGranularity`).
Das Paar muss mindestens einen Slot erzeugen, sonst schlägt die Validierung fehl.

Verhalten

Definiert zusammen mit slotGranularityMinutes die slotId-Werte für cellKey.

Typische Fehler

INVALID_TIME_RANGEFehlende Werte oder null Slots für den Bereich.

Erlaubte Werte

Exakt 60 oder 15 (nicht als String).
Muss in allowedGranularities vorkommen. Bei der kostenpflichtigen API sind meist beide erlaubt; wenn 15 für den Mandanten deaktiviert ist: INVALID_GRANULARITY.

Verhalten

Bestimmt zusammen mit dem Zeitraum die Slot-Anzahl.

Typische Fehler

INVALID_GRANULARITYNicht 60/15 oder im Plan nicht erlaubt.

Erlaubte Werte

Plain JSON-Objekt (kein Array).
Jeder Key muss ein cellKey im erwarteten Raster (Daten × slotIds) sein. Unbekannte Keys → UNKNOWN_CELL_KEY.
Jeder Wert: JSON-Zahl, ganzzahlig, 0 bis 15 inklusive.
Fehlende Zellen gelten als Bedarf 0 (SHORTFALL nur bei Bedarf ≥ 1).

Verhalten

Keys werden nach trim über sanitizeCellKey verglichen.

Typische Fehler

INVALID_REQUIREMENTSKein Objekt oder ungültiger Zahlenwert.
UNKNOWN_CELL_KEYKey nicht im berechneten Datums-Slot-Raster.

Erlaubte Werte

Länge zwischen 1 und maxStaffPerSchedule (Standard 500 für POST /v1/schedule; getrennt vom Listenlimit für POST /v1/staff).
Jedes Element: Plain-Objekt nur mit erlaubten Keys: staffId, displayName, availableCells (Strict-Modus).
staffId und displayName müssen die Bereinigung überstehen (Abschnitt Bereinigung).
staffId muss im Array eindeutig sein (DUPLICATE_STAFF_ID).

Verhalten

Reihenfolge bleibt für die Verfügbarkeitszählung erhalten.

Typische Fehler

INVALID_STAFFLeeres Array, zu viele Zeilen, ungültiges Objekt oder Bereinigung fehlgeschlagen.
UNKNOWN_FIELDZusätzlicher Key am staff-Objekt im Strict-Modus.
DUPLICATE_STAFF_IDDerselbe staffId zweimal.

Erlaubte Werte

Ausgelassen: Mitarbeiter gilt auf allen Zellen des Rasters als verfügbar (intern null = „alle Zellen“).
Wenn gesetzt: JSON-Array von Strings; jeder nicht leere String muss ein cellKey im erwarteten Raster sein.
Leere Strings im Array sind ungültig (INVALID_AVAILABLE_CELL).

SHORTFALL-Prüfung

Für jede Zelle mit Bedarf ≥ 1 muss die Anzahl verfügbarer Mitarbeiter ≥ Bedarf sein, sonst SHORTFALL_CELLS.

Typische Fehler

INVALID_AVAILABLE_CELLUnbekannter cellKey oder leerer Eintrag.
SHORTFALL_CELLSZu wenig Personal für den erforderlichen Bedarf in einer Zelle.

Was die API in der übergeordneten Zeile speichert

Die öffentliche API akzeptiert nur ROOT_KEYS auf oberster Ebene und STAFF_KEYS pro Mitarbeiterzeile. Senden Sie nicht laborLawJurisdiction, usLaborStateCode, laborModelVersion oder paidOptimization.
Bei Übermittlung setzt der Server die übergeordnete SCHEDULE_CONDITION aus gemeinsamen Standardwerten: paidOptimization = DEFAULT_PAID_OPTIMIZATION — laborLawCompliance false; balanceStaffLoad, honorShiftWishes und preferConsecutiveShifts true (siehe schedule-defaults-shared.ts und build-schedule-transact-items.ts). laborLawJurisdiction JP, usLaborStateCode GENERIC, laborModelVersion v1.
Gesetzliche Arbeitszeitgrenzen im Optimierer erfordern sowohl übergeordnete als auch pro-Mitarbeiter-Compliance-Flags; dieser Pfad lässt sie aus, erwarten Sie daher keine gesetzlichen Obergrenzen allein aus diesem JSON.
Das Arbeitszeitmodell ist eine Näherung für die Planung, keine Rechtsberatung. Katalog: optimizer/config/labor_models.json.

Dokumentation

Ausführlich: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 und §3.1.

Bei unzulässigen Keys

UNKNOWN_FIELDStrict-Modus lehnt unbekannte Root- oder staff-Eigenschaften ab.

Wie in `sanitize.ts` implementiert, vor oder während der Validierung. Diese Regeln erklären Ablehnungen als INVALID_STAFF.

staffId

Trim; Länge 1–128.
Zeichen müssen /^[a-zA-Z0-9._-]+$/ entsprechen (keine Schrägstriche oder Backslashes).

displayName

Steuerzeichen und Zero-Width entfernen; Leerzeichen zusammenführen; trim.
Winkelklammern < und > sind nicht erlaubt.
Max. 128 Zeichen nach Bereinigung; darf nicht leer werden.

Zell-Keys (requirements / availableCells)

Keys werden getrimmt; müssen exakt den cellKey-Strings im berechneten Raster entsprechen.

202 Accepted

Der Anfragetext hat die Validierung bestanden und die Bedingung wurde geschrieben; die Optimierung kann asynchron weiterlaufen. Der Handler kann einen JSON-Body mit conditionId usw. zurückgeben.

Validierungsfehler liefern strukturierte Informationen mit stabilem `code`. Parsen vor der Validierung (INVALID_JSON, PAYLOAD_TOO_LARGE). Persistenzfehler können als DYNAMODB_ERROR erscheinen. PATCH /v1/schedule-defaults kann SCHEDULE_DEFAULTS_SAVE_FAILED (HTTP 400) mit Details liefern.

Code	Bedeutung
INVALID_JSON	Body ist kein gültiges JSON.
PAYLOAD_TOO_LARGE	UTF-8-Byte-Länge überschreitet maxPayloadBytes (Standard 512 KiB).
TYPE_ERROR	Falscher JSON-Typ oder nicht unterstützte apiVersion-Zeichenkette.
UNKNOWN_FIELD	Strict-Modus: nicht erlaubte Eigenschaft auf Root oder staff-Objekt.
INVALID_TIME_ZONE	timeZone fehlt oder ist kein gültiger IANA-Name.
INVALID_DATE_RANGE	Daten nicht YYYY-MM-DD, ungültiger Bereich oder leere Aufzählung.
SCHEDULE_SPAN_TOO_LONG	Zu viele Tage zwischen Start und Ende (siehe maxScheduleDays).
INVALID_TIME_RANGE	Zeitraum fehlt oder ergibt null Slots.
INVALID_GRANULARITY	slotGranularityMinutes nicht 60/15 oder im Plan nicht erlaubt.
INVALID_REQUIREMENTS	requirementsByCell kein Objekt oder Zahl nicht 0–15.
UNKNOWN_CELL_KEY	Key nicht im berechneten Planungsraster.
INVALID_STAFF	staff leer, zu groß, ungültige Zeile oder Bereinigung fehlgeschlagen.
DUPLICATE_STAFF_ID	Doppelte staffId-Werte.
INVALID_AVAILABLE_CELL	Leerer oder unbekannter Eintrag in availableCells.
SHORTFALL_CELLS	Unzureichende Verfügbarkeit gegenüber dem Bedarf.
DYNAMODB_ERROR	Vorübergehender oder Persistenzfehler nach der Validierung (handlerabhängig).
SCHEDULE_DEFAULTS_SAVE_FAILED	PATCH /v1/schedule-defaults: Validierung oder Geschäftsregeln fehlgeschlagen (siehe error.details).
LABOR_COMPLIANCE_REQUIRED	PATCH /v1/staff/{staffId}: laborConstraintMask gesendet, obwohl laborLawCompliance false ist.

{
  "apiVersion": "2026-04-01",
  "timeZone": "Asia/Tokyo",
  "scheduleStartDate": "2026-04-07",
  "scheduleEndDate": "2026-04-13",
  "timeRangeStart": "08:00",
  "timeRangeEnd": "20:00",
  "slotGranularityMinutes": 60,
  "requirementsByCell": {
    "2026-04-07__slot-0": 2
  },
  "staff": [
    {
      "staffId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Example",
      "availableCells": ["2026-04-07__slot-0"]
    }
  ]
}

Weiterführende Links. Pläne und kostenpflichtige Funktionen: docs/architecture/NURSE_SCHEDULING_SERVICE_SPECIFICATION.md. Anfragetext von POST /v1/schedule: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §1–§11. Anfragetext von PATCH /v1/schedule-defaults (Mandanten-Standardwerte): dieselbe Datei §12. Implementierung: app/lib/public-schedule-api/, app/features/schedule-settings/schedule-defaults-actions.ts, app/lib/public-api-write/weekly-shift-wish-tenant.ts. Bereitstellung: docs/aws/CDK_DEPLOY.md.

API-Referenz für Entwickler (kostenpflichtig)

Methode

Pfad

Beschreibung

GET

{baseUrl}/v1/schedule-results

Listet SCHEDULE_RESULT-Elternzeilen: conditionId, status, candidateCount, createdAt/updatedAt usw. DynamoDB-Elternzeilen-Paginierung.

GET

{baseUrl}/v1/schedule-results/history

Verlaufssuche für Planungsergebnisse (wie Browser-Verlauf). Optional from / to (ISO 8601, Standard Dienstbeginn bis jetzt), keyword, eventName (kommagetrennt INSERT,MODIFY,REMOVE), limit, cursor. Führt aktuelle und Archivdaten automatisch zusammen; nur items / nextCursor.

GET

{baseUrl}/v1/schedule-results/{conditionId}

Holt eine SCHEDULE_RESULT-Elternzeile per conditionId (JSON-Attribute; PK/SK weggelassen).

GET

{baseUrl}/v1/schedule-results/{conditionId}/resolution

Aufgelöste Optimierungsausgabe: status, candidates, confirmedAssignments falls vorhanden. Bei status completed und noch nicht bestätigt kann rank-1 bei diesem GET automatisch bestätigt werden (Nebenwirkung). Manuelle Bestätigung über POST …/confirm-assignments.

GET

{baseUrl}/v1/schedule-results/{conditionId}/review

Review-Payload für manuelle Bestätigung (Kandidaten, requiredByCellKey, allowedCellKeys der Mitarbeitenden usw.).

GET

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context

Kontext für Notfall-Schicht (Kalendertage, Personal, Slots). Kostenpflichtiges Abo erforderlich; null wenn Bedingung fehlt.

GET

{baseUrl}/v1/schedule-conditions

Listet SCHEDULE_CONDITION-Elternzeilen (conditionId, Daten, optional publicApiCancelledAt).

GET

{baseUrl}/v1/schedule-conditions/{conditionId}

Bedingungs-Elternzeile plus reqDays und staffSnapshots (ohne PK/SK).

GET

{baseUrl}/v1/audit-logs

Listet Audit-Log-Einträge (neueste zuerst; Cursor-Paginierung).

GET

{baseUrl}/v1/schedule-defaults

Mandanten-Planungsstandardzeile (SCHEDULE_DEFAULTS) oder null, wenn noch nicht gespeichert.

GET

{baseUrl}/v1/schedule-actual/{conditionId}

SCHEDULE_ACTUAL-Zeile für Ist-Schichten oder null, wenn keine vorhanden.

GET

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Wochen-Wunschzeile des Mitarbeitenden oder null, wenn keine vorhanden.

GET

{baseUrl}/v1/company

Liefert Stripe-Customer-Felder (Name, E-Mail, Telefon, Adresse) zur customerId Ihres API-Schlüssels.

GET

{baseUrl}/v1/users

Listet Mandantenbenutzer (optional: limit, cursor, userName, permissionProfileId, scope fullAccess|nonFullAccess).

GET

{baseUrl}/v1/users/{userId}

Holt einen Benutzer anhand der userId im Pfad.

GET

{baseUrl}/v1/staff

Listet aktive Mitarbeitende des Mandanten (sortiert nach Anzeigename).

GET

{baseUrl}/v1/staff/{staffId}

Holt einen Mitarbeitenden per staffId inkl. Arbeitsdetails (laborLawCompliance, laborFlsaExempt, persönliche Obergrenzen, laborConstraintMask). Soft-Delete → 404.

Methode

Pfad

Beschreibung

PATCH

{baseUrl}/v1/company

Aktualisiert Unternehmensprofilfelder (Abrechnungskunde).

PATCH

{baseUrl}/v1/schedule-defaults

Speichert Planungs-Standardwerte des Mandanten (JSON-Body wie saveSchema in schedule-defaults-actions). Kostenpflichtige Felder folgen Ihrem Abonnement.

POST

{baseUrl}/v1/users

Legt einen Benutzer an. Antwort 201 mit JSON-Benutzer.

PATCH

{baseUrl}/v1/users/{userId}

Aktualisiert Benutzerfelder (userName, email, permissionProfileId, locale).

DELETE

{baseUrl}/v1/users/{userId}

Löscht einen Benutzer. 409 bei keinem verbleibenden Nutzer oder letztem Admin.

POST

{baseUrl}/v1/staff

Legt einen Mitarbeitenden an (displayName). Antwort 201 mit staff-JSON.

POST

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift

Klont abgeschlossenen Quellplan mit Abwesenheiten; antwortet 201 mit conditionId. Kostenpflichtiges Abo erforderlich.

POST

{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments

Validiert und speichert manuell bearbeitete Zuweisungen (200 mit { ok: true }).

PATCH

{baseUrl}/v1/staff/{staffId}

Aktualisiert displayName und Arbeitsdetails (laborLawCompliance, laborFlsaExempt, persönliche Obergrenzen, laborConstraintMask).

DELETE

{baseUrl}/v1/staff/{staffId}

Soft-Delete eines Mitarbeitenden (setzt deletedAt).

DELETE

{baseUrl}/v1/schedule-conditions/{conditionId}

Markiert die Bedingung als storniert (publicApiCancelledAt); löscht keine Kindzeilen.

PUT

{baseUrl}/v1/schedule-actual/{conditionId}

Speichert Ist-Zuweisungen JSON { "assignments": [ ... ] } (gegen das Bedingungsraster validiert).

PUT

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Ersetzt Wochen-Wünsche: volles Raster (1–7 Tage), wishByCellKey pro Zelle (NONE|LOW|HIGH); Granularität aus Mandanten-Standardwerten.

POST

{baseUrl}/v1/users/{userId}/restore

Stellt einen per Soft-Delete entfernten Benutzer wieder her.

Header

Beschreibung

x-api-key

API-Schlüssel für Ihr kostenpflichtiges Abonnement (identifiziert Mandant und Planlimits).

Content-Type

application/json

Einstellung

Kostenpflichtige API (typisch)

Abrechnungsmodell

Stripe-Abonnement; Produktgebühren skalieren typischerweise mit den registrierten Mitarbeiter-Plätzen gemäß Preisseite (keine Gebühr pro API-Aufruf).

maxScheduleDays

Bis zu 14 Kalendertage pro Übermittlung für die Standard-Zwei-Wochen-Detailplanung (längere Spannen nur bei vertraglicher Freigabe).

maxStaffPerSchedule

Bis zu 500 staff-Zeilen pro POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; Inline-staffId im Body).

maxRosterStaff

Bis zu 30 aktive Mitarbeitende über POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT bei Überschreitung.

allowedGranularities

[60, 15] — 15-Minuten-Slots sind kostenpflichtig; 60 Minuten werden ebenfalls unterstützt.

maxPayloadBytes

524288 (512 KiB) UTF-8, sofern kein höheres Limit gewährt wurde.

strictUnknownRootKeys

true — unbekannte Keys auf Root-Ebene oder in staff werden abgelehnt

Feld

Typ

Erforderlich

Hinweise

timeZone

string

IANA-Zeitzone zur Interpretation von Daten und Slots.

scheduleStartDate / scheduleEndDate

string (YYYY-MM-DD)

Kalenderbereich inklusiv; Start ≤ Ende.

timeRangeStart / timeRangeEnd

string (HH:mm)

Wanduhr-Zeitraum, der die Slot-Spalte definiert; muss mindestens einen Slot ergeben.

slotGranularityMinutes

60 | 15

Kostenpflichtige API: 60 (stündlich) oder 15 (Viertelstunden). Muss in allowedGranularities enthalten sein.

requirementsByCell

object

Keys = cellKey im berechneten Raster; Werte = ganze Zahl 0–15.

staff

array

Nicht leer; maximale Größe siehe Limits; pro Eintrag: staffId, displayName, optional availableCells.

Felderreferenz (erlaubte Werte)

Code

Bedeutung

INVALID_JSON

Body ist kein gültiges JSON.

PAYLOAD_TOO_LARGE

UTF-8-Byte-Länge überschreitet maxPayloadBytes (Standard 512 KiB).

TYPE_ERROR

Falscher JSON-Typ oder nicht unterstützte apiVersion-Zeichenkette.

UNKNOWN_FIELD

Strict-Modus: nicht erlaubte Eigenschaft auf Root oder staff-Objekt.

INVALID_TIME_ZONE

timeZone fehlt oder ist kein gültiger IANA-Name.

INVALID_DATE_RANGE

Daten nicht YYYY-MM-DD, ungültiger Bereich oder leere Aufzählung.

SCHEDULE_SPAN_TOO_LONG

Zu viele Tage zwischen Start und Ende (siehe maxScheduleDays).

INVALID_TIME_RANGE

Zeitraum fehlt oder ergibt null Slots.

INVALID_GRANULARITY

slotGranularityMinutes nicht 60/15 oder im Plan nicht erlaubt.

INVALID_REQUIREMENTS

requirementsByCell kein Objekt oder Zahl nicht 0–15.

UNKNOWN_CELL_KEY

Key nicht im berechneten Planungsraster.

INVALID_STAFF

staff leer, zu groß, ungültige Zeile oder Bereinigung fehlgeschlagen.

DUPLICATE_STAFF_ID

Doppelte staffId-Werte.

INVALID_AVAILABLE_CELL

Leerer oder unbekannter Eintrag in availableCells.

SHORTFALL_CELLS

Unzureichende Verfügbarkeit gegenüber dem Bedarf.

DYNAMODB_ERROR

Vorübergehender oder Persistenzfehler nach der Validierung (handlerabhängig).

SCHEDULE_DEFAULTS_SAVE_FAILED

PATCH /v1/schedule-defaults: Validierung oder Geschäftsregeln fehlgeschlagen (siehe error.details).

LABOR_COMPLIANCE_REQUIRED

PATCH /v1/staff/{staffId}: laborConstraintMask gesendet, obwohl laborLawCompliance false ist.

{ "apiVersion": "2026-04-01", "timeZone": "Asia/Tokyo", "scheduleStartDate": "2026-04-07", "scheduleEndDate": "2026-04-13", "timeRangeStart": "08:00", "timeRangeEnd": "20:00", "slotGranularityMinutes": 60, "requirementsByCell": { "2026-04-07__slot-0": 2 }, "staff": [ { "staffId": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Example", "availableCells": ["2026-04-07__slot-0"] } ] }

API-Referenz für Entwickler (kostenpflichtig)

Geltungsbereich dieser Dokumentation

Abonnement-Abrechnung und Zugriff

Authentifizierung

Endpunkt

Aufruf (Quickstart)

curl-Beispiel (bash / macOS / Linux / WSL)

Lese-API (GET)

Schreib-API (PATCH / POST / PUT / DELETE)

Header

Antwort-Header

Limits der kostenpflichtigen Stufe (Berechtigungen)

Erlaubte Root-Keys (Strict-Modus)

Anfragetext (Überblick)

Kurzübersichtstabelle

Felderreferenz (erlaubte Werte)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Arbeitsrecht und kostenpflichtige Optimierung (nicht im JSON-Body)

Regeln zur Bereinigung

Erfolgsantwort

Fehlercodes (vollständig)

Minimales JSON-Beispiel

API-Referenz für Entwickler (kostenpflichtig)

Geltungsbereich dieser Dokumentation

Abonnement-Abrechnung und Zugriff

Authentifizierung

Endpunkt

Aufruf (Quickstart)

curl-Beispiel (bash / macOS / Linux / WSL)

Lese-API (GET)

Schreib-API (PATCH / POST / PUT / DELETE)

Header

Antwort-Header

Limits der kostenpflichtigen Stufe (Berechtigungen)

Erlaubte Root-Keys (Strict-Modus)

Anfragetext (Überblick)

Kurzübersichtstabelle

Felderreferenz (erlaubte Werte)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Arbeitsrecht und kostenpflichtige Optimierung (nicht im JSON-Body)

Regeln zur Bereinigung

Erfolgsantwort

Fehlercodes (vollständig)

Minimales JSON-Beispiel