Версии и If-Match

Пока ваша система работает с записью, её может изменить кто-то в магазине. Версия в If-Match применяет вашу правку только к той записи, которую вы прочитали.

Загружаем поисковый индекс…

Версии и If-Match

Версии

У записей, которые правят и магазин, и интеграция, есть 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

  1. Прочитайте запись заново.
  2. Примените свою правку к тому, что в ней сейчас, — или решите, что она больше не нужна.
  3. Отправьте её с новым 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, если остаток сдвинулся. Приход и списание меняют остаток на величину и проверки не требуют.

Следующий гайдЛимиты запросов