Klantly Developers

Idempotence et modifications simultanées

Évitez les doublons lors d'une nouvelle tentative et n'écrasez jamais par erreur une version plus récente.

Idempotency-Key

Une erreur réseau ou un délai d'attente dépassé ne signifie pas que votre requête a échoué. Avec un POST, envoyez donc un en-tête Idempotency-Key contenant une valeur unique, par exemple un 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"}'
  • Si vous renvoyez la même requête avec la même clé, vous obtenez la même réponse, avec l'en-tête Idempotent-Replayed: true. Rien n'est créé en double. Seul le secret d'un endpoint de webhook (à la création et au renouvellement) n'y figure plus : il n'est affiché qu'une seule fois.
  • La même clé avec un autre corps renvoie 422 idempotency_key_reused.
  • Si la première requête est encore en cours, vous obtenez 409 idempotency_in_progress.
  • Les réponses qui dépendent de l'état actuel (401, 403, 404, 409, 412, 422, 423, 429) et toute 5xx ne sont pas conservées : la même clé avec un corps corrigé exécute simplement la requête.

Une Idempotency-Key est valable 24 heures et vaut pour toute votre entreprise, pas par clé. Si deux intégrations (ou deux clés) utilisent la même valeur pour une requête différente, la seconde reçoit 422 idempotency_key_reused ; donnez à chaque intégration son propre préfixe, par exemple crm- ou webshop-. Comme la garantie appartient à l'entreprise, une nouvelle tentative reste sûre si votre intégration bascule sur le nouveau jeton pendant le renouvellement de la clé.

Attention

Les routes d'upload (pièces jointes d'un devis et photos d'un bon d'intervention) ne fonctionnent pas avec une Idempotency-Key : avec un corps multipart/form-data, Klantly ne peut pas savoir si vous envoyez à nouveau le même fichier. Si vous répétez un upload, vous obtenez un deuxième fichier ; supprimez-le vous-même le cas échéant.

ETag et If-Match

Chaque objet seul est accompagné d'un en-tête ETag. Envoyez-le dans If-Match lorsque vous faites un PATCH :

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

Si quelqu'un d'autre a modifié l'enregistrement entre-temps, vous obtenez 412 precondition_failed et rien ne change. Récupérez à nouveau l'enregistrement et réessayez. Sans If-Match, la modification est simplement appliquée.

Dernière mise à jour le 21 septembre 2026