Внешняя СД

Доставка силами СДЭК, Boxberry и других служб - передача трек-номера.

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

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

Службу видно в карточке: delivery.provider_id, например CDEK, BOXBERRY, RUSSIAN_POST. Для пункта выдачи ещё delivery.provider_location_id. Оба поля в схеме не обязательны. Отправление мерчант оформляет в кабинете службы — это вне API. Трек передаёт в API через delivery-provider/update. Статусы в API ставит мерчант по данным службы. По треку статус сам не меняется.

Дальше цепочка та же, что у пришедшего типа.

До двери: COURIER

Покупатель выбирает адрес. Пример — заказ ORD-DBS-2026-304, его везёт курьер СДЭК.

NEW → CONFIRMED → PACKED → DELIVERING → DELIVERED.

address_tail обязателен: индекс, город, населённый пункт, улица, дом, квартира. Заказ предоплачен, деньги у двери не берут. Если служба не вручила заказ, отдельного исхода в спецификации нет. Его согласуют с витриной.

  1. Опрос новых заказов. POST /v1/order/dbs/list с filter.status: ["NEW"] и limit. cursor — для следующей страницы.
  2. Карточка. В delivery обязателен только delivery_type: "COURIER". Адрес — address_tail. Служба — provider_id, если витрина её прислала. Склад сборки — location_id.
  3. Подтверждение. POST /v1/order/dbs/status/update → CONFIRMED, changed_by: "MERCHANT", changed_at (RFC3339).
  4. Слот, если его надо сдвинуть. POST /v1/order/dbs/timeslot/set — только после согласования с покупателем.
  5. Экземпляр, если он нужен. POST /v1/order/dbs/exemplar/set до PACKED.
  6. Упаковка. POST /v1/order/dbs/status/update → PACKED.
  7. Отправление в службе. Мерчант создаёт его в кабинете СДЭК, Boxberry или Почты России и получает трек. Шаг вне API.
  8. Трек. POST /v1/order/dbs/delivery-provider/update. В схеме у тела нет обязательных полей. Передают merchant_order_id и provider_posting_id. provider_check_url и comment — по необходимости. Трек отправляют до DELIVERING.
  9. В пути. POST /v1/order/dbs/status/update → DELIVERING по данным службы.
  10. Доставлен. POST /v1/order/dbs/status/update → DELIVERED, когда служба вручила заказ.

В пункт выдачи: PICKUP_POINT

Покупатель выбирает пункт службы, например пункт СДЭК. Пример — заказ ORD-DBS-2026-305. В карточке delivery_type: "PICKUP_POINT", provider_id: "CDEK", пункт — provider_location_id. address_tail не обязателен.

NEW → CONFIRMED → PACKED → DELIVERING → READY_FOR_PICKUP → DELIVERED или CANCELLED (не забрал или отказался).

Сборка, отправление в кабинете службы и трек — те же шаги, что до двери. После PACKED мерчант ставит DELIVERING, когда посылка едет в пункт, затем READY_FOR_PICKUP, когда она ждёт покупателя. READY_FOR_PICKUP можно поставить и сразу из PACKED. Забрал — DELIVERED. Не забрал или отказался — CANCELLED.

JSON — карточка до двери

POST /v1/order/dbs/list. Обязательны filter и limit.

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

{
  "orders": [{
    "merchant_order_id": "ORD-DBS-2026-304",
    "client_order_id": "CLT-80004",
    "location_id": "wh-msk-dbs-01",
    "status": "NEW",
    "customer": {
      "name": "Иван Петров",
      "phone": "+79001112233"
    },
    "delivery": {
      "delivery_type": "COURIER",
      "provider_id": "CDEK",
      "address_tail": "125009, г. Москва, ул. Тверская, д. 10, кв. 5"
    },
    "product_name": "Наушники",
    "prices": [{
      "price_type": "CUSTOMER_FINAL_PRICE",
      "value": 1299000
    }],
    "delivery_date": {
      "delivery_date_begin": "2026-06-16T10:00:00+03:00",
      "delivery_date_end": "2026-06-16T14:00:00+03:00"
    },
    "created_at": "2026-06-14T11:00:00+03:00"
  }],
  "next_cursor": "",
  "total": 1
}

JSON — карточка в пункт СДЭК

Тип тот же PICKUP_POINT. Служба и пункт — в provider_id и provider_location_id.

{
  "orders": [{
    "merchant_order_id": "ORD-DBS-2026-305",
    "client_order_id": "CLT-80005",
    "location_id": "wh-msk-dbs-01",
    "status": "NEW",
    "customer": {
      "name": "Иван Петров",
      "phone": "+79001112233"
    },
    "delivery": {
      "delivery_type": "PICKUP_POINT",
      "provider_id": "CDEK",
      "provider_location_id": "CDEK-MSK-0142"
    },
    "product_name": "Чайник",
    "prices": [{
      "price_type": "CUSTOMER_FINAL_PRICE",
      "value": 499000
    }],
    "delivery_date": {
      "delivery_date_begin": "2026-06-16T10:00:00+03:00",
      "delivery_date_end": "2026-06-18T21:00:00+03:00"
    },
    "created_at": "2026-06-14T11:30:00+03:00"
  }],
  "next_cursor": "",
  "total": 1
}

location_id — склад сборки. provider_location_id — пункт службы.

JSON — трек

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

JSON — статусы до двери

Обязательны merchant_order_id, status, changed_at, changed_by.

{
  "merchant_order_id": "ORD-DBS-2026-304",
  "status": "PACKED",
  "changed_at": "2026-06-14T15:00:00+03:00",
  "changed_by": "MERCHANT"
}

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

{
  "merchant_order_id": "ORD-DBS-2026-304",
  "status": "DELIVERED",
  "changed_at": "2026-06-16T13:20:00+03:00",
  "changed_by": "MERCHANT"
}

Для пункта выдачи после PACKED те же DELIVERING и затем READY_FOR_PICKUP. Забрал — DELIVERED. Не забрал или отказался — CANCELLED.

{
  "merchant_order_id": "ORD-DBS-2026-305",
  "status": "READY_FOR_PICKUP",
  "changed_at": "2026-06-16T10:00:00+03:00",
  "changed_by": "MERCHANT"
}

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