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

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

Введение

Участники

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

В DBS нет отгрузок и грузомест — жизненный цикл строится вокруг одного заказа и его статусов. Один заказ DBS в API — один товар (offer_id, product_id).

Сценарий 0: Подготовка инфраструктуры DBS

До поступления заказов мерчант настраивает склад, зоны доставки (полигоны) и тарифы. Полигон описывает только зону и стоимость доставки — не слоты. Слоты настраиваются на витрине по данным от мерчанта; в API это сейчас не вынесено. Слоты не связаны с полигонами доставки.

Диаграмма последовательности

Пошаговое описание

1. Создание склада. POST /v1/location/create — локация с типом WAREHOUSE. В ответе — location_id (например, wh-msk-dbs-01). Статус локации отслеживается через location/list.
2. Полигон доставки. POST /v1/polygon/create — контур зоны (coordinates) и тарифы (delivery_options: цена, вес, НДС, тип доставки). Полигон задаёт зону и стоимость доставки, не слоты. Полигон создаётся в статусе DRAFT; активация — на стороне витрины (polygon/list).
3. Привязка к складу. POST /v1/polygon/bind — связать polygon_id и location_id.
4. Остатки и цены. POST /v1/product/stock/update и POST /v1/product/price/update — актуальные данные по товарам на складе. Без остатков заказ на витрине не оформится. Текущие значения можно читать через POST /v1/product/stock/info и POST /v1/product/price/info.
5. Обновление опций (при необходимости). POST /v1/polygon/delivery-options/update — изменение тарифов без пересоздания полигона; POST /v1/polygon/coordinates/update — корректировка границ зоны. Удаление полигона — POST /v1/polygon/delete; архивация склада — POST /v1/location/archive.

Слоты настраиваются на витрине по данным от мерчанта; в API это сейчас не вынесено. Слоты не связаны с полигонами доставки. Покупатель выбирает интервал на витрине при оформлении заказа.

JSON-примеры

Шаг 1 — POST /v1/location/create

{
  "locations": [{
    "merchant_location_id": "wh-msk-dbs-01",
    "location_types": ["WAREHOUSE"],
    "name": "Склад DBS Москва",
    "address_tail": "125009, г. Москва, ул. Тверская, д. 1"
  }]
}

Шаг 2 — POST /v1/polygon/create (фрагмент)

{
  "polygons": [{
    "name": "Москва — центр",
    "location_id": "wh-msk-dbs-01",
    "coordinates": [[[37.61, 55.75], [37.65, 55.78]]],
    "delivery_options": [{
      "weight_from": 0,
      "weight_to": 30,
      "price": 299,
      "vat": "VAT_22",
      "delivery_time_minutes": 240,
      "delivery_types": [{ "delivery_type": "COURIER" }]
    }]
  }]
}

Шаг 3 — POST /v1/polygon/bind

{
  "polygon_id": "poly-msk-center-01",
  "location_id": "wh-msk-dbs-01"
}

Шаг 4 — POST /v1/product/stock/update

{
  "stocks": [{
    "offer_id": "PHONE-001",
    "product_id": "PRD-PHONE-01",
    "location_id": "wh-msk-dbs-01",
    "count": 50
  }]
}

В теле stock/update массив называется stocks (не items). Достаточно указать offer_id или product_id; если переданы оба, приоритет у offer_id. Максимум 200 элементов в запросе.

Цены загружаются отдельным вызовом POST /v1/product/price/update (поля currency, items — см. спецификацию метода).

Сценарий 1: Курьерская доставка — полный happy path

Мерчант получает заказ ORD-DBS-2026-301 в статусе NEW с типом доставки COURIER. Слот доставки покупатель уже выбрал на витрине при оформлении. Мерчант подтверждает заказ, при необходимости корректирует слот или адрес, передаёт данные экземпляра (IMEI), упаковывает и передаёт курьеру. Код вручения (handover-code/set) — опционально: по договорённости витрины и мерчанта, мерчант может передать код покупателю или витрине. Заказ ведётся через DELIVERING до DELIVERED.

Диаграмма последовательности

Пошаговое описание

