Idempotencia

Cada endpoint M2M que cambia estado acepta un encabezado Idempotency-Key. Enviar la misma clave dos veces retorna la respuesta original — nunca una operación duplicada. Este documento especifica el contrato.

Inicio rápido

KEY=$(uuidgen)

# Primera llamada: crea la orden
curl -X POST "https://sandbox-api.ariari.xyz/api/v1/fxorder/createOrder" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'
# Retorna: 201 Created + reference_code FXT-20260428-000123

# Segunda llamada (reintento por hipo de red): retorna la MISMA respuesta, sin duplicado
curl -X POST "https://sandbox-api.ariari.xyz/api/v1/fxorder/createOrder" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'
# Retorna: 201 Created + reference_code FXT-20260428-000123 (igual)

Endpoints que requieren `Idempotency-Key`

Si usted omite Idempotency-Key en un endpoint de creación, la solicitud retorna 422 Unprocessable Entity con error_code: BFF-IDEM-001.

Formato de la clave

Genere claves frescas del lado cliente. UUID v4 es la opción predeterminada más segura. ARi recomienda uuidgen (Linux/macOS) o crypto.randomUUID() (Node 19+).

Retención

Las claves de idempotencia se retienen durante 24 horas después de la solicitud original. Después de 24 h, la clave es purgada. Un reintento con una clave de 25 horas crea una nueva operación (sin detección de duplicado).

Implicación práctica: complete su secuencia de reintentos dentro de las 24 h de la solicitud original. Reintentos con demora larga deberían generar una clave fresca.

Semántica de conflicto — misma clave, cuerpo distinto

Enviar el mismo Idempotency-Key con un cuerpo de solicitud distinto dentro de la ventana de 24 h retorna:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "error_code": "DB-IDEM-409",
  "detail": "Idempotency-Key ya utilizada con un payload de solicitud distinto. Genere una clave fresca.",
  "trace_id": "..."
}

Esto protege contra errores del lado cliente donde la misma clave se reutiliza para operaciones lógicamente distintas. Siempre genere una clave fresca para cada nueva operación; solo reutilice una clave al reintentar la misma solicitud exacta tras un fallo transitorio.

Matriz de decisión de reintentos

Cuando una solicitud falla, esta matriz le indica si debe reintentar con la misma clave o generar una nueva.

Por qué la misma clave para reintentos 5xx/429: el servidor podría haber procesado la solicitud original aunque la respuesta no haya llegado a usted. Reutilizar la clave permite al servidor retornar la respuesta original (o detectar el duplicado en vuelo). Sin idempotencia, su reintento crea una operación duplicada.

Específico de FX: interacción con ventana de bloqueo de tasa

Las llamadas a createOrder de FX que incluyen un quote_id de una cotización bloqueada (getQuote con lock_rate=true) tienen una restricción temporal adicional: la cotización bloqueada expira después de 60 segundos (retornado en expires_at en la respuesta de cotización).

Matriz de decisión para reintentos de createOrder con cotización bloqueada:

En caso de duda, trate cualquier reintento post-expiración como una nueva operación: cotización fresca, clave de idempotencia fresca.

Reutilización del campo de monto XOR en reintento

La forma del cable FX usa XOR para los campos de monto — los clientes envían exactamente uno de origin_amount (Tengo) o destination_amount (Quiero); nunca ambos. Cuando reintenta con la misma Idempotency-Key, el mismo lado XOR debe usarse.

• Original: origin_amount: 1000, Idempotency-Key: K1 → respuesta guardada
• Reintento: destination_amount: 50000, Idempotency-Key: K1 → 409 Conflict (forma de solicitud distinta)

ARi trata el cuerpo de la solicitud — incluyendo qué lado XOR lleva el monto — como parte de la verificación hash-de-payload de la clave de idempotencia.

Mejores prácticas

1. Genere claves del lado cliente, persístalas. No pierda la clave entre el primer intento y un reintento. Si su cliente se cae, recuperar la clave desde almacenamiento durable le permite reintentar con seguridad.
2. No comparta claves entre operaciones. Una operación = una clave. Nunca etiquete dos intenciones distintas con el mismo valor de clave.
3. No reutilice claves después de éxito explícito. Una vez que recibe una respuesta 200/201, esa clave está "quemada" — generar una nueva clave para la siguiente operación es más barato que arriesgar deduplicación involuntaria.
4. Agregue un prefijo reconocible para depuración. ARi acepta cualquier cadena ^[a-zA-Z0-9_-]{1,128}$. Su equipo de operaciones se lo agradecerá cuando puedan hacer grep de partner-fx- en los logs.

Vea también

• Autenticación — encabezados requeridos
• Errores — códigos BFF-IDEM-001, DB-IDEM-409
• Órdenes FX — mecánica de la ventana de bloqueo de tasa