Éviter les opérations en double

L’idempotence garantit qu’une opération n’a lieu qu’une seule fois, quel que soit le nombre de fois où la même requête est relancée. Elle évite par exemple un devis en double lorsque la connexion tombe au milieu d’un POST et que vous ne savez pas si Cord l’a reçu.

L’en-tête Idempotency-Key

Toute requête de l’API v1 qui crée ou modifie quelque chose (POST, PATCH ou DELETE) accepte l’en-tête Idempotency-Key. Générez une valeur unique par opération (par exemple, un UUID), conservez-la avec l’opération et renvoyez-la à chaque nouvelle tentative avec le même corps :

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" }'

Ce que Cord répond à une répétition

• Même valeur et même corps : Cord ne réexécute pas l’opération et ne la décompte pas de votre quota. Il renvoie la réponse d’origine, avec le même code d’état, et ajoute l’en-tête Idempotent-Replayed: true.
• Même valeur avec un autre corps, une autre méthode ou une autre route : 422 avec le code idempotency_key_reused. Utilisez une nouvelle valeur pour chaque opération différente.
• La première requête est toujours en cours : 409 avec idempotency_in_progress. Attendez quelques secondes et réessayez.
• Erreurs 5xx et 429 : elles ne sont pas conservées ; vous pouvez donc réessayer avec la même valeur.
• Valeur invalide : de 1 à 255 caractères visibles sont acceptés ; sinon, 400 avec invalid_idempotency_key.
• Sans garantie, pas d’exécution : si Cord ne peut pas réserver la valeur, il répond 503 avec idempotency_unavailable et n’exécute pas l’opération.

Durée

Cord conserve chaque valeur 24 heures, par clé API : la même valeur envoyée avec une autre clé est une autre opération. Au-delà de 24 heures, la même valeur exécute de nouveau l’opération ; avant de relancer une opération plus ancienne, vérifiez donc si elle existe déjà.

Sans l’en-tête, chaque requête s’exécute telle qu’elle arrive. Un GET n’en a pas besoin : une lecture ne modifie rien.

SDK et serveur MCP

• Le SDK Node (@flouviahq/node) envoie un Idempotency-Key pour chaque opération d’écriture et répète la même valeur lors de ses nouvelles tentatives. Vous pouvez transmettre la vôtre avec l’option idempotencyKey.
• Les outils du serveur MCP qui écrivent acceptent l’argument idempotency_key, avec la même règle et la même durée.

À savoir aussi

• Conservez l’id de la réponse. Lorsque vous créez un devis (POST /api/v1/cotizaciones), la réponse contient data.id et data.folio. Enregistrez-les dans votre système : si vous disposez déjà d’un id pour cette opération, inutile de relancer.
• Réimporter un catalogue ne crée pas de doublons. L’import de clients par CSV dans l’application met à jour le client qui correspond par identifiant fiscal ou par raison sociale, et celui de produits, le produit qui correspond par SKU.

Les codes d’erreur de l’API et leur signification figurent dans Gestion des erreurs.