Запрос информации о товарах

Описание

POST cart

С помощью этого запроса Маркет убеждается, что товары, которые покупатель сложил в корзину, в самом деле в наличии в магазине. У DBS-магазинов запрашивается не только наличие, но и информация о возможностях доставки и доступных способах оплаты.

⚠️ Если вы продаете цифровые товары, обязательно прочтите инструкцию.

URL ресурса:

https://<URL_запроса>/cart

Таймаут на получение ответа: 5,5 секунд.

Передаваемые магазину данные

Структура данных в теле запроса приведена ниже. Порядок следования параметров не гарантируется.

{
  "cart":
  {
    "businessId": {int64},
    "currency": "{enum}",
    "delivery":
    {
      "region":
      {
        "id": {int32},
        "name": "{string}",
        "type": "{enum}",
        "parent":
        {
          "id": {int32},
          "name": "{string}",
          "type": "{enum}",
          "parent":
          {
            ...
          }
        }
      }
    },
    "items":
    [
      {
        "count": {int32},
        "feedId": {int64},
        "offerId": "{string}",
        "warehouseId": {int64},
        "partnerWarehouseId": "{string}",
        "categoryId": {int64},
        "feedCategoryId": "{string}"
      },
      ...
    ]
  }
}

{
  "cart":
  {
    "businessId": {int64},
    "currency": "{enum}",
    "deliveryCurrency": "{enum}",
    "delivery":
    {
      "estimated": {boolean},
      "region":
      {
        "id": {int32},
        "name": "{string}",
        "type": "{enum}",
        "parent":
        {
          "id": {int32},
          "name": "{string}",
          "type": "{enum}",
          "parent":
          {
            ...
          }
        }
      },
      "address":
      {
        "country": "{string}",
        "city": "{string}",
        "subway": "{string}",
        "street": "{string}",
        "house": "{string}",
        "block": "{string}",
        "floor": "{string}"
      }
    },
    "items":
    [
      {
        "feedId": {int64},
        "offerId": "{string}",
        "count": {int32},
        "offerName": "{string}",
        "feedCategoryId": "{string}",
        "fulfilmentShopId": {int64}
      },
      ...
    ]
  }
}

Параметр

Тип

Значение

cart

Описание

Корзина.

Параметры, вложенные в cart

Параметр

Тип

Значение

businessId

Int64

Идентификатор бизнеса-аккаунта.

currency

Enum

Валюта, в которой выражены цены товаров в заказе:

  • RUR — российский рубль.

deliverycurrency

DBS

Enum

Валюта, в которой выражены цены товаров в заказе:

  • RUR — российский рубль.

delivery

Описание

Информация о доставке.

items

Описание

Товары в корзине.

Параметры, вложенные в delivery

Параметр

Тип

Значение

region

Описание

Регион доставки.

address

DBS

Описание

Адрес доставки. Передается, если покупатель уже указал адрес на Маркете.

estimated

DBS

Boolean

Признак, показывающий, что дата доставки по заказу не подтверждена. Передается для товаров на заказ с долгим сроком доставки (31-60 дней). Окончательную дату доставки нужно передать Маркету в течение 7 дней с даты оформления заказа в запросе PUT campaigns/{campaignId}/orders/{orderId}/delivery/date.

Параметры, вложенные в region

Параметр

Тип

Значение

id

Int32

Идентификатор региона.

name

String

Название региона.

type

Enum

Тип региона.

Возможные значения:

  • CITY — город.
  • CITY_DISTRICT — район города.
  • CONTINENT — континент.
  • COUNTRY — страна.
  • COUNTRY_DISTRICT — федеральный округ.
  • METRO_STATION — станция метро.
  • MONORAIL_STATION — станция монорельса.
  • OTHERS_UNIVERSAL — другой тип населенного пункта.
  • OVERSEAS_TERRITORY — отдельная территория какого-либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).
  • REGION — регион.
  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).
  • SETTLEMENT — поселение.
  • SUBJECT_FEDERATION — субъект федерации.
  • SUBJECT_FEDERATION_DISTRICT — район субъекта федерации.
  • SUBURB — пригород.
  • VILLAGE— село.

parent

region

Родительский регион.

Указываются родительские регионы до уровня страны включительно (type=COUNTRY).

Параметры, вложенные в address

Параметр

Тип

Значение

country

String

Страна

city

String

Город или населенный пункт

subway

String

Станция метро

street

String

Улица

house

String

Дом или владение

block

String

Корпус или строение

floor

String

Этаж

lat

Double

