Idempotence

Il y a deux mécanismes. Sachez lequel chaque route utilise.

Factures, avoirs et éléments d’un lot : la clé et la référence vivent dans la facture

POST …/invoices et POST …/credit-notes acceptent :

• l’en-tête Idempotency-Key, 64 caractères au plus, et/ou
• le champ external_reference du corps, 100 caractères au plus, unique dans l’entreprise.

L’un des deux au moins est obligatoire, sinon 400 IDEMPOTENCY_REQUIRED : sans lui, une nouvelle tentative créerait une seconde facture. Tous deux sont conservés avec la facture ; ils valent donc aussi longtemps que la facture existe, pas seulement 24 heures.

• Envoyer une clé ou une référence déjà utilisée, avec le même corps, ne crée rien : la réponse est 200 avec Idempotent-Replayed: true et la facture dans son état du moment. 5000 et 5000.0 sont le même montant.
• La même clé ou référence avec un autre corps répond 422 IDEMPOTENCY_KEY_REUSED.
• Si vous envoyez les deux, la clé est cherchée d’abord, puis la référence.
• Une facture en échec est définitive. Renvoyer sa clé ou sa référence rejoue l’échec. Pour normaliser la vente, renvoyez-la avec une nouvelle clé et une nouvelle external_reference.
• Un 429 se rejoue toujours sans risque avec la même clé.
• Dans un lot, il n’y a pas d’en-tête : chaque élément porte sa propre idempotency_key (64 caractères au plus), et/ou l’external_reference de son invoice.

Tous les autres POST : l’en-tête générique

Les autres POST (rapports, relance d’un rapport, exports, rotation du secret du webhook, pause, reprise, fin, désactivation, création d’un point de vente) acceptent l’en-tête Idempotency-Key : 8 à 128 caractères parmi A-Z a-z 0-9 _ -. Il est obligatoire sur POST …/reports, POST …/exports et POST /webhook/rotate-secret, facultatif sur les autres.

Pendant 24 heures, pour une clé et une requête :

• le premier appel s’exécute et son statut et son corps sont conservés ; un appel qui échoue est oublié, vous pouvez donc le rejouer avec la même clé ;
• la même clé avec la même requête renvoie le statut et le corps conservés, avec Idempotent-Replayed: true, sans rien exécuter ;
• la même clé pendant que le premier appel tourne encore répond 409 IDEMPOTENCY_REQUEST_IN_PROGRESS avec Retry-After: 2 ;
• la même clé avec une autre requête répond 422 IDEMPOTENCY_KEY_REUSED ;
• un en-tête obligatoire absent répond 400 IDEMPOTENCY_KEY_REQUIRED, un en-tête mal formé 400 IDEMPOTENCY_KEY_INVALID.

Un secret n’est jamais conservé : le rejeu d’un appel qui avait renvoyé un secret de webhook le montre absent (Webhook).

POST /businesses est idempotent sur external_id quel que soit l’en-tête. PUT /webhook et PUT …/token peuvent simplement être renvoyés.