Saltar al contenido principal

Idempotencia

La idempotencia evita que una misma operación se procese más de una vez cuando la solicitud necesita reenviarse.

En la práctica, significa que puede repetir una llamada de creación con la misma idempotencyKey sin generar una nueva operación duplicada.

Para qué sirve​

Use idempotencia siempre que exista la posibilidad de que la misma solicitud se envíe de nuevo por un motivo técnico, como:

  • un timeout en la respuesta
  • una falla momentánea de red
  • un retry automático del cliente HTTP
  • un reenvío manual de la misma llamada

Este comportamiento es especialmente importante en operaciones financieras, porque evita que el integrador cree dos transacciones, dos depósitos o dos retiros por accidente.

Cómo usarla​

El flujo recomendado es simple:

  1. genere una idempotencyKey única para la operación
  2. envíe esa clave junto con la solicitud de creación
  3. si la misma operación debe reenviarse, reutilice la misma clave
  4. si es una operación nueva, genere una clave nueva
Regla práctica

Si la intención de negocio es la misma, reutilice la misma idempotencyKey. Si la intención cambió, cree una clave nueva.

Qué hace la plataforma​

Desde el punto de vista de quien integra, la plataforma reconoce que la misma clave representa la misma operación dentro del mismo contexto de la integración.

Eso permite que un retry no se convierta en una nueva operación por error.

Si el primer intento aún está en procesamiento, la segunda llamada puede esperar el resultado de la operación original antes de responder.

Por cuánto tiempo es válida la clave​

La plataforma guarda el resultado de la operación asociado a la idempotencyKey durante 1 hora a partir del primer envío.

ℹ️ Ventana de idempotencia

Mientras esté dentro de esa ventana, reenviar la misma idempotencyKey devuelve el resultado de la operación original, sin crear una nueva.

Pasada 1 hora la clave expira: un reenvío con la misma idempotencyKey deja de reconocerse como retry y puede generar una nueva operación.

Si su flujo de retry puede demorar más que eso, asegúrese de que el reenvío ocurra dentro de esa ventana.

idempotencyKey vs externalCode​

Estos dos campos tienen funciones distintas:

  • idempotencyKey: identifica un intento único de operación y protege contra la duplicación técnica
  • externalCode: su referencia de negocio para localizar la operación en su propio sistema

Pueden usarse juntos, pero uno no sustituye al otro.

Cuándo generar una clave nueva​

Genere una nueva idempotencyKey cuando:

  • el pedido cambió
  • el monto cambió
  • el destinatario cambió
  • se trata de otra operación, aunque parezca parecida

No reutilice la misma clave para intenciones distintas.

Ejemplo práctico​

Primer intento​

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Retry de la misma operación​

Si la llamada anterior no tuvo una respuesta clara, al reenviar el mismo payload con la misma idempotencyKey la plataforma debe tratarlo como la misma operación.

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Buenas prácticas​

  • use la idempotencyKey en los POST de creación
  • mantenga la misma clave mientras siga intentando concluir la misma operación
  • genere una clave nueva para cada nueva intención de negocio
  • no use la clave como sustituta de externalCode
  • trate el timeout y el retry de su cliente como escenarios esperados

Dónde se aplica​

En nuestra API, este concepto aparece principalmente en los endpoints de creación:

En resumen​

La idempotencia es lo que permite reejecutar la misma intención sin crear duplicados.

Para el integrador, la regla principal es:

  • misma operación, misma idempotencyKey
  • operación nueva, nueva idempotencyKey