Idempotenz
Bricht die Verbindung nach einem POST ab, wissen Sie nicht, ob DebtFlow die Anfrage ausgeführt hat. Mit dem Header Idempotency-Key können Sie gefahrlos wiederholen – ohne doppelte Rechnung oder doppelten Brief.
curl -X POST 'https://www.debt-flow.io/api/v1/contacts' \
-H "Authorization: Bearer $DEBTFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 4f0c2a7e-crm-sync-1832' \
-d '{"name":"Muster GmbH"}'| Fall | Antwort |
|---|---|
| Erste Anfrage mit neuem Schlüssel | wird normal ausgeführt; die Antwort wird 24 Stunden gespeichert |
| Gleicher Schlüssel, gleiche Anfrage | gespeicherte Antwort mit Header Idempotent-Replayed: true |
| Gleicher Schlüssel, andere Anfrage | 422 idempotency_conflict |
| Erste Anfrage läuft noch | 409 idempotency_in_progress – kurz warten, dann erneut |
| Erste Anfrage endete mit 5xx | Schlüssel wird freigegeben; die Wiederholung wird neu ausgeführt |
- Schlüssel: 8 bis 255 Zeichen aus
A–Z a–z 0–9 _ - : ., zum Beispiel eine UUID. - Der Schlüssel gilt je API-Schlüssel bzw. OAuth-Verbindung; verschiedene Integrationen kommen sich nicht in die Quere.
- „Gleiche Anfrage“ heißt: gleiche Methode, gleicher Pfad und gleicher Body.
- Gilt für
POST-Endpunkte außer Datei-Uploads; in der API-Referenz ist der Header bei jedem unterstützten Endpunkt aufgeführt.GET,PATCHundDELETElassen sich ohnehin wiederholen.
Ein Schlüssel je Vorgang
Erzeugen Sie den Schlüssel, wenn der fachliche Vorgang entsteht (zum Beispiel „Rechnung zu Auftrag 1832 anlegen“), und speichern Sie ihn mit dem Vorgang. Ein neuer Schlüssel bei jedem Versuch würde den Schutz aushebeln.