Cómo usarlo
- Generá una clave nueva para cada operación, como un UUID, y guardala con la operación en tu sistema.
- Enviala en el encabezado
Idempotency-Keyde la escritura. - 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:
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"
}'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
| Caso | Respuesta |
|---|---|
| La misma clave con otro método, ruta o cuerpo | 422 idempotency_key_reused |
| La primera solicitud con la clave todavía corre | 409 idempotency_key_in_use con Retry-After: 1 |
| La primera solicitud fue rechazada | Un rechazo no se guarda, así que la repetición corre de nuevo |
| Pasaron más de 24 horas | La clave se olvida, y la repetición corre como una solicitud nueva |
| No se puede leer el encabezado | 422 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.