1. Опрос обновлений. POST /v1/order/dbs/status/list — периодический запрос изменений статусов (filter.status, filter.updated_at, cursor). Ответ: order_updates[] с merchant_order_id, status, updated_at.
2. Карточка заказа. POST /v1/order/dbs/list — детали: delivery (тип COURIER, address_tail), requirements, customer, цены, item_type (PRODUCT / SERVICE), опционально actions и handover_code. Для курьерской доставки address_tail — полная строка адреса (индекс, город, населённый пункт, улица, дом, квартира), например: 125009, г. Москва, ул. Тверская, д. 10, кв. 5. Для SERVICE может быть заполнен linked_merchant_order_ids.
3. Подтверждение. POST /v1/order/dbs/status/update → CONFIRMED, changed_by: "MERCHANT", changed_at (RFC3339).
4. Слот доставки при необходимости. Первичный выбор слота — на витрине покупателем. POST /v1/order/dbs/timeslot/set позволяет мерчанту обновить интервал (delivery_date_begin, delivery_date_end, changed_by), если это согласовано с клиентом. Слоты настраиваются на витрине по данным от мерчанта; в API это сейчас не вынесено. Слоты не связаны с полигонами доставки.
5. Экземпляр товара. POST /v1/order/dbs/exemplar/set — один объект exemplar: marks с mark_type: "imei" при requirements.requires_imei: true.
6. Упаковка. POST /v1/order/dbs/status/update → PACKED. На складе заказ собран и готов к передаче курьеру.
7. Код вручения опционально. POST /v1/order/dbs/handover-code/set — мерчант регистрирует код в API. По договорённости витрины и мерчанта, мерчант может передать код покупателю или витрине. Курьер получает код от мерчанта своими средствами, не через API. Шаг не обязателен в happy path.
8. В доставке. POST /v1/order/dbs/status/update → DELIVERING — курьер выехал.
9. Доставлен. POST /v1/order/dbs/status/update → DELIVERED — покупатель получил заказ. При использовании кода вручения сверка происходит на стороне мерчанта/курьера.

Слот и дату доставки можно изменить, если это согласовано с клиентом (timeslot/set); адрес — по договорённости витрины и мерчанта (delivery-address/set).

Порядок работы на складе

┌─────────────────────────────────────────────────────────────┐
│  0. Слот выбран покупателем на витрине (до поступления NEW)  │
│  1. Заказ NEW — status/list + list                            │
│  2. status/update → CONFIRMED                                 │
│  3. (опц.) timeslot/set — корректировка слота мерчантом       │
│  4. exemplar/set → IMEI / маркировка по requirements          │
│  5. СБОРКА и УПАКОВКА на складе wh-msk-dbs-01                 │
│  6. status/update → PACKED                                    │
│  7. (опц.) handover-code/set → код в API; по договорённости    │
│     витрины и мерчанта — покупателю или витрине; курьеру —   │
│     напрямую от мерчанта, не через API                        │
│  8. Передача заказа курьеру                                   │
│  9. status/update → DELIVERING                                 │
│ 10. status/update → DELIVERED                                  │
└─────────────────────────────────────────────────────────────┘

Правило: exemplar/set до PACKED; timeslot/set — при корректировке слота; handover-code/set — опционально, после PACKED; по договорённости витрины и мерчанта мерчант может передать код покупателю или витрине; курьеру — не через API. Слоты настраиваются на витрине по данным от мерчанта; в API это сейчас не вынесено. Слоты не связаны с полигонами доставки.

JSON-примеры

Шаг 1 — POST /v1/order/dbs/status/list

{
  "cursor": "",
  "filter": {
    "status": ["NEW"],
    "updated_at": "2026-06-14T00:00:00+03:00"
  }
}

{
  "order_updates": [{
    "merchant_order_id": "ORD-DBS-2026-301",
    "client_order_id": "CLT-80001",
    "status": "NEW",
    "updated_at": "2026-06-14T11:20:00+03:00"
  }],
  "next_cursor": ""
}

Шаг 2 — POST /v1/order/dbs/list

{
  "cursor": "",
  "filter": {
    "merchant_order_id": ["ORD-DBS-2026-301"],
    "status": ["NEW"]
  }
}

