Workflow-Transitionen idempotent anfordern

Verwenden Sie Transition-Requests, wenn Ihre Integration einen Workflow-Übergang asynchron anstoßen und dessen Ergebnis zuverlässig verfolgen muss. 202 Accepted bestätigt nur die persistierte Annahme. Lesen Sie den fachlichen Abschluss über die zurückgegebene statusUrl.

Request senden

Senden Sie bei jedem Aufruf einen nichtleeren X-Idempotency-Key mit höchstens 255 Zeichen:

http
POST /api/v1/workflows/transition-requests HTTP/1.1
Authorization: Bearer <token>
X-Tenant-ID: <tenant-uuid>
X-Idempotency-Key: order-4711-confirm-v1
Content-Type: application/json

{
  "entity": "order",
  "entityId": "<order-uuid>",
  "transition": "confirm"
}

Der Workflow-Endpunkt akzeptiert höchstens 1 MiB Request-Body. PIM- Lifecycle-Adapter akzeptieren höchstens 64 KiB. Größere Requests antworten mit 413 Request Entity Too Large und werden weder als Transition-Request noch als Queue-Event gespeichert.

Retries korrekt behandeln

Verwenden Sie denselben Key erneut, solange Tenant, Endpunkt, authentifizierter Akteur, wirksame Berechtigungsobergrenze und fachliche Anforderung unverändert bleiben. Ein exakter Retry liefert erneut 202 Accepted mit derselben requestId, demselben Status und derselben statusUrl. Parallel eintreffende Retries erzeugen ebenfalls nur einen Request und ein Queue-Event.

Verwenden Sie keinen bereits belegten Key für eine andere Entity, Transition oder Nutzlast. Workspace antwortet dann mit 409 Conflict und ERR_IDEMPOTENCY_MISMATCH. Erzeugen Sie erst für eine neue fachliche Anforderung einen neuen Key.

Ein fehlender Key liefert 400 Bad Request und ERR_IDEMPOTENCY_KEY_REQUIRED. Behandeln Sie diesen Fehler als Integrationsfehler, nicht als transienten Retry.

Berechtigungen bei späterer Ausführung

Der Server bindet die authentifizierte Identität und ihre beim Eingang wirksame Berechtigungsobergrenze an den Auftrag. Senden Sie dafür keine zusätzlichen Akteursfelder. Vor der Ausführung prüft der Server Identität, Tenantzugehörigkeit und aktuelle Berechtigungen erneut. Ein Entzug notwendiger Rechte kann den bereits angenommenen Auftrag mit failed beenden. Eine spätere Erweiterung der Rollenrechte erweitert seine ursprüngliche Berechtigungsgrenze nicht.

Logout, Sessionablauf oder der spätere Widerruf eines API-Keys stornieren einen bereits angenommenen Auftrag nicht rückwirkend. Prüfen Sie weiterhin dessen statusUrl. Neue Aufträge benötigen gültige Zugangsdaten. Diese Regel betrifft den generischen Workflow-Endpunkt; andere Adapter behalten ihre eigenen Verträge.

Status auswerten

Lesen Sie statusUrl, bis der Request einen terminalen Status erreicht:

  • pending: angenommen und noch nicht geclaimt,
  • processing: die durable Verarbeitung läuft,
  • succeeded: der Workflow-Übergang wurde fachlich abgeschlossen,
  • failed: die Verarbeitung ist terminal fehlgeschlagen.

Bewerten Sie ausschließlich succeeded als fachlichen Erfolg. Loggen Sie den Idempotency-Key nicht, wenn er Geschäfts- oder Kundendaten enthält; verwenden Sie stattdessen eine opake, von Ihrer Integration erzeugte Referenz.