Saltar al contenido principal
Un aspecto clave de la confiabilidad de Midaz es asegurar que las operaciones sean seguras de reintentar y nunca se procesen más de una vez. Ya sea que esté manejando transacciones o creando entidades, su integración debe ser resiliente, incluso cuando enfrenta problemas de red, tiempos de espera o interrupciones temporales. Esta página explica cómo Midaz protege contra la duplicación usando claves de idempotencia, y cómo puede implementarlas para manejar reintentos en su sistema con confianza.

​
Hacer que los reintentos sean seguros

En sistemas del mundo real, las solicitudes de API fallidas son comunes. Tal vez ocurra un tiempo de espera de red. Tal vez su servicio se caiga justo después de enviar una solicitud. En estos casos, es natural reintentar, pero ¿cómo puede estar seguro de que Midaz no procesará la misma operación dos veces? Ahí es donde entran las claves de idempotencia. Al adjuntar una clave única a cada solicitud, le está diciendo a Midaz: “Esta es la misma operación. Si ya la has procesado, no la hagas de nuevo.” Midaz almacena esta clave temporalmente y la usa para determinar si la solicitud es nueva, ya completada o todavía en proceso. Esto protege su sistema de duplicados mientras le da control total sobre su estrategia de reintentos.

​
Idempotencia en Midaz

Midaz usa claves de idempotencia para asegurar que las operaciones sean seguras de reintentar y nunca se procesen más de una vez. Para eso, su solicitud debe incluir dos encabezados:
  • X-Idempotency: la clave única que identifica la solicitud.
  • X-TTL: el tiempo de vida (en segundos) que Midaz debe almacenar esta clave en caché.
Esto es lo que sucede detrás de escena:
  1. Cuando llega una nueva clave, Midaz la marca como pending, procesa la solicitud y almacena la respuesta completa en caché.
  2. Si la misma clave se usa nuevamente dentro de la ventana TTL:
    1. Si la operación todavía se está ejecutando, Midaz devuelve un 409 Conflict con X-Idempotency-Replayed: false.
    2. Si está terminada, Midaz devuelve exactamente la misma respuesta, incluyendo encabezados y cuerpo, con X-Idempotency-Replayed: true.
Este modelo funciona en todos los endpoints de Midaz y le brinda una forma segura y predecible de construir flujos de trabajo reintentables, ya sea que esté manejando pagos, trabajos en segundo plano o transacciones de alto volumen.

​
Resumen del flujo de trabajo

La Figura 1 muestra el ciclo de vida completo de una solicitud idempotente:

Figura 1. Ciclo de vida de solicitud idempotente en Midaz.

Cómo funciona:
  • Si la solicitud no incluye una clave de idempotencia existente, Midaz crea una nueva, procesa la solicitud, almacena la respuesta y la devuelve con X-Idempotency-Replayed: false.
  • Si la clave ya existe:
    • Si la operación todavía se está ejecutando, Midaz devuelve un 409 Conflict con X-Idempotency-Replayed: false.
    • Si la operación está completa, Midaz omite la ejecución y devuelve la respuesta en caché con X-Idempotency-Replayed: true.
Este comportamiento garantiza que cada solicitud se maneje de manera segura, predecible y sin duplicación, incluso cuando se reintenta.

​
Ejemplo de solicitud

Aquí se muestra cómo enviar una solicitud idempotente para crear una transacción: 
POST /v1/transactions
X-Idempotency: 7fb8e1d098cd4730bb932d038b3b8651
X-TTL: 60
Content-Type: application/json

{
  "amount": 1000,
  "source": "wallet_A",
  "destination": "wallet_B",
  "asset": "USD"
}
Si la solicitud tiene éxito y la envía nuevamente dentro de 60 segundos, Midaz devolverá el resultado en caché con: 
X-Idempotency-Replayed: true
Si la envía nuevamente mientras la original todavía se está procesando, recibirá un: 
HTTP/1.1 409 Conflict
X-Idempotency-Replayed: false

​
Generación de claves

Usted genera la clave X-Idempotency de su lado. La clave debe ser determinística, lo que significa que si se reintenta la misma operación, la clave permanece igual. Una estrategia simple y efectiva es crear un hash basado en los campos clave que definen la operación. Por ejemplo:
  • Monto de la transacción
  • Origen y destino
  • Código de activo
Aquí hay un ejemplo rápido en Python: 
import hashlib

def generate_idempotency_key(amount, source, destination, asset):
    raw = f"{amount}:{source}:{destination}:{asset}".lower()
    return hashlib.md5(raw.encode()).hexdigest()

​
Prevención de duplicación de entidades

Para algunos endpoints, no necesita claves de idempotencia para evitar la duplicación. Midaz aplica restricciones de unicidad en recursos críticos como Cuentas y Libros Contables. Si intenta crear una entidad con un nombre que ya existe, el sistema bloquea la solicitud y devuelve un error descriptivo. Esto garantiza que sus datos permanezcan limpios, sin ambigüedades y fáciles de gestionar, incluso cuando múltiples servicios están operando en paralelo o cuando los reintentos ocurren automáticamente.

​
Preguntas frecuentes

Midaz trata la solicitud como nueva cada vez. Esto significa que los reintentos pueden resultar en operaciones duplicadas.
No. Las claves deben estar limitadas a una sola operación y endpoint.
Solo se usa el TTL de la primera solicitud. Cambiarlo más tarde no tiene efecto.
Sí. Midaz reproduce la respuesta completa, incluyendo encabezados y cuerpo, para solicitudes completadas.
La ventana predeterminada es de 300 segundos (5 minutos), pero puede personalizarla hasta su límite permitido por endpoint.