{
  "orders": [{
    "merchant_order_id": "ORD-DBS-2026-301",
    "client_order_id": "CLT-80001",
    "location_id": "wh-msk-dbs-01",
    "status": "NEW",
    "item_type": "PRODUCT",
    "delivery": {
      "delivery_type": "COURIER",
      "address_tail": "125009, г. Москва, ул. Тверская, д. 10, кв. 5"
    },
    "product_id": "PRD-PHONE-01",
    "offer_id": "PHONE-001",
    "requirements": {
      "requires_imei": true,
      "requires_mandatory_mark": false
    },
    "actions": [{ "type": "cancel", "enabled": true }]
  }],
  "next_cursor": "",
  "total": 1
}

Шаг 3 — POST /v1/order/dbs/status/update (CONFIRMED)

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "status": "CONFIRMED",
  "changed_at": "2026-06-14T11:25:00+03:00",
  "changed_by": "MERCHANT"
}

Шаг 4 — POST /v1/order/dbs/timeslot/set (корректировка мерчантом)

Покупатель уже выбрал слот на витрине при оформлении. Ниже — два примера, как мерчант обновляет интервал через API после согласования с клиентом (например, перенос на другой день или другое доступное окно). Поля delivery_date_begin и delivery_date_end — RFC3339 с часовым поясом адреса доставки.

Москва (UTC+3) — курьер, адрес 125009, г. Москва, ул. Тверская, д. 10, кв. 5

Покупатель выбрал на витрине слот 10:00–14:00 на 15.06.2026; мерчант переносит доставку на вечернее окно 14:00–18:00 того же дня.

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "delivery_date_begin": "2026-06-15T14:00:00+03:00",
  "delivery_date_end": "2026-06-15T18:00:00+03:00",
  "changed_by": "MERCHANT"
}

Новосибирск (UTC+7) — курьер, адрес 630099, г. Новосибирск, ул. Красный проспект, д. 25, кв. 12

Склад wh-nsk-dbs-01. Покупатель выбрал на витрине слот 10:00–14:00; мерчант согласовал с клиентом перенос на следующий день, окно 14:00–18:00 по местному времени.

{
  "merchant_order_id": "ORD-DBS-2026-305",
  "delivery_date_begin": "2026-06-16T14:00:00+07:00",
  "delivery_date_end": "2026-06-16T18:00:00+07:00",
  "changed_by": "MERCHANT"
}

Шаг 5 — POST /v1/order/dbs/exemplar/set

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "product_id": "PRD-PHONE-01",
  "offer_id": "PHONE-001",
  "exemplar": {
    "exemplar_id": 1,
    "marks": [{
      "mark": "35693803564341",
      "mark_type": "imei"
    }],
    "weight": 0.22
  }
}

Шаг 7 (опционально) — POST /v1/order/dbs/handover-code/set

По договорённости витрины и мерчанта, мерчант может передать код покупателю или витрине (вне API). Курьеру код сообщается мерчантом напрямую.

{
  "handover_codes": [{
    "merchant_order_id": "ORD-DBS-2026-301",
    "code": "482917"
  }]
}

Шаг 6, 8–9 — смена статусов

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "status": "PACKED",
  "changed_at": "2026-06-15T08:30:00+03:00",
  "changed_by": "MERCHANT"
}

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "status": "DELIVERING",
  "changed_at": "2026-06-15T09:00:00+03:00",
  "changed_by": "MERCHANT"
}

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "status": "DELIVERED",
  "changed_at": "2026-06-15T11:45:00+03:00",
  "changed_by": "MERCHANT"
}

Сценарий 2: Доставка в ПВЗ / самовывоз

Заказ ORD-DBS-2026-302 с delivery_type: "PICKUP_POINT". После PACKED мерчант передаёт заказ в пункт выдачи и выставляет READY_FOR_PICKUP вместо DELIVERING. Финальный статус — DELIVERED при выдаче покупателю. Если покупатель не забрал заказ, мерчант может перевести его в CANCELLED.

1. Шаги 1–2 как в сценарии 1 — опрос и карточка; в delivery — delivery_type: "PICKUP_POINT", provider_location_id пункта выдачи.
2. POST /v1/order/dbs/status/update → CONFIRMED → PACKED. Корректировка слота через timeslot/set для ПВЗ обычно не требуется.
3. Мерчант доставляет посылку в ПВЗ (вне API).
4. POST /v1/order/dbs/status/update → READY_FOR_PICKUP — заказ ожидает покупателя в пункте.
5. После выдачи — POST /v1/order/dbs/status/update → DELIVERED.
6. Если покупатель не забрал заказ в срок — POST /v1/order/dbs/status/update → CANCELLED (из READY_FOR_PICKUP).

