Подключение по схеме DBS

Пошаговое руководство для мерчанта - от получения токена до боевого трафика.

DBS (Delivery by Seller) — схема, при которой продавец сам управляет логистикой: держит склады, задаёт зоны доставки, собирает и везёт заказ покупателю.

Что нужно сделать, чтобы подключиться

Подключение. Первый шаг нельзя пропустить: без доступов и согласованных правил витрины остальные шаги не выполняются.

Шаг	Что делает мерчант	Методы
0	Получает хост и токен, согласует правила и ограничения витрины	—
1	Создаёт склады и точки выдачи	`location/create`, `location/list`
2	Создаёт полигоны доставки и привязывает их к складам	`polygon/create`, `polygon/bind`, `polygon/list`
3	Заводит карточки в ЛКП витрины и сверяет соответствия артикулов	`product/mapping/list`
4	Загружает цены и остатки	`product/price/update`, `product/stock/update`
5	Получает новые заказы	`order/dbs/list`
6	Ведёт заказ по статусам до `DELIVERED`	`order/dbs/status/update` и методы ветки
7	Обрабатывает отмены и возвраты	`cancellation/`, `return/`

Шаги 1–4 делаются один раз при подключении, дальше — по мере изменений. Шаги 5–7 в повторяющемся цикле: периодически запрашивает новые заказы, обновляет их статусы, обрабатывает отмены и возвраты.

Что важно понять до первого запроса

Хост и токен выдаёт каждая витрина отдельно. В контракте стоит заглушка api.example.com. Один токен работает с одной витриной: для второй витрины нужна вторая пара «хост + токен» и отдельная запись в конфиге.

Витрина сужает контракт. Спецификация задаёт максимум допустимого. Поверх неё витрина накладывает свои правила: какие значения полей принимает, какие статусы и переходы разрешает, какого размера батч пропускает, как часто можно стучаться. Отказ по правилу витрины приходит кодом STOREFRONT_RULE_VIOLATION с текстом в message. Всё это выясняется до интеграции.

Webhook в API нет. Новые заказы, смены статусов, заявки на отмену и возврат мерчант опрашивает сам списками.

Один заказ DBS — один товар. В заказе нет массива позиций (это не корзина): product_id, offer_id, product_name, prices лежат в рамках 1 заказа. Отгрузок и грузомест в DBS нет — они только в FBS и FBO.

Участники

Кто	Роль
Мерчант	Продавец. Держит склад, собирает заказ и доставляет покупателю курьером, в пункт выдачи заказов (ПВЗ), через внешнюю службу доставки (СД) или выдаёт на своей точке
Витрина	Бэкенд маркетплейса. Принимает заказы, назначает склад (`location_id`), передаёт адрес и тип доставки, модерирует локации и полигоны
API	DBS Seller API — REST поверх HTTPS. Все методы `POST`, тело и ответ JSON
Покупатель	Оформляет заказ на витрине и там же выбирает слот доставки из интервалов полигона (`time_slots`)

Ветки доставки

Тип доставки приходит в заказе в поле delivery.delivery_type и определяет, по какой цепочке статусов вести заказ.

`delivery_type`	Что это	Цепочка после `PACKED`	Инструкция
`COURIER`	Курьер до адреса покупателя	`DELIVERING` → `DELIVERED`	Курьерка
`EXPRESS`	Срочная курьерская доставка	`DELIVERING` → `DELIVERED` + tracking	Express
`PICKUP_POINT`	Доставка в пункт выдачи	`READY_FOR_PICKUP` → `DELIVERED`	ПВЗ
`CLICK_AND_COLLECT`	Самовывоз с точки продавца	`READY_FOR_PICKUP` → `DELIVERED`	C&C

Отдельно стоит доставка внешней службой доставки: это не отдельный delivery_type, а способ исполнения ветки COURIER или PICKUP_POINT силами СДЭК, Boxberry и подобных — см. Внешняя СД.

Константы примеров

Во всех инструкциях используются одни и те же значения, чтобы примеры складывались в один сквозной сценарий.

Что	Значение
Склад DBS	`location_id: "wh-msk-dbs-01"`
Точка самовывоза	`location_id: "cnc-msk-tverskaya-01"`
Полигон	`polygon_id: "poly-msk-center-01"` — курьерская зона по центру Москвы
Товар	`offer_id: "PHONE-001"`, `product_id: "PRD-PHONE-01"`
Дата доставки	`2026-06-15`, слот 10:00–14:00 (выбран покупателем на витрине)
Заказы	`ORD-DBS-2026-301` (смартфон, курьер), `ORD-DBS-2026-302` (чайник, ПВЗ), `ORD-DBS-2026-303` (наушники, C&C)

Полный справочник методов

Все методы DBS с детальными параметрами и ответами — в разделе API Reference DBS.