Идемпотентность

Запись может оборваться по таймауту уже после того, как магазин её применил. Заголовок Idempotency-Key делает повтор безопасным: магазин применяет запрос один раз, а на повтор отвечает сохранённым результатом.

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

Идемпотентность

Как пользоваться

  1. Делайте новый ключ на каждую операцию, например UUID, и храните его вместе с операцией в своей системе.
  2. Отправляйте его в заголовке Idempotency-Key запроса записи.
  3. После таймаута или сетевой ошибки повторите запрос с тем же ключом и тем же телом.

Ответ хранится 24 часа. Повтор получает его обратно — тот же статус и тело — с 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"
  }
}

Ключ принимает любая запись: POST, PATCH, PUT и DELETE. Ключ — от 1 до 255 видимых символов ASCII.

Правила

СлучайОтвет
Тот же ключ с другим методом, путём или телом422 idempotency_key_reused
Первый запрос с этим ключом ещё идёт409 idempotency_key_in_use с Retry-After: 1
Первый запрос получил отказОтказ не сохраняется, поэтому повтор выполняется заново
Срок хранения ответа — 24 часа — истёкКлюч забыт, и повтор выполняется как новый запрос
Заголовок не разобран422 invalid_idempotency_key

Тела сравниваются по содержимому: порядок ключей в JSON не важен. Ключи одного приложения не пересекаются с ключами другого.

Всё или ничего

Каждая запись идёт одной транзакцией: применяется целиком или не применяется вовсе, и отказ ничего не оставляет. Некоторые методы проверяют больше сами: остаток устанавливается против того количества, по которому вы считали, expected_on_hand, и сдвинувшийся с тех пор остаток получает 409 stock_on_hand_changed.

Следующий гайдВерсии и If-Match