Широта. Не гарантируем заполнение, так как это опциональное поле.

lon

Double

Долгота. Не гарантируем заполнение, так как это опциональное поле.

Параметры, вложенные в items

Параметр

Тип

Значение

feedId

Int64

Идентификатор каталога товаров. В ответе магазин должен указать тот же идентификатор

offerId

String

Идентификатор вашего товарного предложения для определенного товара. Описание в Справке для продавцов

count

Int32

Количество товара.

warehouseId

Int64

Идентификатор склада на Маркете.

partnerWarehouseId

String

Идентификатор склада в системе партнера. Параметр устарел, временно поддерживается, но не доступен для ввода и редактирования.

categoryId

Int64

Идентификатор товарной категории Маркета. В ответе магазин не должен передавать этот идентификатор. Оставьте его пустым.

feedCategoryId

String

Идентификатор товарной категории из прайс-листа. В ответе магазин не должен передавать этот идентификатор. Оставьте его пустым.

Параметр

Тип

Значение

feedId

Int64

Идентификатор каталога товаров. В ответе магазин должен указать тот же идентификатор

offerId

String

Идентификатор вашего товарного предложения для определенного товара. Описание в Справке для продавцов

offerName

String

Название товара.

feedCategoryId

String

Идентификатор категории, указанной в каталоге.

fulfilmentShopId

Int64

Идентификатор поставщика товара. Чтобы узнать его, войдите в личный кабинет магазина и нажмите на его название. Идентификатор указан в поле ID магазина в строке нужного склада.

count

Int32

Количество товара.

Ответные данные от магазина

В ответе магазин должен передать актуальные данные для переданной корзины товаров и указанного региона доставки.

{
  "cart":
  {
    "items":
    [
      {
        "feedId": {int64},
        "offerId": "{string}",
        "count": {int32}
      },
      ...
    ]
  }
}

{
  "cart":
  {
    "deliveryCurrency": "{enum}",
    "deliveryOptions":
    [
      {
        "id": "{string}",
        "price": {double},
        "serviceName": "{string}",
        "type": "{enum}",
        "dates":
        {
          "fromDate": "{date}",
          "toDate": "{date}",
          "intervals":
          [
            {
              "date": "{date}",
              "fromTime": "{time}",
              "toTime": "{time}"
            },
            ...
          ]
        },
        "outlets":
        [
          {
            "code": "{string}"
          },
          ...
        ],
        "paymentMethods":
        [
          "{enum}",
          ...
        ]
      },
      ...
    ],
    "items":
    [
      {
        "feedId": {int64},
        "offerId": "{string}",
        "delivery": {boolean},
        "count": {int32}
        "sellerInn": "{string}"
      },
      ...
    ],
    "paymentMethods":
    [
      "{enum}",
      ...
    ]
  }
}

Как передавать данные по товарам в разных ситуациях

В переданный регион или адрес покупателя магазин не доставляет заказы (DBS)

Укажите пустые опции доставки: "deliveryOptions": []. В параметре items для каждого товара параметр delivery передавать необязательно.

В корзине присутствуют товары, которые магазин не доставляет в указанный регион либо по указанному адресу (DBS)

Для таких товаров укажите "delivery": false в параметре items.

Товар отсутствует в продаже (DBS)

Укажите для товара параметр "count": 0. Если все товары из корзины отсутствуют в продаже, передайте параметр items пустым.

Важно

При получении информации о том, что товар отсутствует в продаже, через 10–15 минут соответствующее предложение перестает отображаться на Маркете по модели DBS до следующего обновления данных на сервисе (индексация происходит каждые 4 часа).

Товара сейчас нет в наличии

Укажите параметр count="0", вложенный в параметр items. Если все товары из корзины отсутствуют в продаже, передайте параметр items пустым.

Пример

Для удобства чтения пример кода приведен в сокращенном формате.

{
  "cart":
  {
    "items":
    [
      {
        "feedId": {int64},
        "offerId": "{string}",
        "count": {int32},
        "delivery": {boolean}
      },
      ...
    ]
  }
}

Как передавать информацию о доставке в пункты самовывоза (DBS)

Укажите в параметре outlets идентификаторы всех пунктов самовывоза, в которых товар уже есть в наличии и в которые вы можете доставить товар, если его там еще нет. Нужно указать все подходящие пункты самовывоза в регионе, указанном в запросе в параметре region (в том числе в случае, если параметр содержит неполный адрес: например, только город или район в области).

