Idempotencia

Por qué importa

Las redes fallan a mitad de petición. Si haces POST /v1/activations y la conexión cae antes de ver la respuesta, no sabes si la activación se creó. Reintentar ingenuamente podría cobrarte dos veces.

La cabecera Idempotency-Key lo soluciona: envía la misma clave en el reintento, obtén el mismo resultado.

Cómo usar

Genera un UUID por operación lógica, envíalo en cada reintento de la misma operación:

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

Repetir la misma llamada con el mismo Idempotency-Key devuelve la respuesta original — sin segunda activación, sin segundo cargo.

TTL

Las claves se recuerdan durante 24 horas. Después se libera el slot y la misma clave puede reutilizarse como nueva.

Dónde aplica

Todos los endpoints POST /v1/* que crean o cobran: activaciones, alquileres, depósitos, extensiones. Los endpoints de lectura (GET) son ya idempotentes e ignoran la cabecera.

Conflictos

Si reutilizas la misma clave con un body diferente, la API devuelve 409 idempotency_conflict. Mantén el body idéntico en reintentos o genera una nueva clave.

Comportamiento del SDK

Los SDKs oficiales auto-generan claves de idempotencia para cada llamada de creación y las reutilizan en reintentos automáticos. Puedes anular con una clave explícita si lo necesitas.