Заказы
Заказ приходит вебхуком, живёт у вас и возвращается к нам статусами. Набор статусов закрытый: свои значения не принимаются, потому что по ним считается доставка и деньги.
Статусы и переходы
| Из | Можно перейти в | Комментарий |
|---|---|---|
new | confirmed, canceled | До оплаты заказ можно только подтвердить или отменить |
confirmed | assembling, canceled | Оплата подтверждена |
assembling | assembled, canceled | Сборка началась, позиции заблокированы |
assembled | shipped | Отмена уже невозможна, только возврат |
shipped | delivered, returned | Нужен трек-номер перевозчика |
delivered | returned | Возврат принимается 14 дней |
Переход не по таблице отвергается с кодом state_transition и текущим статусом в теле ответа. Это чаще всего значит, что заказ уже перевела ваша вторая система.
Перевод статуса
POST /v1/orders/ORD-20481/status HTTP/1.1
Authorization: Bearer $CEDAR_KEY
Idempotency-Key: assemble-ORD-20481
Content-Type: application/json
{ "status": "assembled", "comment": "собран, ждёт курьера" }Заголовок Idempotency-Key обязателен на всех переводах статуса. Повтор с тем же ключом в течение суток вернёт первый ответ и ничего не сделает - это защита от двойного нажатия и от повторов на разрыве сети.
Частичная отмена и возврат
Отменить можно позицию, а не только заказ целиком: передайте items со списком sku и количеством. Когда отменены все позиции, заказ сам переходит в canceled.
Возврат после доставки оформляется отдельным методом и не меняет состав заказа: он создаёт связанный документ, чтобы в отчётности осталась и продажа, и возврат.
Блокировка на сборке
Пока заказ в assembling, состав менять нельзя: попытка вернёт 409 и код order_locked. Это не сбой, а нормальный ответ. Снимите блокировку переводом в confirmed, если сборку остановили.