Как пользоваться
- Делайте новый ключ на каждую операцию, например UUID, и храните его вместе с операцией в своей системе.
- Отправляйте его в заголовке
Idempotency-Keyзапроса записи. - После таймаута или сетевой ошибки повторите запрос с тем же ключом и тем же телом.
Ответ хранится 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.