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. Der öffentliche Vertrag dokumentiert genau eine produktive Basis-URL:
Interne Entwicklungs- oder Stage-Hosts sind nicht Bestandteil des kundenorientierten Vertrags und dürfen nicht in öffentliche Client-Konfigurationen eingebettet werden.

​
Dry Run im Vergleich zu einer separaten Umgebung

dryRun=true ist ein Request-Modus für unterstützte Schreiboperationen. Er ist keine Sandbox und verwendet keine getrennte Datenbank.

​
Sichere Teststrategie

1

Dedizierten Key verwenden

Erstellen Sie einen Key mit dem kleinstmöglichen Unternehmens- und Divisionsscope, der für Entwicklung oder Abnahmetests erforderlich ist.
2

Abgestimmte Testdatensätze verwenden

Stimmen Sie Testmitarbeiter, Bestellungen, Vorfälle, Divisionen und Payroll-Zeiträume mit den verantwortlichen Kundenadministratoren ab.
3

Schreibvorgänge zuerst validieren

Verwenden Sie dryRun=true bei unterstützten Operationen und prüfen Sie die projizierte Ressource sowie das Fehlerverhalten.
4

Kontrollierten Schreibvorgang ausführen

Führen Sie im abgestimmten Scope genau eine reale Anfrage aus und prüfen Sie Speicherung und sämtliche Side Effects.
5

Wiederherstellung testen

Testen Sie Timeouts, 409, 422, 429 und die Deaktivierung von Zugangsdaten, bevor Sie die Automatisierung aktivieren.

​
Was der Health-Endpoint bestätigt und was nicht

GET /health bestätigt, dass die Public API erreichbar ist und ihre Health-Antwort zurückgeben kann. Der Endpoint bestätigt nicht:
  • die Gültigkeit des API-Keys
  • den Tenant- oder Divisionsscope
  • den Zugriff auf eine konkrete Ressource
  • die Verfügbarkeit einer nachgelagerten Dokumentdatei
  • die Korrektheit eines Write-Payloads
Verwenden Sie mindestens einen geschützten Read und einen unterstützten Dry Run für eine End-to-End-Prüfung der Integration.
Verwenden Sie keinen undokumentierten internen Host als Fallback. Ein Client muss sicher fehlschlagen, wenn die produktive Basis-URL nicht verfügbar ist.
Zuletzt geändert am 20. Oktober 2026