Если условия доставки для разных пунктов самовывоза отличаются (например, в одни пункты заказ будет доставлен завтра, а в другие — послезавтра), в параметре deliveryOptions укажите по одному вложенному параметру для каждой группы пунктов с одинаковыми условиями и в каждом из них перечислите подходящие пункты.

Как передавать данные о цифровых товарах (DBS)

В ответе на запрос от Маркета укажите следующие значения для параметров, вложенных в deliveryOptions:

  • Тип доставки "type": "DIGITAL". Это единственный доступный тип доставки для цифровых товаров.
  • Дата доставки – текущий день. (Параметр fromDate, вложенный в dates).
  • Наименование службы доставки – «Доставка на электронную почту». (Параметр serviceName).
  • Способ оплаты – предоплата (YANDEX, APPLE_PAY, GOOGLE_PAY, TINKOFF_CREDIT, TINKOFF_INSTALLMENTS, SBP).
Пример

Для удобства чтения пример кода приведен в сокращенном формате.

{
  ...
  "deliveryOptions":
  [
    {
      "id": "{string}",
      "price": 0,
      "serviceName": "Доставка на электронную почту",
      "type": "DIGITAL",
      "dates": {
        "fromDate": "{date}",
       },
      "paymentMethods": [
        "YANDEX",
        "APPLE_PAY",
        "GOOGLE_PAY",
        "TINKOFF_CREDIT",
        "TINKOFF_INSTALLMENTS",
        "SBP"
      ]
    }
  ],
  ...
}

Что передавать в качестве цены доставки (DBS)

На Маркете действует единый тариф на доставку для покупателей. Стоимость доставки подставляется автоматически из единой тарифной сетки. Можно передавать любое число — данные о стоимости доставки, переданные по API, не учитываются. Подробно о едином тарифе рассказано в Справке для продавцов.

Диапазоны дат и интервалы доставки (DBS)

Укажите в параметрах fromDate и toDate, вложенных в dates, самую раннюю и самую позднюю возможные даты доставки соответственно, а в параметре intervals — даты и (для курьерской доставки при возможности) интервалы доставки, между которыми сможет выбрать пользователь.

Набор параметров, вложенных в dates, зависит от способа доставки заказа:

  • Для заказов со способом доставки курьером ("type": "DELIVERY") следует передавать либо все три параметра (fromDate, toDate, intervals), либо только раннюю дату доставки (fromDate).
  • Для заказов со способом доставки самовывозом ("type": "PICKUP") следует передавать только параметры fromDate и toDate. Параметр intervals для таких заказов передавать нельзя.
Пример

Для удобства чтения пример кода приведен в сокращенном формате.

Что вы передадите в ответе на POST cart

Что сможет выбрать пользователь

 
"type": "DELIVERY",
"dates":
{
  "fromDate": "10-03-2021"
}

10 марта, 00:00–23:59

 
"type": "PICKUP",
"dates":
{
  "fromDate": "01-03-2021",
  "toDate": "03-03-2021"
}

1 марта, 00:00 — 3 марта, 23:59

Описание параметров:

Параметр

Тип

Значение

cart

Описание

Корзина.

Параметры, вложенные в cart

Параметр

Тип

Значение

items

Описание

Товары в корзине.

deliverycurrency

DBS

Enum

Валюта, в которой выражены цены товаров в заказе:

  • RUR — российский рубль.

deliveryOptions

DBS

Описание

Опции доставки, доступные для корзины.

paymentMethods

DBS

Enum

Способы оплаты, доступные для всех товаров в корзине:

  • YANDEX — банковской картой при оформлении.
  • APPLE_PAY — Apple Pay при оформлении.
  • GOOGLE_PAY — Google Pay при оформлении.
  • TINKOFF_CREDIT — оформить в кредит.
  • TINKOFF_INSTALLMENTS — оформить в рассрочку.
  • SBP — через систему быстрых платежей.
  • CARD_ON_DELIVERY — банковской картой при получении.
  • CASH_ON_DELIVERY — наличными при получении.

Параметры, вложенные в items

Параметр

Тип

Значение

feedId

Int64

Идентификатор каталога товаров. Нужно указать тот же идентификатор, что и в запросе от Маркета.

offerId

String

Идентификатор вашего товарного предложения для определенного товара. Описание в Справке для продавцов

count

Int32

Количество товара, которое доступно для заказа. Необязательно указывать точное количество, но важно указать то количество, которое гарантированно доступно для заказа. Если товара нет в наличии, то необходимо указывать 0.

delivery

DBS

Boolean

Доставка товара в указанный в запросе регион:

  • false — товар не доставляется в указанный регион.
  • true — значение по умолчанию, товар доставляется в указанный регион.

