Idempotencia

Cómo reintentar reservas sin duplicarlas con el encabezado Idempotency-Key.

POST /bookings exige el encabezado Idempotency-Key: un valor único por cada reserva que intentas hacer (un UUID v4 funciona). Si la red falla y no sabes si la reserva se creó, reintenta con la misma llave y el mismo cuerpo.

Reintento	Resultado
Misma llave, mismo cuerpo	La respuesta guardada de la primera vez (mismo código HTTP y cuerpo). No se crea otra reserva.
Misma llave, otro cuerpo	`409` con `idempotency_conflict`. Usa una llave nueva para una reserva distinta.
Sin llave	`400` con `idempotency_key_required`.

Las llaves son por llave de API. Guarda la tuya con tu orden antes de llamar a Muvon:

// One key per booking attempt, saved with your order before calling Muvon
const idempotencyKey = order.muvonIdempotencyKey ?? (order.muvonIdempotencyKey = crypto.randomUUID());
await saveOrder(order);

const res = await fetch("https://api.muvon.mx/api/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MUVON_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify(bookingRequest),
});
// On a timeout or a 5xx, send exactly the same request with the same key:
// you get the booking that was already made instead of a second one.

Cotizar, consultar y listar no cambian nada, así que se pueden reintentar libremente.

Reintento

Resultado

Misma llave, mismo cuerpo

La respuesta guardada de la primera vez (mismo código HTTP y cuerpo). No se crea otra reserva.

Misma llave, otro cuerpo

409 con idempotency_conflict. Usa una llave nueva para una reserva distinta.

Sin llave

400 con idempotency_key_required.

// One key per booking attempt, saved with your order before calling Muvon const idempotencyKey = order.muvonIdempotencyKey ?? (order.muvonIdempotencyKey = crypto.randomUUID()); await saveOrder(order); const res = await fetch("https://api.muvon.mx/api/v1/bookings", { method: "POST", headers: { Authorization: `Bearer ${process.env.MUVON_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify(bookingRequest), }); // On a timeout or a 5xx, send exactly the same request with the same key: // you get the booking that was already made instead of a second one.