Статусы заказа
Обработка заказа и переходы статусов в схеме DBS.
Статусы и ключевые правила
Статусы заказа DBS
| NEW | Новый заказ — поступил на склад продавца |
|---|---|
| CONFIRMED | Подтверждён продавцом, можно начинать сборку |
| PACKED | Упакован, готов к передаче в доставку / ПВЗ |
| DELIVERING | Курьер или СД везут покупателю, либо товар едет в ПВЗ / на точку C&C |
| READY_FOR_PICKUP | Ожидает выдачи в ПВЗ или на точке самовывоза; если покупатель не забрал заказ или отказался — переход в CANCELLED |
| DELIVERED | Доставлен / выдан покупателю |
| CANCELLED | Отменён — через cancellation/* (запрос покупателя) или status/update (мерчант) |
Типы доставки
| COURIER | Курьер до адреса — address_tail обязателен. Цепочка через DELIVERING |
|---|---|
| PICKUP_POINT | Доставка в ПВЗ — provider_location_id; NEW → CONFIRMED → PACKED → DELIVERING → READY_FOR_PICKUP → DELIVERED или CANCELLED** (не забрал или отказался) |
| CLICK_AND_COLLECT | Самовывоз с точки продавца — NEW → CONFIRMED → PACKED → DELIVERING или READY_FOR_PICKUP → DELIVERED или CANCELLED (не забрал или отказался) |
Ключевые правила интеграции
| Единица работы | Один заказ = один товар. Нет отгрузок и грузомест (в отличие от FBS). |
|---|---|
| Инфраструктура | location/create → polygon/create → polygon/bind — зона, стоимость и слоты доставки; см. сценарий 0. Дополнительно: location/archive, polygon/delete, polygon/list |
| Остатки и цены | До начала работы: product/stock/update — остатки на каждый склад (items[] с location_id); product/price/update — цены (items[]). Чтение: product/stock/info, product/price/info |
| Опрос | На MVP: order/dbs/list. В будущем: order/dbs/status/list для событий (filter.updated_at, status), order/dbs/list для деталей. Webhook в API нет. |
| Карточка заказа | item_type: PRODUCT или SERVICE; для услуги — linked_merchant_order_ids. Поле actions — разрешённые действия (сейчас cancel) |
| Экземпляры | exemplar/set — опционально, если есть необходимость. Один объект exemplar; сверять с requirements в карточке заказа |
| Слоты | Задаются на полигоне (delivery_options.time_slots). Покупатель выбирает слот на витрине; витрины могут накладывать свои ограничения. timeslot/set — позволяет мерчанту изменить дату или интервал доставки |
| Адрес и слот | Слот и дату можно изменить, если это согласовано с клиентом (timeslot/set); адрес — по договорённости (delivery-address/set) |
| Код вручения | handover-code/set — опционально, тело handover_codes[] с merchant_order_id + code. По договорённости витрины и мерчанта код можно передать покупателю или витрине; курьер получает код от мерчанта напрямую, не через API |
| Трек СД | delivery-provider/update — внешний трек-номер |
| Отмена | Покупатель → витрина → cancellation/list + cancellation/update. Мерчант → status/update → CANCELLED |
| Возвраты | return/list, return/get, return/dbs/status/set, return/dbs/timeslot/set |
| State machine | Допустимые переходы в спецификации не описаны — ниже предлагаемая таблица |
| Ошибки API | HTTP 400, 401, 429, 500; тело ApiError: error_type, code, message, details |
Предлагаемая state machine заказа DBS
Рекомендация для спецификации, не официальная часть API. Таблица отражает логику сценариев из этой инструкции. Реализация витрины может отличаться до фиксации в спецификации.
Допустимые переходы
| Из | В | Кто инициирует | Условия / примечания |
|---|---|---|---|
| NEW | CONFIRMED | MERCHANT | Мерчант принял заказ в работу (status/update) |
| NEW | CANCELLED | MERCHANT | status/update → CANCELLED (отмена мерчантом) |
| NEW | CANCELLED | CLIENT / MARKET | Через cancellation/* → APPROVED_CANCEL (запрос покупателя через витрину) |
| CONFIRMED | PACKED | MERCHANT | Заказ собран; exemplar/set — опционально, если есть необходимость |
| CONFIRMED | CANCELLED | MERCHANT | status/update → CANCELLED |
| CONFIRMED | CANCELLED | CLIENT / MARKET | Через cancellation/update → APPROVED_CANCEL |
| PACKED | DELIVERING | MERCHANT | Курьер, внешняя СД, ПВЗ и C&C. Опционально handover-code/set; для СД — delivery-provider/update |
| PACKED | READY_FOR_PICKUP | MERCHANT | Второй допустимый путь для PICKUP_POINT и CLICK_AND_COLLECT: из PACKED сразу в READY_FOR_PICKUP, без DELIVERING. Дальше DELIVERED или CANCELLED (не забрал или отказался). |
| PACKED | CANCELLED | MERCHANT | status/update → CANCELLED |
| DELIVERING | DELIVERED | MERCHANT | Факт вручения курьером или СД. Для курьерки из DELIVERING в рекомендуемой цепочке дальше DELIVERED** |
| DELIVERING | PACKED или CANCELLED | MERCHANT | По согласованию мерчанта и витрины: недозвон, отказ у двери, перенос. Куда именно — PACKED или CANCELLED — зависит от бизнес-процесса мерчанта. Ограничения у каждой витрины свои, детализацию обсуждают при проектировании |
| DELIVERING | READY_FOR_PICKUP | MERCHANT | PICKUP_POINT и CLICK_AND_COLLECT: товар передан в ПВЗ или на точку |
READY_FOR_PICKUP | DELIVERED | MERCHANT | Покупатель забрал заказ |
READY_FOR_PICKUP | CANCELLED | MERCHANT | Покупатель не забрал заказ или отказался от заказа (status/update) |
| DELIVERED | — | — | Терминальный статус |
| CANCELLED | — | — | Терминальный статус |
Нерекомендуемые переходы
Технически API может принять и другие смены статуса, но для корректного понимания жизненного цикла заказа мерчантом не рекомендуется пропускать этапы или смешивать ветки доставки:
| Переход | Почему не рекомендуется |
|---|---|
NEW → PACKED / DELIVERING / DELIVERED | Пропуск подтверждения и подготовки — затрудняет учёт на складе |
CONFIRMED → DELIVERING / DELIVERED | Без статуса PACKED не отражён факт сборки |
PACKED → DELIVERED (курьер) | Для COURIER ожидается промежуточный DELIVERING |
Любой → из DELIVERED / CANCELLED | Терминальные статусы |
Предусловия перед ключевыми статусами
| Целевой статус | Рекомендуемые предусловия |
|---|---|
PACKED | exemplar/set — опционально, если есть необходимость (например IMEI/маркировка в requirements) |
DELIVERING | Статус PACKED; для внешней СД — delivery-provider/update |
READY_FOR_PICKUP | Статус PACKED или DELIVERING; физическая передача в ПВЗ или на точку C&C |
DELIVERED | Из DELIVERING или READY_FOR_PICKUP |
CANCELLED | Либо cancellation/update → APPROVED_CANCEL (покупатель), либо status/update → CANCELLED (мерчант); в т.ч. из READY_FOR_PICKUP, если покупатель не забрал заказ или отказался |