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

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.