Жизненный цикл заказа
Одна статусная модель для приложения курьера, кабинета, API и вебхуков — с правилами изменения и отмены.
Статусы — по стандарту Onfleet / Deliverect и одинаковые везде: в приложении курьера, вашем кабинете, нашем
бэк-офисе, GET /v1/orders/{id} и вебхуках.
Статусы
| Шаг | Статус | Что происходит | Финальный |
|---|---|---|---|
| 1 | created | Создан | |
| 1 | scheduled | Запланирован к времени или в слот | |
| 2 | searching | Поиск курьера | |
| 3 | assigned | Курьер назначен | |
| 4 | to_pickup | Курьер едет за заказом | |
| 5 | at_pickup | Курьер на точке забора (ожидание сборки считается) | |
| 6 | picked_up | Забрал заказ | |
| 7 | to_dropoff | В пути к получателю | |
| 8 | at_dropoff | У получателя | |
| 9 | delivered | Доставлен | да |
| 9 | failed | Не доставлен (с кодом причины) | |
| 9 | returning | Возврат на точку забора | |
| 9 | returned | Возвращён | да |
| 7 | transfer | Передача другому курьеру (поломка, ДТП, разряд) | |
| — | cancelled | Отменён (до забора) | да |
| — | lost | Утерян (по инциденту) | да |
history[] заказа хранит каждый переход со временем, reason_code и версией заказа version. Версия растёт с
каждым изменением заказа — вебхуки несут её как order_version, поэтому событие старше уже известного состояния
всегда можно отбросить.
Переназначение и передача
Заказ может сменить курьера на любом шаге; вы получаете order.courier_assigned с replaced: true.
- До забора (
assigned,to_pickup,at_pickup) — курьер отказался, пропал со связи, села батарея или нашёлся курьер ближе: заказ возвращается вsearchingс кодом причины и приоритетом, ETA пересчитывается (order.eta_changed, если сдвиг больше вашего порога). - После забора — поломка, ДТП или разряд без станции рядом: второй курьер забирает заказ в точке встречи, статус
transfer, передача подтверждается кодами и фото с обеих сторон; затем сноваto_dropoff.
Изменение заказа
PATCH /v1/orders/{id} меняет только переданные поля.
| Поле | До picked_up | После забора |
|---|---|---|
dropoff (адрес, подъезд, этаж, квартира, комментарий) | да | нет |
recipient_name, scheduled_at, cod | да | нет |
recipient_phone, comment | да | да, пока заказ не завершён |
Отклонённое изменение — 422 order_not_editable с details[].field и списком ещё доступных полей editable. Новый
адрес вне зон — 422 out_of_zone.
Сигнал «собран»
POST /v1/orders/{id}/ready сообщает, что заказ собран. Без него поиск курьера стартует по нормативу сборки точки
забора (assembly_minutes), чтобы курьер не ждал у прилавка.
Отмена
POST /v1/orders/{id}/cancel с reason_code (см. коды причин):
| Когда | Результат | Плата |
|---|---|---|
created, scheduled, searching | cancelled | 0 |
assigned, to_pickup, at_pickup | cancelled; курьер получает уведомление и компенсацию | по тарифу, в cancellation_fee |
picked_up, to_dropoff, at_dropoff | заказ возвращается на точку забора (returning → returned) | возврат по тарифу |
завершён, failed, returning | 422 order_not_cancellable | — |
Не доставлен
Если курьер не может вручить заказ (получатель не отвечает, неверный адрес, отказ, нет документа для 18+, нет
оплаты), заказ переходит в failed с reason_code, затем returning → returned. Приходят order.failed и
order.returned.