Skip to main content
Cuando envías una solicitud de pago por la red, puedes encontrarte con una situación en la que tu conexión se cae antes de recibir una respuesta. En ese punto no puedes saber si el servidor procesó el pago o no. Si reintentas la solicitud sin una clave de idempotencia, corres el riesgo de cobrarle dos veces al cliente. El encabezado Idempotency-Key resuelve esto: te permite reintentar una solicitud cualquier número de veces con la garantía de que Therius la procesará exactamente una vez.

​
Cómo funciona

Todos los endpoints que modifican datos aceptan un encabezado de solicitud Idempotency-Key:
  • POST /payment/purchase
  • POST /payment/authorization
  • POST /payment/{id}/capture
  • POST /payment/{id}/refund
  • POST /payment/{id}/cancel
  • POST /payment/{id}/cancel_or_refund
  • POST /payment/resume
  • POST /subscription
  • POST /subscription/usage — consulta la nota más abajo; la semántica difiere un poco
El valor debe ser un UUID v4 que generes por operación lógica (un UUID por compra, uno por reembolso, y así). Así maneja Therius la clave durante los reintentos:
  1. Primera solicitud — Therius reserva la clave, procesa el pago y almacena la respuesta 2xx asociada a la clave.
  2. Reintento con la misma clave — Therius detecta el duplicado, omite el procesamiento y devuelve la respuesta en caché de inmediato.
  3. Solicitud concurrente con la misma clave — Si llega una segunda solicitud con la misma clave mientras la primera aún está en curso, Therius devuelve 409 Conflict con un encabezado Retry-After: 1. Espera un segundo y reintenta.
  4. Endpoint equivocado, misma clave — Reutilizar una clave en un endpoint diferente devuelve 422 Unprocessable Entity.
Solo se almacenan en caché las respuestas 2xx. Si una solicitud falla con un estado 4xx o 5xx, la clave no se guarda — puedes reintentar con una clave nueva (o la misma clave, si el error fue transitorio y quieres volver a intentar la misma operación).
Las claves expiran después de 24 horas. Tras la expiración, el mismo UUID puede reutilizarse libremente, pero de todos modos deberías generar un UUID nuevo para cualquier operación nueva.
POST /subscription/usage también lee el encabezado Idempotency-Key, pero se deduplica por (meterCode, Idempotency-Key) y nunca expira: una repetición devuelve el evento de uso original con "duplicate": true en vez de una respuesta HTTP en caché. Allí la clave es opcional — si la omites, cada llamada registra un evento nuevo.

​
Ejemplos de código

​
Bash / cURL

Si el comando expira por timeout, vuelve a ejecutarlo con el mismo valor de $IDEM_KEY. Therius devolverá el resultado en caché si la solicitud original tuvo éxito.

​
JavaScript

Almacena el UUID junto con el pedido en tu base de datos antes de enviar la solicitud. Si la llamada fetch lanza un error de red, recupera el UUID almacenado y reintenta con él — no generes uno nuevo.

​
Mejores prácticas

En producción el encabezado Idempotency-Key no es opcional. Envía siempre uno en cada llamada que modifica datos. Omitirlo en un endpoint de pago en un entorno de producción es un error de configuración, no un descuido menor.
Al reintentar tras un timeout, reutiliza exactamente el mismo UUID que enviaste originalmente. Therius devuelve el resultado en caché sin volver a procesar el pago, de modo que a tu cliente se le cobra exactamente una vez.
  • Genera la clave antes de la solicitud, no después. Guárdala con el registro del pedido para poder recuperarla si necesitas reintentar.
  • Un UUID por operación lógica. Una compra y su posterior reembolso son dos operaciones distintas — cada una recibe su propio UUID.
  • No reutilices claves entre endpoints. Una clave usada para POST /payment/purchase no puede usarse para POST /payment/{id}/refund.
  • No compartas claves entre clientes ni pedidos. Cada clave debe ser globalmente única para una sola operación.