Versiones
Los registros que cambian tanto la tienda como una integración tienen una version que crece con cada cambio: las categorías, los productos y las variantes, los clientes, los borradores de pedido, las reglas de recomendaciones y los endpoints de webhooks. Un registro individual la trae en el encabezado ETag, ETag: "7"; en un listado cada registro tiene version.
Las variantes comparten la versión de su producto: un cambio del producto o de cualquiera de sus variantes la mueve. La versión de una variante y la de su producto son el mismo número. Los registros anidados funcionan igual: las fotos del producto se cambian con la versión del producto, y las direcciones del cliente, con la versión del cliente. Los datos fiscales del cliente tienen su propia versión, separada de la del cliente.
Cambiá bajo una versión
El cambio o la eliminación de un registro con versión necesita su versión en If-Match. La respuesta trae la nueva:
curl -X PATCH "https://api.saleya.app/v1/variants/1042" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H 'Idempotency-Key: 5d2c1f0e-8b7a-4c3d-9e2f-1a0b9c8d7e6f' \
-H "Content-Type: application/json" \
-d '{
"price": 129900
}'HTTP/1.1 200 OK
ETag: "8"Si el registro cambió después de que lo leíste, la solicitud no cambia nada:
curl -X PATCH "https://api.saleya.app/v1/variants/1042" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H 'Idempotency-Key: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d' \
-H "Content-Type: application/json" \
-d '{
"price": 129900
}'HTTP/1.1 412 Precondition Failed
{
"type": "precondition_failed",
"title": "The record has changed",
"status": 412,
"detail": "The version in If-Match does not match the record: it was changed after it was read, or the If-None-Match condition is false. Read the record again, apply your change to it and repeat the request with the new ETag."
}| Respuesta | Cuándo |
|---|---|
412 precondition_failed | La versión no es la actual: el registro cambió después de que lo leíste. |
428 precondition_required | No hay If-Match. * no es una versión y también se rechaza. |
Ante un 412
- Leé el registro de nuevo.
- Aplicá tu cambio a lo que hay ahora — o decidí que ya no hace falta.
- Envialo con el
ETagnuevo.
Escribir por ID externo
Escribir por ID externo —el ID del registro en tu sistema—, como PATCH /products/by-external-id/{external_id}, crea el registro si no existe y lo cambia si existe. Acá If-Match es opcional; con él, el registro tiene que existir en esa versión. If-None-Match: * significa solo crear: un registro existente recibe 412.
El stock no tiene versión
El stock cambia demasiado seguido para una versión. Fijar stock lleva la cantidad que contaste, expected_on_hand, y recibe 409 stock_on_hand_changed si el stock se movió. Ingresar y dar de baja cambia el stock en una cantidad y no necesita verificación.