Idempotence

Certaines écritures ont un effet réel qui ne doit pas se produire deux fois — déclencher une distribution de paie, par exemple. Ces opérations exigent un Idempotency-Key, et l'API garantit que rejouer la même clé renvoie la réponse d'origine au lieu de produire un second effet.

La référence indique quelles opérations exigent l'en-tête.

Envoyer la clé

curl -X POST "https://<hote-api-external>/api/v1/client/app/payroll/distribution/trigger" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 6f1e8c94-3d5a-4c2b-9f7e-11a2b3c4d5e6" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Générez une clé neuve — un UUID est idéal — pour chaque intention métier distincte, et réutilisez cette même clé à chaque réessai de cette intention. Omettre l'en-tête sur une opération qui l'exige donne un 400 (idempotency/key-required).

Le corps et la réponse ci-dessous sont capturés depuis la suite de tests, pas recopiés : ce que vous voyez est ce que l'API a reçu et renvoyé.

{
  "credentialsLogin": "partner-payroll-login",
  "companySiret": "12345678901234",
  "payrollPeriod": "2026-01-01"
}

{
  "isSuccess": true,
  "errorMessage": null,
  "distributionUrl": "https://staffngo.example.com/payroll/distribution/sample"
}

Ce qui identifie un doublon

Trois choses ensemble : votre identité partenaire, la clé, et une empreinte du corps de la requête, le tout rapporté à la capacité et à la version exactes que vous avez appelées.

Deux conséquences à connaître :

Réutiliser une clé avec un corps différent constitue une requête différente, pas un rejeu. Ne recyclez jamais une clé entre des appels sans rapport.
La même clé sur un autre endpoint, ou une autre version du même endpoint, est elle aussi distincte — on ne vous servira jamais une réponse conçue pour un autre contrat.

Ce que vous obtenez en retour

Situation	Réponse
Premier appel	Le handler s'exécute ; sa réponse est renvoyée et mémorisée.
Rejeu après complétion	La réponse mémorisée, à l'identique — même statut, même corps. Aucune seconde exécution.
Rejeu pendant que le premier tourne encore	`409` avec `type` = `idempotency/in-progress`. Attendez, puis réessayez.
Premier appel en échec (non-2xx) ou interrompu	La clé est libérée. Réessayer avec la même clé relance l'opération.

C'est cette dernière ligne qu'il faut avoir en tête : seules les écritures réussies sont mémorisées. Une tentative en échec n'empoisonne pas la clé, donc un réessai légitime après erreur n'est pas silencieusement avalé.

En pratique

Persistez la clé à côté de l'opération que vous tentez, avant de l'envoyer. Une clé régénérée au réessai n'offre aucune protection.
Sur un 409 idempotency/in-progress, temporisez et réessayez avec la même clé plutôt que d'en émettre une nouvelle — une nouvelle clé créerait un second effet, exactement ce que vous cherchiez à éviter.
Sur un timeout sans réponse, réessayez avec la même clé. C'est le cas pour lequel l'idempotence existe : vous ignorez si l'écriture a abouti, l'API le sait.

Jetons legacy

Les appels authentifiés avec un jeton BearerClient déprécié contournent entièrement ce mécanisme — un rejeu n'y est pas dédoublonné. C'est une raison de plus de migrer vers des identifiants OAuth, voir Authentification.