Подготовка

Подготовка инфраструктуры DBS - создание локаций, складов и полигонов доставки.

Подготовка инфраструктуры DBS

До поступления заказов мерчант настраивает склад и полигоны. На полигоне задаются зона доставки (coordinates), стоимость (delivery_options.price) и слоты (delivery_options.time_slots). Витрины могут накладывать свои ограничения на тарифы и доступные слоты.

До начала работы необходимо прогрузить остатки на каждый склад (stock/update с location_id) и выставить цены (price/update). Без остатков и цен заказ на витрине не оформится.

Предусловие: товары и артикулы

Остатки и цены грузятся по идентификаторам товара — offer_id (артикул продавца) и product_id (id товара на витрине). Заводить товары через DBS Seller API нельзя: в схеме DBS нет методов создания карточек.

Карточки товаров и артикулы создаются в личном кабинете продавца (ЛКП) той витрины, на которую выходит мерчант, — там же витрина присваивает product_id. Порядок заведения, требования к карточке и сроки модерации задаёт витрина, уточняйте их при подключении.

Что делать в API после заведения:

  • Сверить соответствия offer_id ↔ product_id — POST /v1/product/mapping/list (filter, limit; в фильтре offer_id[], product_id[], is_archived). В ответе у каждой строки есть признак is_archived: архивный товар скрыт из выдачи.
  • Скрыть или вернуть товар в выдачу — POST /v1/product/archive/update (is_archived). Либо обнулить остаток через stock/update.
  • Дальше грузить остатки и цены (шаг 4). Правило идентификаторов общее: заполняется либо offer_id, либо product_id; если пришли оба — приоритет у product_id; витрина может потребовать передавать оба.

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

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

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

JSON-примеры

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

LocationCreateItem.required: location_types, name, latitude, longitude, limits (length, width, height, weight), working_schedule (day, schedule.time_start, schedule.time_end), is_accepts_returns. merchant_location_id и address_tail — опционально.

{
  "locations": [{
    "merchant_location_id": "wh-msk-dbs-01",
    "location_types": ["WAREHOUSE"],
    "name": "Склад DBS Москва",
    "address_tail": "125009, г. Москва, ул. Тверская, д. 1",
    "latitude": 55.757,
    "longitude": 37.615,
    "is_accepts_returns": false,
    "limits": {
      "length": 200,
      "width": 120,
      "height": 120,
      "weight": 50
    },
    "working_schedule": [
      { "day": "MONDAY", "schedule": { "time_start": "09:00", "time_end": "21:00" } },
      { "day": "TUESDAY", "schedule": { "time_start": "09:00", "time_end": "21:00" } },
      { "day": "WEDNESDAY", "schedule": { "time_start": "09:00", "time_end": "21:00" } },
      { "day": "THURSDAY", "schedule": { "time_start": "09:00", "time_end": "21:00" } },
      { "day": "FRIDAY", "schedule": { "time_start": "09:00", "time_end": "21:00" } },
      { "day": "SATURDAY", "schedule": { "time_start": "09:00", "time_end": "18:00" } },
      { "day": "SUNDAY", "schedule": { "time_start": "09:00", "time_end": "18:00" } }
    ]
  }]
}

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

У полигона required: coordinates, delivery_options. name и location_id — опционально. У delivery_options[].required: currency, delivery_time_minutes, delivery_types, price. vat, weight_from / weight_to, time_slots — опционально.

{
  "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,
      "currency": "RUB",
      "vat": "VAT_22",
      "delivery_time_minutes": 240,
      "delivery_types": [{ "delivery_type": "COURIER" }],
      "time_slots": [
        { "from": "10:00", "to": "14:00" },
        { "from": "14:00", "to": "18:00" }
      ]
    }]
  }]
}

Шаг 2 — курьерская доставка одежды с примеркой

Отдельный delivery_option для одежды: курьер, примерка включена (is_fitting), время на примерку 15 минут (fitting_duration_minutes). Витрины могут не поддерживать опцию или ограничить длительность.

{
  "polygons": [{
    "name": "Москва — центр, одежда",
    "location_id": "wh-msk-dbs-01",
    "coordinates": [[[37.61, 55.75], [37.65, 55.78]]],
    "delivery_options": [{
      "weight_from": 0,
      "weight_to": 10,
      "price": 399,
      "currency": "RUB",
      "vat": "VAT_22",
      "delivery_time_minutes": 240,
      "delivery_types": [{ "delivery_type": "COURIER" }],
      "time_slots": [
        { "from": "10:00", "to": "14:00" },
        { "from": "14:00", "to": "18:00" }
      ],
      "additional_options": [{
        "option_name": "is_fitting",
        "value": true,
        "options": [{
          "option_name": "fitting_duration_minutes",
          "value": 15
        }]
      }]
    }]
  }]
}

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

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

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

У запроса required: items. У элемента required: location_id, count. offer_id / product_id — хотя бы одно (если оба, приоритет у product_id).

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

Максимум 200 элементов в запросе. Остатки передаются по каждому складу отдельно (location_id).

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

Цены выставляются до начала работы. Поля currency и items обязательны.

{
  "currency": "RUB",
  "items": [{
    "offer_id": "PHONE-001",
    "product_id": "PRD-PHONE-01",
    "price": 5999000
  }]
}