Klantly Developers

Idempotenz und gleichzeitiges Bearbeiten

Vermeiden Sie doppelte Datensätze bei einem erneuten Versuch und überschreiben Sie nie versehentlich eine neuere Version.

Idempotency-Key

Ein Netzwerkfehler oder Timeout bedeutet nicht, dass Ihre Anfrage fehlgeschlagen ist. Senden Sie bei einem POST daher einen Header Idempotency-Key mit einem eindeutigen Wert mit, zum Beispiel einer UUID:

cURL
curl -X POST "https://app.klantly.com/api/v1/customers" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{"email": "jan@example.com"}'
  • Senden Sie dieselbe Anfrage mit demselben Schlüssel erneut, erhalten Sie dieselbe Antwort zurück, mit dem Header Idempotent-Replayed: true. Es wird nichts doppelt angelegt. Nur das Secret eines Webhook-Endpunkts (beim Erstellen und Erneuern) fehlt dann: Es ist genau einmal zu sehen.
  • Derselbe Schlüssel mit einem anderen Body ergibt 422 idempotency_key_reused.
  • Läuft die erste Anfrage noch, folgt 409 idempotency_in_progress.
  • Antworten, die vom aktuellen Zustand abhängen (401, 403, 404, 409, 412, 422, 423, 429), und jede 5xx werden nicht gespeichert: Derselbe Schlüssel mit einem korrigierten Body führt die Anfrage einfach aus.

Ein Idempotency-Key gilt 24 Stunden und zählt für Ihr gesamtes Unternehmen, nicht pro Schlüssel. Verwenden zwei Integrationen (oder zwei Schlüssel) denselben Wert für eine andere Anfrage, erhält die zweite 422 idempotency_key_reused; geben Sie jeder Integration ein eigenes Präfix, zum Beispiel crm- oder webshop-. Da die Garantie zum Unternehmen gehört, bleibt ein erneuter Versuch sicher, wenn Ihre Integration während der Schlüsselerneuerung auf das neue Token wechselt.

Warnung

Die Upload-Routen (Anhänge zu einem Angebot und Fotos zu einem Arbeitsauftrag) funktionieren nicht mit einem Idempotency-Key: Bei einem multipart/form-data-Body kann Klantly nicht erkennen, ob Sie dieselbe Datei erneut senden. Wiederholen Sie einen Upload, erhalten Sie eine zweite Datei; löschen Sie diese dann selbst.

ETag und If-Match

Jedes einzelne Objekt kommt mit einem Header ETag. Senden Sie ihn in If-Match mit, wenn Sie ein PATCH ausführen:

HTTP
PATCH /api/v1/customers/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70 HTTP/1.1
Authorization: Bearer kly_4fZ2mQ8v...
If-Match: "3f2c9a41d6e8b07c5a2f"
Content-Type: application/json

Wurde der Datensatz inzwischen von jemand anderem geändert, folgt 412 precondition_failed und alles bleibt unverändert. Rufen Sie den Datensatz erneut ab und versuchen Sie es noch einmal. Ohne If-Match wird die Änderung einfach übernommen.

Zuletzt aktualisiert am 21. September 2026