Idempotency

L'idempotency garantit qu'une opération ne peut être exécutée qu'une seule fois, même si la même requête est envoyée plusieurs fois — en cas de timeout, panne réseau ou retry.

Pourquoi c'est important Utilisation Comportement Durée de vie Erreurs

Pourquoi c'est important

Imaginez ce scénario : vous envoyez un payout, votre serveur reçoit un timeout, et vous ne savez pas si le paiement a été traité. Sans idempotency, un retry enverrait le paiement deux fois.

Principe

Avec le header Idempotency-Key, la seconde requête (identique) retournera exactement la même réponse que la première, sans exécuter l'opération une deuxième fois.

Utilisation

Ajoutez le header Idempotency-Key à chaque requête POST :

bash Requête avec Idempotency-Key

curl -X POST https://envoifacile.com/api/v1/merchant/payin \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order_2024_XYZ_001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "currency": "XOF", ... }'

Bonnes pratiques pour choisir la clé

Utilisez la référence de commande/paiement côté marchand
La clé doit être unique par opération (pas par session)
Max 64 caractères, alphanumériques + -_.
Ne réutilisez jamais une clé pour une opération différente

php Génération d'une bonne clé

// ✅ Bon — basé sur une référence métier unique
$idempotencyKey = "payin_{$orderId}";
$idempotencyKey = "payout_salary_{$employeeId}_2024_06";

// ✅ Bon — UUID généré à la création de la requête et stocké
$idempotencyKey = Str::uuid()->toString();

// ❌ Mauvais — généré à chaque retry (perd tout l'intérêt)
$idempotencyKey = Str::uuid()->toString(); // dans la boucle retry

Comportement

Situation	Réponse	HTTP
Première requête avec cette clé	Traitement normal, réponse fraîche	200
Même clé + même payload (replay)	Réponse originale retournée sans re-traitement	200
Même clé + payload différent	Erreur `IDEMPOTENCY_CONFLICT`	422
Requête identique déjà en traitement	Erreur `CONCURRENT_REQUEST`	409
Clé expirée (>24h)	Traitement comme une nouvelle requête	200

Durée de vie

Les clés d'idempotency sont conservées pendant 24 heures après la première requête. Après ce délai, la même clé peut être réutilisée pour une nouvelle opération.

Erreurs d'idempotency

json IDEMPOTENCY_CONFLICT — 422

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency-Key reused with a different payload."
  }
}

json CONCURRENT_REQUEST — 409

{
  "success": false,
  "error": {
    "code": "CONCURRENT_REQUEST",
    "message": "A request with this Idempotency-Key is already being processed."
  }
}