Idempotence
Comment l'en-tête `Idempotency-Key` empêche les doubles facturations lors des retries sur réseaux instables.
Pourquoi c'est important
Les réseaux échouent en plein milieu d'une requête. Si vous faites POST /v1/activations et que la connexion tombe avant de voir la réponse, vous ne savez pas si l'activation a été créée. Un retry naïf pourrait facturer deux fois.
L'en-tête Idempotency-Key résout cela : envoyez la même clé au retry, obtenez le même résultat.
Utilisation
Générez un UUID par opération logique, envoyez-le à chaque retry de la même opération :
KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
-H "Authorization: Bearer $EVESES_API_KEY" \
-H "Idempotency-Key: $KEY" \
-d '{"country":"ua", "service":"telegram"}'
Refaire le même appel avec le même Idempotency-Key renvoie la réponse originale — pas de deuxième activation, pas de deuxième facturation.
TTL
Les clés sont mémorisées pendant 24 heures. Ensuite le slot est libéré et la même clé peut être réutilisée comme neuve.
Où ça s'applique
Tous les endpoints POST /v1/* qui créent ou facturent : activations, locations, dépôts, prolongations. Les endpoints de lecture (GET) sont déjà idempotents et ignorent l'en-tête.
Conflits
Si vous réutilisez la même clé avec un body différent, l'API renvoie 409 idempotency_conflict. Gardez le body identique sur les retries ou générez une nouvelle clé.
Comportement du SDK
Les SDKs officiels génèrent automatiquement des clés d'idempotence pour chaque appel de création et les réutilisent sur les retries automatiques. Vous pouvez surcharger avec une clé explicite si besoin.