¿Por qué importa?

Cuando su integración hace POST a un endpoint que muta estado (crear pedido, recargar saldo) y el request se cae a mitad de camino — timeout, red intermitente, 502 transitorio — usted no sabe con certeza si la operación se aplicó o no. Reintentar a ciegas puede crear dos pedidos por el mismo carrito o duplicar la recarga.

El header Idempotency-Key resuelve esto: envía una llave única en el primer intento; en reintentos con la misma llave la API devuelve el mismo resultado original sin re-ejecutar la mutación.

Endpoints soportados

POST /external/orders
POST /external/customers/:id/wallet/recharge
POST /external/customers/by-phone/:phone/wallet/recharge
POST /external/inventory/licenses

En endpoints no listados el header se ignora. Para webhooks, el receptor debe deduplicar usando X-Nuvlyx-Event-Id.

Cómo usar el header

curl -X POST https://api.nuvlyx.com/api/v1/external/orders \
  -H "Authorization: Bearer nvl_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bot-wa-pedido-9f8e2a1b" \
  -d '{ "customerPhone": "+573001234567", "items": [...] }'

Reglas para la llave

String único por operación. Recomendamos UUIDv4 o un prefijo + id de negocio (bot-wa-pedido-{orderId}).
Máximo 80 caracteres.
La llave es válida por 24 horas; después se libera.
Si reintenta con la misma llave y un body distinto, recibirá 409 Conflict.

Patrón recomendado en el bot

Genere la llave ANTES del primer intento (UUIDv4).
Guarde la llave junto a su registro de la operación.
Reintente con la misma llave hasta éxito o agotamiento del backoff.
Si vuelve a procesar el mismo evento (por ej. el webhook se redelivere), use la MISMA llave de antes.

Nota

El soporte completo de Idempotency-Key está en rollout — algunos endpoints lo aceptan ya, otros lo ignoran silenciosamente. Esta página se mantiene como el contrato hacia donde nos dirigimos. Mientras tanto, escriba su integración como si ya estuviera activo: cuando lo activemos no tendrá que cambiar nada.

Idempotency-Key para reintentos seguros