Klantly Developers

Idempotentie en gelijktijdig bewerken

Voorkom dubbele records bij een nieuwe poging en overschrijf nooit per ongeluk een nieuwere versie.

Idempotency-Key

Een netwerkfout of time-out betekent niet dat je verzoek is mislukt. Stuur bij een POST daarom een header Idempotency-Key mee met een unieke waarde, bijvoorbeeld een 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"}'
  • Stuur je hetzelfde verzoek opnieuw met dezelfde sleutel, dan krijg je hetzelfde antwoord terug, met de header Idempotent-Replayed: true. Er wordt niets dubbel aangemaakt. Alleen het secret van een webhook-endpoint (bij aanmaken en vernieuwen) staat er dan niet meer in: dat is precies één keer te zien.
  • Dezelfde sleutel met een andere body geeft 422 idempotency_key_reused.
  • Loopt het eerste verzoek nog, dan volgt 409 idempotency_in_progress.
  • Antwoorden die van de toestand afhangen (401, 403, 404, 409, 412, 422, 423, 429) en elke 5xx worden niet bewaard: dezelfde sleutel met een gecorrigeerde body voert het verzoek gewoon uit.

Een Idempotency-Key geldt 24 uur en telt voor je hele bedrijf, niet per sleutel. Gebruiken twee koppelingen (of twee sleutels) dezelfde waarde voor een ánder verzoek, dan krijgt de tweede 422 idempotency_key_reused; geef elke koppeling daarom een eigen voorvoegsel, bijvoorbeeld crm- of webshop-. Doordat de waarborg bij het bedrijf hoort, blijft een herhaling veilig als je koppeling tijdens het vernieuwen van een sleutel overstapt op het nieuwe token.

Waarschuwing

De uploadroutes (bijlagen bij een offerte en foto's bij een werkbon) werken niet met een Idempotency-Key: bij een multipart/form-data-body kan Klantly niet zien of je hetzelfde bestand nog eens stuurt. Herhaal je een upload, dan krijg je een tweede bestand; verwijder dat dan zelf.

ETag en If-Match

Elk los object komt met een header ETag. Stuur die mee in If-Match wanneer je een PATCH doet:

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

Is het record intussen door iemand anders gewijzigd, dan volgt 412 precondition_failed en blijft alles ongewijzigd. Haal het record opnieuw op en probeer het nog eens. Zonder If-Match wordt de wijziging gewoon doorgevoerd.

Laatst bijgewerkt op 21 september 2026