Doppelte Vorgänge vermeiden

Idempotenz stellt sicher, dass ein Vorgang genau einmal stattfindet, egal wie oft dieselbe Anfrage wiederholt wird. Sie verhindert zum Beispiel ein doppeltes Angebot, wenn die Verbindung mitten in einem POST abbricht und Sie nicht wissen, ob Cord es erhalten hat.

Der Header Idempotency-Key

Jede Anfrage an die API v1, die etwas anlegt oder ändert (POST, PATCH oder DELETE), akzeptiert den Header Idempotency-Key. Erzeugen Sie pro Vorgang einen eindeutigen Wert (zum Beispiel eine UUID), speichern Sie ihn mit dem Vorgang und senden Sie ihn bei jeder Wiederholung mit demselben Body erneut:

curl -X POST "https://cordhq.app/api/v1/clientes" \
     -H "Authorization: Bearer $CORD_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5d9c2b7e-6f1a-4c3d-9e8b-2a1f0c7d6e5b" \
     -d '{ "empresa": "ACME Corp" }'

Was Cord bei einer Wiederholung antwortet

• Derselbe Wert und derselbe Body: Cord führt den Vorgang nicht erneut aus und rechnet ihn nicht auf Ihr Kontingent an. Es gibt die ursprüngliche Antwort mit demselben Statuscode zurück und ergänzt den Header Idempotent-Replayed: true.
• Derselbe Wert mit anderem Body, anderer Methode oder Route: 422 mit dem Code idempotency_key_reused. Verwenden Sie für jeden anderen Vorgang einen neuen Wert.
• Die erste Anfrage läuft noch: 409 mit idempotency_in_progress. Warten Sie einige Sekunden und versuchen Sie es erneut.
• Fehler 5xx und 429: werden nicht gespeichert, Sie können also mit demselben Wert erneut versuchen.
• Ungültiger Wert: Erlaubt sind 1 bis 255 sichtbare Zeichen, sonst 400 mit invalid_idempotency_key.
• Ohne Garantie keine Ausführung: Kann Cord den Wert nicht reservieren, antwortet es mit 503 und idempotency_unavailable und führt den Vorgang nicht aus.

Wie lange er gilt

Cord merkt sich jeden Wert 24 Stunden lang, pro API-Schlüssel: Derselbe Wert mit einem anderen Schlüssel ist ein anderer Vorgang. Nach 24 Stunden führt derselbe Wert den Vorgang erneut aus. Prüfen Sie deshalb vor der Wiederholung eines älteren Vorgangs, ob er schon existiert.

Ohne den Header wird jede Anfrage so ausgeführt, wie sie eintrifft. Ein GET braucht ihn nicht: Lesen ändert nichts.

SDK und MCP-Server

• Das Node-SDK (@flouviahq/node) sendet bei jedem schreibenden Vorgang einen Idempotency-Key und wiederholt denselben Wert bei seinen Wiederholungen. Einen eigenen Wert übergeben Sie mit der Option idempotencyKey.
• Die schreibenden Tools des MCP-Servers akzeptieren das Argument idempotency_key, mit derselben Regel und derselben Dauer.

Außerdem

• Speichern Sie die id der Antwort. Wenn Sie ein Angebot erstellen (POST /api/v1/cotizaciones), enthält die Antwort data.id und data.folio. Speichern Sie beide in Ihrem System: Haben Sie für diesen Vorgang schon eine ID, ist keine Wiederholung nötig.
• Ein erneuter Katalogimport erzeugt keine Duplikate. Der CSV-Import von Kunden in der App aktualisiert den Kunden, der nach Steuernummer oder Firmenname übereinstimmt, der Import von Produkten das Produkt mit derselben SKU.

Die Fehlercodes der API und ihre Bedeutung finden Sie unter Fehlerbehandlung.