Zum Hauptinhalt springen

​
API 2.0.0: Aktiver Vertrag erforderlich

POST /incidents erfordert einen Vertrag mit Status active. Der Status approved reicht nicht aus. Ohne aktiven Vertrag scheitert die Anfrage mit HTTP 422 und EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, auch bei dryRun=true; es wird kein Vorfall erstellt. Klären Sie den Vertragsstatus über den zuständigen Fachprozess, bevor Sie eine neue Anfrage mit neuer X-Request-ID senden. Bestehende Vorfälle bleiben unter ihren bisherigen Lebenszyklus- und Feldbeschränkungen bearbeitbar. Die neue Voraussetzung gilt für das Erstellen. Die Voraussetzung der Mitarbeiteraktivierung bleibt separat dokumentiert; eine Reihenfolge der Validierungsfehler ist nicht festgelegt.

​
API 2.0.0: Sperränderungen bei aktiven Verträgen

Bei PATCH /employees/{id} verbietet ein aktiver Vertrag sowohl blocked: true als auch blocked: false. Enthält die Anfrage blocked, lehnt die API den gesamten Patch mit HTTP 422 und EMPLOYEE_HAS_ACTIVE_CONTRACT ab, auch bei dryRun=true. Andere Felder dieser abgelehnten Anfrage werden nicht übernommen. Auch das erneute Senden des bereits gespeicherten blocked-Werts ist unzulässig. Für reine Profiländerungen lassen Sie blocked vollständig weg. Konfigurieren Sie Serialisierung und Synchronisationsmapping so, dass blocked: false nicht als Standardwert hinzugefügt wird. Beispiel:
Wiederholen Sie einen unveränderten abgelehnten Patch nicht. Klären Sie den Sperrauftrag über den zuständigen Fachprozess oder senden Sie für eine unabhängig beabsichtigte Profiländerung einen neuen Patch ausschließlich mit den gewünschten unterstützten Profilfeldern. Ein erfolgreicher Dry Run reserviert den Vertragsstatus nicht; behandeln Sie dieselbe Validierung beim realen Schreibvorgang. Verwenden Sie diese Checkliste, bevor Sie einen automatisierten produktiven Zeitplan aktivieren.

​
Zugriff und Secrets

  • Für diese Integration existiert ein dedizierter API-Key
  • Der Key-Name bezeichnet System, Zweck und Umgebung
  • Der Key besitzt nur den kleinstmöglichen erforderlichen Unternehmens- und Divisionsscope
  • Der Key wird in einem verwalteten Secret Store gespeichert
  • Der Key ist nicht in Quellcode, Logs, Tickets oder Screenshots enthalten
  • Ein Verfahren für Key-Rotation und Notfalldeaktivierung wurde getestet

​
Request-Verhalten

  • Jede Anfrage besitzt einen expliziten Timeout
  • Für jeden logischen Versuch wird eine X-Request-ID erzeugt und protokolliert
  • X-Tenant-ID wird überall gesendet, wo die Zuordnung sonst mehrdeutig wäre
  • Unbekannte Felder werden nicht gesendet
  • JSON-Anfragen verwenden application/json
  • Attachment-Uploads halten die dokumentierten Vorgaben für Multipart-Feld, Typ, Anzahl und Größe ein

​
Korrektheit der Synchronisation

  • Stabile systemübergreifende Identifikatoren werden gespeichert
  • Die Pagination läuft bis zur dokumentierten letzten Seite
  • Ein festes Filterfenster oder ein Checkpoint verhindert unbeabsichtigte Datenlücken
  • null, ausgelassene Eigenschaften und leere Strings werden unterschiedlich behandelt
  • Neue Enum-Werte und unbekannte Response-Eigenschaften führen nicht zum Absturz des Clients
  • Teilfehler werden protokolliert und können sicher fortgesetzt werden

​
Schreibvorgänge und Retries

  • Unterstützte Schreibvorgänge werden, wo sinnvoll, mit dryRun=true validiert
  • Dry Runs werden weder als Reservierung noch als getrennte Umgebung behandelt
  • POST- und Statusübergangs-Anfragen werden nach einem Timeout niemals blind wiederholt
  • Mehrdeutige Ergebnisse von Schreibvorgängen werden durch erneutes Lesen der Ressource abgeglichen
  • 409 und 422 werden als fachliche oder Validierungsergebnisse behandelt, nicht als transiente Fehler
  • Bei 429 wird Retry-After berücksichtigt
  • Read-Retries verwenden begrenztes exponentielles Backoff und ein Retry-Budget

​
Beobachtbarkeit

  • Logs enthalten Operation, HTTP-Status, Fehlercode, Tenant-Kontext und Request-ID
  • Logs enthalten weder API-Keys noch unnötige personenbezogene Daten
  • Alerts existieren für anhaltende Authentifizierungs-, Autorisierungs-, Validierungs-, Rate-Limit- und 5xx-Fehler
  • Ein Dashboard oder Bericht zeigt Synchronisations-Checkpoints und ungelöste Datensätze
  • Die vom Client verwendete OpenAPI-Vertragsversion wird dokumentiert

​
Betrieb und Support

  • Für die Integration ist ein Verantwortlicher benannt
  • Ein Runbook beschreibt Neustart, Rollback, Key-Rotation und Incident Response
  • Supportanfragen enthalten UTC-Zeit, Methode, Pfad, Status, Fehlercode und Request-ID
  • Heruntergeladene Payroll- und Incident-Dateien werden durch geeignete lokale Zugriffskontrollen geschützt
  • Aufbewahrungs- und Löschregeln für lokale Logs und Dateien sind definiert
  • Der aktuelle Changelog sowie Funktionen und Einschränkungen wurden geprüft
Das Bestehen dieser Checkliste ersetzt keine kundenspezifische Abnahme. Validieren Sie Mappings, Berechtigungen, Side Effects und nachgelagerte Importe gemeinsam mit den fachlich Verantwortlichen.
Zuletzt geändert am 20. Oktober 2026