sellerInn

DBS

String

ИНН продавца товара

Параметры, вложенные в deliveryOptions

Параметр

Тип

Значение

id

String

Идентификатор опции доставки, присвоенный магазином. Если идентификатор указан, он будет передан обратно магазину в запросе POST order/accept. Максимальная длина: 50 символов.

price

Double

Стоимость доставки в валюте заказа. Для отделения целой части от дробной используется точка. C 1 июля 2021 вводятся единые тарифы на доставку для покупателей. Стоимость доставки будет одинакова независимо от того, кто доставляет заказ: Маркет или сам продавец. Она подставится автоматически из единой тарифной сетки. Данные о стоимости доставки, переданные по API, не будут учитываться. При этом все так же необходимо передавать Маркету информацию о сроках доставки. Подробнее в Справке для продавцов.

serviceName

String

Наименование службы доставки. Обязательный параметр. Максимальная длина: 50 символов.

type

Enum

Способ доставки заказа. Возможные значения:

  • DELIVERY — курьерская доставка.
  • PICKUP — самовывоз.
  • DIGITAL — только для цифровых товаров.

dates

Описание

Диапазон дат доставки.

outlets

Описание

Пункты самовывоза. Указывается, если выбран самовывоз ("type": "PICKUP"). Укажите в параметре outlets идентификаторы всех пунктов самовывоза.

paymentMethods

Enum

Способы оплаты, доступные для указанного вида доставки:

  • YANDEX — банковской картой при оформлении.
  • APPLE_PAY — Apple Pay при оформлении.
  • GOOGLE_PAY — Google Pay при оформлении.
  • TINKOFF_CREDIT — оформить в кредит.
  • TINKOFF_INSTALLMENTS — оформить в рассрочку.
  • SBP — через систему быстрых платежей.
  • CARD_ON_DELIVERY — банковской картой при получении.
  • CASH_ON_DELIVERY — наличными при получении.

Параметры, вложенные в dates

Параметр

Тип

Значение

fromDate

Date

Ближайшая возможная дата доставки. Формат даты: ДД-ММ-ГГГГ. Дата должна быть не ранее текущей даты и не позднее 31 календарного дня от текущей даты.

toDate

Date

Самая поздняя дата доставки. Формат: ДД-ММ-ГГГГ. Дата должна быть не ранее даты, указанной в параметре fromDate, и не позднее 31 календарного дня от текущей даты. Если параметр toDate не указан, то единственно возможной датой доставки считается дата, указанная в параметре fromDate.

intervals

Описание

Список возможных дат и интервалов времени доставки в указанный день. В параметре можно указать до 5 интервалов для каждой даты. Параметр обязателен для курьерской доставки ("type": "DELIVERY"). Необходимо указывать вместе с параметрами toDate и fromDate.

Параметры, вложенные в intervals

Параметр

Тип

Значение

date

Date

Возможная дата доставки. Формат даты: ДД-ММ-ГГГГ.

fromTime

Time

Начало интервала времени доставки. Обязательный параметр. Формат времени: 24-часовой, ЧЧ:ММ. В качестве минут всегда должно быть указано 00 (исключение — 23:59). Максимальное значение: 21:00.

toTime

Time

Конец интервала времени доставки. Обязательный параметр. Формат времени: 24-часовой, ЧЧ:ММ. В качестве минут всегда должно быть указано 00 (исключение — 23:59). Максимальное значение: 23:59.

Параметры, вложенные в outlets

Параметр

Тип

Значение

code

String

Идентификатор пункта самовывоза, присвоенный магазином.

Если указан несуществующий идентификатор, такой пункт самовывоза не выводится покупателю при оформлении заказа.

Описание ошибок

Магазин может вернуть следующие статусы ответов:

Описание

Пояснение:

Ошибка 400 Bad Request

Если магазин считает запрос, поступающий от Маркета, некорректным, магазин должен вернуть статус ответа 400 с описанием причины ошибки в теле ответа. Такие ответы будут анализироваться на предмет нарушений и недоработок API со стороны Маркета.

Ошибка 500 Internal Server Error

В случае технической ошибки на стороне магазина он должен вернуть статус ответа 500. Магазины с большим количеством таких ответов могут быть отключены от Маркета.

Примеры

Запрос

