Idempotencia

Una escritura puede vencer por timeout después de que la tienda la aplicó. El encabezado Idempotency-Key hace segura la repetición: la tienda aplica la solicitud una vez y responde la repetición con el resultado guardado.

Cargando el índice de búsqueda…

Idempotencia

Cómo usarlo

  1. Generá una clave nueva para cada operación, como un UUID, y guardala con la operación en tu sistema.
  2. Enviala en el encabezado Idempotency-Key de la escritura.
  3. Después de un timeout o un error de red, repetí la solicitud con la misma clave y el mismo cuerpo.

La respuesta se guarda durante 24 horas. Una repetición la recibe de vuelta — el mismo estado y cuerpo — con Idempotent-Replayed: true:

Solicitud
curl -X POST "https://api.saleya.app/v1/inventory-levels/set" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 0b4a9a3c-6c4e-4f0e-9a43-2f8f6d1b7e21' \
  -H "Content-Type: application/json" \
  -d '{
  "variant_id": 1042,
  "location_id": 3,
  "on_hand": "24",
  "expected_on_hand": "20"
}'
Respuesta
HTTP/1.1 200 OK
Idempotent-Replayed: true

{
  "status": "applied",
  "inventory_level": {
    "variant_id": 1042,
    "location_id": 3,
    "on_hand": "24",
    "reserved": "2",
    "available": "22",
    "updated_at": "2026-11-11T14:30:00Z"
  }
}

Toda escritura acepta la clave: POST, PATCH, PUT y DELETE. Una clave tiene de 1 a 255 caracteres ASCII visibles.

Reglas

CasoRespuesta
La misma clave con otro método, ruta o cuerpo422 idempotency_key_reused
La primera solicitud con la clave todavía corre409 idempotency_key_in_use con Retry-After: 1
La primera solicitud fue rechazadaUn rechazo no se guarda, así que la repetición corre de nuevo
Pasaron más de 24 horasLa clave se olvida, y la repetición corre como una solicitud nueva
No se puede leer el encabezado422 invalid_idempotency_key

Los cuerpos se comparan por contenido: el orden de las claves en el JSON no importa. Las claves de una aplicación no se cruzan con las de otra.

Todo o nada

Cada escritura corre como una transacción: se aplica entera o no se aplica, y un rechazo no deja nada a medias. Algunos endpoints verifican más por su cuenta: el stock se fija contra la cantidad que contaste, expected_on_hand, y un stock que se movió desde entonces recibe 409 stock_on_hand_changed.

Siguiente guíaVersiones e If-Match