Версии
У записей, которые правят и магазин, и интеграция, есть version, которая растёт с каждым изменением: у категорий, товаров и вариантов, покупателей, черновиков заказов, правил рекомендаций и адресов вебхуков. Одна запись приходит с ней в заголовке ETag, ETag: "7"; в списке у каждой записи есть version.
Варианты делят версию своего товара: изменение товара или любого его варианта сдвигает её. Версия варианта и версия его товара — одно и то же число. Так же устроены вложенные записи: фото товара правятся под версией товара, адреса покупателя — под версией покупателя. У реквизитов покупателя версия своя, отдельная от покупателя.
Правка под версией
Правка или удаление записи с версией требует её версию в If-Match. Ответ приносит новую:
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"Если запись изменили после вашего чтения, запрос ничего не меняет:
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."
}| Ответ | Когда |
|---|---|
412 precondition_failed | Версия не текущая: запись изменили после вашего чтения. |
428 precondition_required | Нет If-Match. * — не версия и тоже отклоняется. |
Что делать на 412
- Прочитайте запись заново.
- Примените свою правку к тому, что в ней сейчас, — или решите, что она больше не нужна.
- Отправьте её с новым
ETag.
Запись по внешнему id
Запись по внешнему id — id записи в вашей системе, — например PATCH /products/by-external-id/{external_id}, создаёт запись, если её нет, и меняет, если есть. If-Match здесь по желанию; с ним запись должна существовать в этой версии. If-None-Match: * значит «только создать»: существующая запись получит 412.
У остатков нет версии
Остатки меняются слишком часто для версии. Установка остатка несёт количество, по которому вы считали, expected_on_hand, и получает 409 stock_on_hand_changed, если остаток сдвинулся. Приход и списание меняют остаток на величину и проверки не требуют.