{
  "cart":
  {
    "businessId": 8085591,
    "currency": "RUR",
    "delivery":
    {
      "region":
      {
        "id": 213,
        "name": "Москва",
        "type": "CITY",
        "parent":
        {
          "id": 1,
          "name": "Москва и Московская область",
          "type": "SUBJECT_FEDERATION",
          "parent":
          {
            "id": 3,
            "name": "Центральный федеральный округ",
            "type": "COUNTRY_DISTRICT",
            "parent":
            {
              "id": 225,
              "name": "Россия",
              "type": "COUNTRY"
            }
          }
        }
      }
    },
    "items":
    [
      {
        "feedId": 12345,
        "offerId": "4609283881",
        "count": 3,
        "warehouseId": 12345,
        "partnerWarehouseId": "67890"
      },
      {
        "feedId": 12346,
        "offerId": "4607632101",
        "count": 1,
        "warehouseId": 12345,
        "partnerWarehouseId": "67890"
      }
    ]
  }
}

Ответ

HTTP/1.1 200 OK
...

{
  "cart":
  {
    "items":
    [
      {
        "feedId": 12345,
        "offerId": "4609283881",
        "count": 3
      },
      {
        "feedId": 12346,
        "offerId": "4607632101",
        "count": 1
      }
    ]
  }
}

Запрос

{
  "cart":
  {
    "businessId": 8085591,
    "currency": "RUR",
    "deliveryCurrency": "RUR",
    "delivery":
    {
      "region":
      {
        "id": 213,
        "name": "Москва",
        "type": "CITY",
        "parent":
        {
          "id": 1,
          "name": "Москва и Московская область",
          "type": "SUBJECT_FEDERATION",
          "parent":
          {
            "id": 3,
            "name": "Центральный федеральный округ",
            "type": "COUNTRY_DISTRICT",
            "parent":
            {
              "id": 225,
              "name": "Россия",
              "type": "COUNTRY"
            }
          }
        }
      },
      "address":
      {
        "country": "Россия",
        "city": "Москва",
        "subway": "Проспект Вернадского",
        "street": "Ленинский проспект",
        "house": "90",
        "floor": "6"
      }
    },
    "items":
    [
      {
        "feedId": 12345,
        "offerId": "4609283881",
        "offerName": "Чайник электрический 100 W",
        "feedCategoryId": "35",
        "fulfilmentShopId": 1234567,
        "count": 1
      },
      {
        "feedId": 12346,
        "offerId": "4607632101",
        "offerName": "Тостер",
        "feedCategoryId": "35",
        "fulfilmentShopId": 1234567,
        "count": 1
      }
    ]
  }
}

Ответ

HTTP/1.1 200 OK
...

{
  "cart":
  {
    "deliveryCurrency": "RUR",
    "deliveryOptions":
    [
      {
        "id": "1",
        "price": 100,
        "serviceName": "DPD",
        "type": "DELIVERY",
        "dates":
        {
          "fromDate": "15-09-2020",
          "toDate": "17-09-2020",
          "intervals":
          [
            {
              "date": "15-09-2020",
              "fromTime": "09:00",
              "toTime": "21:00"
            },
            {
              "date": "16-09-2020",
              "fromTime": "09:00",
              "toTime": "21:00"
            },
            {
              "date": "17-09-2020",
              "fromTime": "09:00",
              "toTime": "21:00"
            }
          ]
        }
      },
      {
        "price": 0,
        "serviceName": "PickPoint",
        "type": "PICKUP",
        "dates":
        {
          "fromDate": "15-09-2020",
          "toDate": "18-09-2020"
        },
        "outlets":
        [
          {
            "code": "9"
          },
          {
            "code": "10"
          },
          {
            "code": "12"
          }
        ]
      },
      {
        "price": 0,
        "serviceName": "PickPoint",
        "type": "PICKUP",
        "dates":
        {
          "fromDate": "16-09-2020",
          "toDate": "19-09-2020"
        },
        "outlets":
        [
          {
            "code": "11"
          }
        ]
      }
    ],
    "items":
    [
      {
        "feedId": 12345,
        "offerId": "4609283881",
        "delivery": true,
        "count": 1,
        "sellerInn ": "0123456789"
      },
      {
        "feedId": 12346,
        "offerId": "4607632101",
        "delivery": true,
        "count": 1,
        "sellerInn ": "0123456789"
      }
    ],
    "paymentMethods":
    [
      "YANDEX",
      "CARD_ON_DELIVERY",
      "CASH_ON_DELIVERY",
      "TINKOFF_CREDIT",
      "TINKOFF_INSTALLMENTS",
      "SBP"
    ]
  }
}
Предыдущая
Отладка и проверки API
Следующая
Передача заказа и запрос на принятие заказа
В этой статье: