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
5xxo 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).