# Idempotencia

Las redes fallan: una respuesta se pierde y tu sistema no sabe si la entrega se creó. Con `Idempotency-Key` podés reintentar **sin duplicar**.

## Cómo funciona

`POST /api/v1/deliveries` exige el encabezado `Idempotency-Key`: un identificador estable de tu pedido, de 1 a 128 caracteres `A-Z a-z 0-9 _ . : -` (por ejemplo `pedido-1042`). En el lote, cada ítem lleva su `idempotencyKey`.

| Situación | Respuesta |
| --- | --- |
| Primera vez | `201` y la entrega nueva (`Idempotent-Replayed: false`). |
| Misma clave y mismo cuerpo | `201` con **el cuerpo original** e `Idempotent-Replayed: true`, aunque la entrega haya cambiado después. Nunca se crea una segunda, ni con solicitudes simultáneas. |
| Misma clave, otro cuerpo | `409 IDEMPOTENCY_CONFLICT`. |
| Falta o es inválida | `400 IDEMPOTENCY_KEY_REQUIRED`. |

- Las claves de idempotencia son **propias de cada clave de API**: dos integraciones no chocan entre sí.
- El orden de los campos del JSON y los espacios no importan; los valores se comparan tal cual.
- Ante un `5xx` o un timeout, reintentá con la **misma** clave. Para un pedido distinto, usá una clave distinta.

## Además de la clave: la referencia de tu pedido

`externalReference` es única por empresa y comercio. Aunque por error mandes el mismo pedido con otra `Idempotency-Key`, la segunda llamada recibe `409 EXTERNAL_REFERENCE_TAKEN` y podés buscar la entrega existente con `GET /api/v1/deliveries?externalReference=…`.

## Operaciones que ya son idempotentes

- `POST /api/v1/deliveries/{id}/cancel`: repetirla responde la misma entrega cancelada.
- `PATCH /api/v1/deliveries/{id}`: enviar los mismos valores deja la entrega igual.
- Los avisos (webhooks) pueden llegar más de una vez con el **mismo** `Ruta-Event-Id`: descartá los repetidos ([webhooks](webhooks.html#duplicados-y-orden)).