Для CLICK_AND_COLLECT (самовывоз с точки продавца) цепочка аналогична: PACKED → READY_FOR_PICKUP → DELIVERED или CANCELLED, если покупатель не забрал заказ. Код вручения (handover-code/set) — опционально: по договорённости витрины и мерчанта, мерчант может передать код покупателю или витрине.

Сценарий 3: Отмена заказа

Отмена в DBS реализуется двумя путями. Запрос покупателя идёт через витрину → заявка в cancellation/*, которую мерчант одобряет или отклоняет. Если отменяет мерчант — он меняет статус заказа напрямую через POST /v1/order/dbs/status/update → CANCELLED.

Путь A — отмена по запросу покупателя (через витрину)

1. Покупатель инициирует отмену на витрине; витрина создаёт заявку.
2. POST /v1/cancellation/list — filter.status: ["NEW"]
3. POST /v1/cancellation/update — status: "APPROVED_CANCEL" или "DECLINED". Поле comment — опционально.
4. При одобрении заказ переходит в CANCELLED на стороне витрины.

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

Путь B — отмена мерчантом

1. Мерчант принимает решение об отмене (товар недоступен, ошибка и т.д.).
2. POST /v1/order/dbs/status/update — status: "CANCELLED", changed_by: "MERCHANT".
3. Отдельная заявка cancellation/* не требуется.

JSON — POST /v1/cancellation/update

{
  "cancellation_id": 10042,
  "status": "APPROVED_CANCEL",
  "comment": "Товар не собран, отмена одобрена"
}

Поле comment в cancellation/update — необязательное. Его можно передать при отклонении заявки для пояснения покупателю.

JSON — отмена мерчантом через статус

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "status": "CANCELLED",
  "changed_at": "2026-06-14T12:00:00+03:00",
  "changed_by": "MERCHANT"
}

Сценарий 4: Внешняя служба доставки (СД)

Мерчант передаёт заказ в CDEK / Boxberry и сообщает трек-номер через POST /v1/order/dbs/delivery-provider/update. Далее статусы DELIVERING / DELIVERED выставляет мерчант по данным СД (автообновление по треку в спецификации не описано).

1. После PACKED — создание отправления в личном кабинете СД.
2. POST /v1/order/dbs/delivery-provider/update — provider_posting_id (трек), опционально provider_check_url.
3. POST /v1/order/dbs/status/update → DELIVERING.
4. По факту вручения СД — DELIVERED.

JSON — POST /v1/order/dbs/delivery-provider/update

{
  "merchant_order_id": "ORD-DBS-2026-301",
  "provider_posting_id": "11087654321000",
  "provider_check_url": "https://cdek.ru/track?order=11087654321000"
}

Стоимость доставки для сверки с тарифом полигона: POST /v1/order/dbs/delivery-cost/get — передать client_order_ids и/или merchant_order_ids.

Сценарий 5: Возврат DBS

Покупатель оформляет возврат на витрине. Мерчант опрашивает POST /v1/return/list, рассматривает заявку и меняет статус через POST /v1/return/dbs/status/set. При необходимости обновляет данные экземпляра — POST /v1/return/dbs/exemplar/update.

Типичная цепочка рассмотрения: NEW → PENDING / DELIVERY_APPROVED → DELIVERING → DELIVERED → APPROVED (или REJECT_REFUND). Другие статусы из спецификации: NEEDS_INFO, REJECT_PENDING, PARTIAL_REFUND, DELIVERY_TO_CLIENT, CANCELED, CLOSED.

JSON — POST /v1/return/dbs/status/set

{
  "return_id": 5001,
  "status": "DELIVERY_APPROVED"
}

{
  "return_id": 5001,
  "status": "APPROVED"
}

Статусы и ключевые правила

Статусы заказа DBS

Типы доставки

Ключевые правила интеграции

Предлагаемая state machine заказа DBS

Рекомендация для спецификации, не официальная часть API. Таблица отражает логику сценариев из этой инструкции. Реализация витрины может отличаться до фиксации в спецификации.

Допустимые переходы

Нерекомендуемые переходы

Технически API может принять и другие смены статуса, но для корректного понимания жизненного цикла заказа мерчантом не рекомендуется пропускать этапы или смешивать ветки доставки:

Предусловия перед ключевыми статусами

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

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