Saltar al contenido principal
Un aspecto clave de la confiabilidad de Midaz es asegurar que las operaciones sean seguras para reintentar y nunca se procesen más de una vez. Ya sea que esté manejando transacciones o creando nuevas entidades, sus solicitudes deben ser resilientes y libres de duplicados. Esta guía cubre cómo Midaz admite reintentos a través de claves de idempotencia, y cómo protege la unicidad de entidades críticas como Cuentas y Ledgers.

​
Reintentos

Las solicitudes de API pueden fallar: interrupciones de red, tiempos de espera agotados o disrupciones temporales ocurren. Cuando suceden, a menudo es seguro reintentar, siempre que esté usando claves de idempotencia. Estas claves permiten que Midaz sepa que está repitiendo una solicitud, no iniciando una nueva. Eso significa que podemos evitar procesarla dos veces, mientras ayudamos a su sistema a recuperarse elegantemente de los errores.

​
Idempotencia

​
Transacciones

Midaz usa claves de idempotencia para garantizar que cada transacción se procese solo una vez, incluso si la misma solicitud se envía múltiples veces. Esto protege contra duplicados accidentales y ayuda a garantizar la consistencia de datos en su sistema.

​
Cómo generar una clave de idempotencia

Usted crea la clave de idempotencia de su lado. Recomendamos construir un hash MD5 a partir de los siguientes campos:
  • Monto de la transacción
  • Origen
  • Destino
  • Código del activo
Esto mantiene la clave única y predecible para los reintentos.

​
Cómo usarla

Al enviar una solicitud POST a /v1/transactions, incluya su clave de idempotencia en el parámetro de consulta idempotencyKey. Midaz almacena esta clave en caché con el formato hash:timestamp:status_request. Si la misma clave se recibe nuevamente dentro de 60 segundos de una transacción exitosa, Midaz bloquea el duplicado y devuelve una respuesta HTTP 409.

​
Caché y ventana de tolerancia

Las claves de idempotencia se almacenan en caché durante 24 horas para optimizar el rendimiento. Por defecto, la ventana de duplicación es de 60 segundos, pero puede personalizarla incluyendo un parámetro de consulta tolerance en su solicitud. Esto define cuánto tiempo Midaz debe considerar dos transacciones como “la misma”. Por ejemplo: Una solicitud enviada después de los 60 segundos iniciales, con una clave de idempotencia válida y un tolerance modificado, se tratará como una nueva operación. Esto le da control sobre el tiempo mientras mantiene sus datos a salvo de repeticiones no deseadas.

​
Prevención de duplicación de entidades

Más allá de las transacciones, Midaz impone nombres únicos para todas las entidades clave, como Cuentas y Ledgers. Si intenta crear una entidad con un nombre que ya existe, Midaz bloquea la operación y devuelve un mensaje claro. Esto garantiza que sus datos se mantengan limpios, sin ambigüedades y fáciles de administrar.