Курьерская доставка

Ветка delivery_type COURIER - от NEW до DELIVERED.

Сценарий 1: Курьерская доставка до адреса

Покупатель на витрине выбирает доставку до адреса. Заказ везёт курьер мерчанта.

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

Цепочка статусов:

NEW → CONFIRMED → PACKED → DELIVERING → DELIVERED.

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

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

Опрос обновлений. На MVP — POST /v1/order/dbs/list (filter.status, cursor). В будущем опрос изменений статусов — POST /v1/order/dbs/status/list (filter.status, filter.updated_at, cursor; ответ order_updates[]).
Карточка заказа. 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.
Подтверждение. POST /v1/order/dbs/status/update → CONFIRMED, changed_by: "MERCHANT", changed_at (RFC3339).
Слот доставки при необходимости. Слоты задаются на полигоне (delivery_options.time_slots). Покупатель выбирает слот на витрине; витрины могут накладывать свои ограничения. POST /v1/order/dbs/timeslot/set позволяет мерчанту изменить дату или интервал доставки (delivery_date_begin, delivery_date_end, changed_by), если это согласовано с клиентом.
Экземпляр товара (опционально). POST /v1/order/dbs/exemplar/set — если есть необходимость (например requirements.requires_imei: true). Один объект exemplar: marks с mark_type: "imei".
Упаковка. POST /v1/order/dbs/status/update → PACKED. На складе заказ собран и готов к передаче курьеру.
Код вручения опционально. POST /v1/order/dbs/handover-code/set — мерчант регистрирует код в API. По договорённости витрины и мерчанта, мерчант может передать код покупателю или витрине. Курьер получает код от мерчанта своими средствами, не через API. Шаг не обязателен в happy path.
В доставке. POST /v1/order/dbs/status/update → DELIVERING — курьер выехал.
Доставлен. POST /v1/order/dbs/status/update → DELIVERED — покупатель получил заказ. При использовании кода вручения сверка происходит на стороне мерчанта/курьера.

В рекомендуемой цепочке из DELIVERING дальше только DELIVERED. Отдельного статуса для «не дозвонились», «отказ у двери» и «перенос» нет. По согласованию мерчанта и витрины заказ может уйти из DELIVERING в PACKED либо в CANCELLED — смотря какие условия есть у мерчанта по бизнес-процессу. Ограничения на каждой витрине свои. Детализацию нужно обсуждать при проектировании, до реализации на своей стороне. Заказ предоплачен: деньги у двери не берут.

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

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

┌─────────────────────────────────────────────────────────────┐
│  0. Слот выбран покупателем на витрине (до поступления NEW) │
│  1. Заказ NEW — list (MVP); в будущем status/list           │
│  2. status/update → CONFIRMED                               │
│  3. (опц.) timeslot/set — корректировка слота мерчантом     │
│  4. (опц.) exemplar/set — если есть необходимость           │
│  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.

JSON-примеры

Шаг 1 — POST `/v1/order/dbs/list` (MVP: опрос)

На MVP новые заказы опрашиваются через list (filter.status). В будущем для опроса изменений статусов используйте POST /v1/order/dbs/status/list.

OrderListRequest.required: filter, limit. cursor опционален.

{
  "cursor": "",
  "limit": 100,
  "filter": {
    "status": ["NEW"]
  }
}

Ответ. У OrderListItem.required: merchant_order_id, client_order_id, location_id, status, customer, delivery, product_name, prices, delivery_date, created_at. У delivery.required только delivery_type; address_tail для COURIER обязателен по описанию поля. У prices[].required: price_type, value. item_type, product_id, offer_id, requirements, actions — опционально.

{
  "orders": [{
    "merchant_order_id": "ORD-DBS-2026-301",
    "client_order_id": "CLT-80001",
    "location_id": "wh-msk-dbs-01",
    "status": "NEW",
    "customer": {
      "name": "Иван Петров",
      "phone": "+79001234567"
    },
    "delivery": {
      "delivery_type": "COURIER",
      "address_tail": "125009, г. Москва, ул. Тверская, д. 10, кв. 5"
    },
    "item_type": "PRODUCT",
    "product_id": "PRD-PHONE-01",
    "offer_id": "PHONE-001",
    "product_name": "Смартфон",
    "prices": [{
      "price_type": "CUSTOMER_FINAL_PRICE",
      "value": 5999000
    }],
    "requirements": {
      "requires_imei": true,
      "requires_mandatory_mark": false
    },
    "actions": [{ "type": "cancel", "enabled": true }],
    "delivery_date": {
      "delivery_date_begin": "2026-06-15T10:00:00+03:00",
      "delivery_date_end": "2026-06-15T14:00:00+03:00"
    },
    "created_at": "2026-06-14T11:00:00+03:00"
  }],
  "next_cursor": "",
  "total": 1
}

В будущем — POST /v1/order/dbs/status/list. OrderUpdatesListRequest.required: filter, limit.

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

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

OrderStatusUpdateRequest.required: merchant_order_id, status, changed_at, changed_by.

{
  "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). Курьеру код сообщается мерчантом напрямую.

{
  "handoverCodes": [
    {
      "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"
}

Курьерская доставка

Шаг 1 — POST /v1/order/dbs/list (MVP: опрос)

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

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

Шаг 1 — POST `/v1/order/dbs/list` (MVP: опрос)

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

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