Варианты товара

  1. Описание
  2. Входные данные
  3. Выходные данные
  4. Ошибки
  5. Примеры

Описание

GET /models/{modelId}/offers

Возвращает список вариантов товара на Маркете.

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

Чтобы узнать идентификатор товара modelId, можно найти товар с помощью запроса GET /search или открыть карточку товара на Маркете и посмотреть набор цифр в URL после названия товара.

Запрос является регионозависимым, его результаты возвращаются постранично.

URL ресурса:

https://api.content.market.yandex.ru/v3/affiliate/models/{modelId}/offers

Входные данные

Параметр

Тип

Значение

Обязательные
modelId String

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

Чтобы узнать идентификатор товара, можно найти товар с помощью запроса GET /search.
geo_id Int32

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

Список идентификаторов часто используемых регионов см. в разделе Регионозависимые запросы.

Необязательные
format Enum

Формат выходных данных:

  • json
  • xml

Значение по умолчанию: json.
fields String

Информация о вариантах товара, которую нужно получить (можно перечислить несколько значений через запятую):

  • OFFER_CHECKOUT_LINK — URL страниц Маркета, на которых пользователи могут оформить заказы с вариантами товара (параметр checkoutUrl). Возвращается, только если:

  • OFFER_DELIVERY — условия доставки вариантов товара (параметр delivery).

  • OFFER_PHOTO — все изображения вариантов товара (параметры photo и photos).
clid String

Идентификатор площадки.

Указанный идентификатор CLID добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&clid=1234567&.... По умолчанию используется идентификатор площадки, для которой выдавался авторизационный ключ.

Идентификатор можно узнать у персонального менеджера. Если вы являетесь партнером Яндекс.Маркета, идентификатор также можно найти в интерфейсе Яндекс.Дистрибуции, на странице Продукты.
vid String

Дополнительный идентификатор для ссылок — строка длиной до 150 символов только из латинских букв, цифр и специальных знаков: ., :, -, _.

Указанный идентификатор добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&vid=review&.... С его помощью можно отслеживать статистику по отдельной ссылке или сравнивать статистику по одинаковым ссылкам на разных страницах.

Подробнее см. в разделе Дополнительный идентификатор инструмента VID Справки партнерской сети Яндекс.Маркета.
touch Boolean

Должна ли страница оформления заказа, URL которой возвращается в выходном параметре checkoutUrl при значении OFFER_CHECKOUT_LINK входного параметра fields, быть адаптирована для мобильных устройств:

  • true — да.

  • false — нет, нужна версия для компьютеров.

Значение по умолчанию: false.

Если во входном параметре fields нет значения OFFER_CHECKOUT_LINK, параметр touch игнорируется.
page Int8

Номер страницы результатов: от 1 до 50.

Значение по умолчанию: 1.
count Int8

Количество результатов на странице: от 1 до 30.

Значение по умолчанию: 10.

Параметр

Тип

Значение

Обязательные
modelId String

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

Чтобы узнать идентификатор товара, можно найти товар с помощью запроса GET /search.
geo_id Int32

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

Список идентификаторов часто используемых регионов см. в разделе Регионозависимые запросы.

Необязательные
format Enum

Формат выходных данных:

  • json
  • xml

Значение по умолчанию: json.
fields String

Информация о вариантах товара, которую нужно получить (можно перечислить несколько значений через запятую):

  • OFFER_CHECKOUT_LINK — URL страниц Маркета, на которых пользователи могут оформить заказы с вариантами товара (параметр checkoutUrl). Возвращается, только если:

  • OFFER_DELIVERY — условия доставки вариантов товара (параметр delivery).

  • OFFER_PHOTO — все изображения вариантов товара (параметры photo и photos).
clid String

Идентификатор площадки.

Указанный идентификатор CLID добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&clid=1234567&.... По умолчанию используется идентификатор площадки, для которой выдавался авторизационный ключ.

Идентификатор можно узнать у персонального менеджера. Если вы являетесь партнером Яндекс.Маркета, идентификатор также можно найти в интерфейсе Яндекс.Дистрибуции, на странице Продукты.
vid String

Дополнительный идентификатор для ссылок — строка длиной до 150 символов только из латинских букв, цифр и специальных знаков: ., :, -, _.

Указанный идентификатор добавляется в URL, возвращаемые в ответе, в виде query-параметра: {url}&vid=review&.... С его помощью можно отслеживать статистику по отдельной ссылке или сравнивать статистику по одинаковым ссылкам на разных страницах.

Подробнее см. в разделе Дополнительный идентификатор инструмента VID Справки партнерской сети Яндекс.Маркета.
touch Boolean

Должна ли страница оформления заказа, URL которой возвращается в выходном параметре checkoutUrl при значении OFFER_CHECKOUT_LINK входного параметра fields, быть адаптирована для мобильных устройств:

  • true — да.

  • false — нет, нужна версия для компьютеров.

Значение по умолчанию: false.

Если во входном параметре fields нет значения OFFER_CHECKOUT_LINK, параметр touch игнорируется.
page Int8

Номер страницы результатов: от 1 до 50.

Значение по умолчанию: 1.
count Int8

Количество результатов на странице: от 1 до 30.

Значение по умолчанию: 10.

Выходные данные

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

{
  "status": "{enum}",
  "context": 
  {
    "id": "{string}",
    "time": "{date}",
    "link": "{string}",
    "marketUrl": "{string}",
    "region": 
    {
      "id": {int32},
      "name": "{string}",
      "type": "{enum}",
      "childCount": {int32},
      "country": 
      {
        "id": {int32},
        "name": "{string}",
        "type": "{enum}",
        "childCount": {int32}
      }
    },
    "currency": 
    {
      "id": "{string}",
      "name": "{string}"
    },
    "page":
    {
      "number": {int32},
      "count": {int32},
      "total": {int32},
      "last": {boolean},
      "totalItems": {int32}
    }
  },
  "offers":
  [
    {
      "sku": "{string}",
      "name": "{string}",
      "url": "{string}",
      "description": "{string}",
      "price":
      {
        "value": "{string}",
        "discount": "{string}",
        "base": "{string}"
      },
      "checkoutUrl": "{string}",
      "photo": 
      {
        "width": {int32},
        "height": {int32},
        "url": "{string}"
      },
      "photos":
      [
        {
          "width": {int32},
          "height": {int32},
          "url": "{string}"
        },
        ...
      ],
      "delivery":
      {
        "brief": "{string}",
        "price":
        {
          "value": "{string}",
          "base": "{string}"
        }
      }
    },
    ...
  ]
}

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

Параметр для формата JSON Параметр для формата XML Тип Описание
result

Ответ.

Параметр возвращается только для формата XML.
Параметры, вложенные в result
status status

Enum

Статус выполнения запроса:

  • OK — запрос выполнен успешно.

  • ERROR — произошла ошибка.

Для формата XML является атрибутом параметра result.
context context

Информация о запросе.
offers offers

Список вариантов товара.
Параметры, вложенные в context
id id

String

Идентификатор запроса.

Для формата XML является атрибутом параметра context.
time time

Date

Дата и время выполнения запроса.

Формат даты: ISO 8601 с миллисекундами и смещением относительно UTC. Например, 2017-11-21T00:00:00.000+03:00.

Для формата XML является атрибутом параметра context.
link link

String

URL страницы запроса на Маркете.

Для формата XML является атрибутом параметра context.
marketUrl marketUrl

String

URL Маркета.

Для формата XML является атрибутом параметра context.
region region

Регион, для которого возвращаются данные.
currency currency

Валюта, в которой указаны цены в ответе.
page page

Информация о страницах результатов.
Параметры, вложенные в region
id id

Int32

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

Для формата XML является атрибутом параметра region.
name name

String

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

Для формата XML является атрибутом параметра region.
type type

Enum

Тип региона:

  • CONTINENT — континент.

  • REGION — регион.

  • COUNTRY — страна.

  • COUNTRY_DISTRICT — федеральный округ.

  • SUBJECT_FEDERATION — субъект федерации.

  • CITY — город.

  • VILLAGE — село.

  • CITY_DISTRICT — район города.

  • METRO_STATION — станция метро.

  • SUBJECT_FEDERATION_DISTRICT — район субъекта федерации.

  • AIRPORT — аэропорт.

  • OVERSEAS_TERRITORY — отдельная территория какого‑либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • MONORAIL_STATION — станция монорельса.

  • RURAL_SETTLEMENT — сельское поселение.

  • OTHER — другой тип населенного пункта.

Для формата XML является атрибутом параметра region.
childCount childCount

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра region.
country country

Страна, в которой расположен регион.
Параметры, вложенные в country
id id

Int32

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

Для формата XML является атрибутом параметра country.
name name

String

Название страны.

Для формата XML является атрибутом параметра country.
type type

Enum

Тип региона:

  • COUNTRY — страна.

Для формата XML является атрибутом параметра country.
childCount childCount

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра country.
Параметры, вложенные в currency
id id

Enum

Код валюты:

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

String

Название валюты.
Параметры, вложенные в page
number number

Int32

Порядковый номер текущей страницы результатов.

Для формата XML является атрибутом параметра page.
count count

Int32

Количество товаров на текущей странице результатов.

Для формата XML является атрибутом параметра page.
total total

Int32

Количество страниц с результатами поиска.

Для формата XML является атрибутом параметра page.
last last

Boolean

Является ли текущая страница результатов последней:

  • true — да.
  • false — нет.

Если параметр не возвращается, страница не является последней.

Для формата XML является атрибутом параметра page.
totalItems totalItems

Int32

Общее количество найденных товаров.

Для формата XML является атрибутом параметра page.
Параметры, вложенные в offers
offer

Информация о варианте товара.
Параметры, вложенные в offers / offer
sku sku String

Идентификатор варианта товара (SKU на Маркете).

Для формата XML является атрибутом параметра offer.
name name

String

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

Для формата XML является атрибутом параметра offer.
url url

String

URL варианта товара на Маркете.

Для формата XML является атрибутом параметра offer.
description description

String

Описание варианта товара.
price price

Информация о цене варианта товара.
checkoutUrl checkoutUrl String

URL страницы Маркета, на которой пользователь может оформить заказ с вариантом товара.

Возвращается, только если:

Во входном параметре touch можно указать, на какую версию страницы должен вести URL: для мобильных устройств или для компьютеров.

Для формата XML является атрибутом параметра offer.
photo photo

Основное изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
photos photos

Все изображения варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
delivery delivery

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

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.
Параметры, вложенные в price (offer)
value value

String

Цена варианта товара. Если на вариант товара действует скидка, указана цена со скидкой.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
discount discount

String

Скидка на вариант товара в процентах.

Возвращается, только если на вариант товара действует скидка.

Для формата XML является атрибутом параметра price.
base base

String

Цена варианта товара без скидки.

Возвращается, только если на вариант товара действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметры, вложенные в photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
height height

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
url url

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в photos
photo

Изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
Параметры, вложенные в photos / photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
height height

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
url url

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в delivery
brief brief

String

Краткое описание условий доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
price price

Int32

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

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
Параметры, вложенные в price (delivery)
value value

String

Стоимость доставки. Если на доставку действует скидка, указана цена со скидкой.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
base base

String

Стоимость доставки без скидки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY и на доставку действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметр для формата JSON Параметр для формата XML Тип Описание
result

Ответ.

Параметр возвращается только для формата XML.
Параметры, вложенные в result
status status

Enum

Статус выполнения запроса:

  • OK — запрос выполнен успешно.

  • ERROR — произошла ошибка.

Для формата XML является атрибутом параметра result.
context context

Информация о запросе.
offers offers

Список вариантов товара.
Параметры, вложенные в context
id id

String

Идентификатор запроса.

Для формата XML является атрибутом параметра context.
time time

Date

Дата и время выполнения запроса.

Формат даты: ISO 8601 с миллисекундами и смещением относительно UTC. Например, 2017-11-21T00:00:00.000+03:00.

Для формата XML является атрибутом параметра context.
link link

String

URL страницы запроса на Маркете.

Для формата XML является атрибутом параметра context.
marketUrl marketUrl

String

URL Маркета.

Для формата XML является атрибутом параметра context.
region region

Регион, для которого возвращаются данные.
currency currency

Валюта, в которой указаны цены в ответе.
page page

Информация о страницах результатов.
Параметры, вложенные в region
id id

Int32

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

Для формата XML является атрибутом параметра region.
name name

String

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

Для формата XML является атрибутом параметра region.
type type

Enum

Тип региона:

  • CONTINENT — континент.

  • REGION — регион.

  • COUNTRY — страна.

  • COUNTRY_DISTRICT — федеральный округ.

  • SUBJECT_FEDERATION — субъект федерации.

  • CITY — город.

  • VILLAGE — село.

  • CITY_DISTRICT — район города.

  • METRO_STATION — станция метро.

  • SUBJECT_FEDERATION_DISTRICT — район субъекта федерации.

  • AIRPORT — аэропорт.

  • OVERSEAS_TERRITORY — отдельная территория какого‑либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • MONORAIL_STATION — станция монорельса.

  • RURAL_SETTLEMENT — сельское поселение.

  • OTHER — другой тип населенного пункта.

Для формата XML является атрибутом параметра region.
childCount childCount

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра region.
country country

Страна, в которой расположен регион.
Параметры, вложенные в country
id id

Int32

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

Для формата XML является атрибутом параметра country.
name name

String

Название страны.

Для формата XML является атрибутом параметра country.
type type

Enum

Тип региона:

  • COUNTRY — страна.

Для формата XML является атрибутом параметра country.
childCount childCount

Int32

Количество дочерних регионов.

Для формата XML является атрибутом параметра country.
Параметры, вложенные в currency
id id

Enum

Код валюты:

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

String

Название валюты.
Параметры, вложенные в page
number number

Int32

Порядковый номер текущей страницы результатов.

Для формата XML является атрибутом параметра page.
count count

Int32

Количество товаров на текущей странице результатов.

Для формата XML является атрибутом параметра page.
total total

Int32

Количество страниц с результатами поиска.

Для формата XML является атрибутом параметра page.
last last

Boolean

Является ли текущая страница результатов последней:

  • true — да.
  • false — нет.

Если параметр не возвращается, страница не является последней.

Для формата XML является атрибутом параметра page.
totalItems totalItems

Int32

Общее количество найденных товаров.

Для формата XML является атрибутом параметра page.
Параметры, вложенные в offers
offer

Информация о варианте товара.
Параметры, вложенные в offers / offer
sku sku String

Идентификатор варианта товара (SKU на Маркете).

Для формата XML является атрибутом параметра offer.
name name

String

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

Для формата XML является атрибутом параметра offer.
url url

String

URL варианта товара на Маркете.

Для формата XML является атрибутом параметра offer.
description description

String

Описание варианта товара.
price price

Информация о цене варианта товара.
checkoutUrl checkoutUrl String

URL страницы Маркета, на которой пользователь может оформить заказ с вариантом товара.

Возвращается, только если:

Во входном параметре touch можно указать, на какую версию страницы должен вести URL: для мобильных устройств или для компьютеров.

Для формата XML является атрибутом параметра offer.
photo photo

Основное изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
photos photos

Все изображения варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
delivery delivery

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

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.
Параметры, вложенные в price (offer)
value value

String

Цена варианта товара. Если на вариант товара действует скидка, указана цена со скидкой.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
discount discount

String

Скидка на вариант товара в процентах.

Возвращается, только если на вариант товара действует скидка.

Для формата XML является атрибутом параметра price.
base base

String

Цена варианта товара без скидки.

Возвращается, только если на вариант товара действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
Параметры, вложенные в photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
height height

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
url url

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в photos
photo

Изображение варианта товара.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.
Параметры, вложенные в photos / photo
width width

Int32

Ширина изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
height height

Int32

Высота изображения в пикселях.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
url url

String

URL изображения.

Возвращается, только если во входном параметре fields указано значение OFFER_PHOTO.

Для формата XML является атрибутом параметра photo.
Параметры, вложенные в delivery
brief brief

String

Краткое описание условий доставки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
price price

Int32

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

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Для формата XML является атрибутом параметра delivery.
Параметры, вложенные в price (delivery)
value value

String

Стоимость доставки. Если на доставку действует скидка, указана цена со скидкой.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.
base base

String

Стоимость доставки без скидки.

Возвращается, только если во входном параметре fields указано значение OFFER_DELIVERY и на доставку действует скидка.

Информация о валюте, в которой указана цена, возвращается в параметре currency.

Для формата XML является атрибутом параметра price.

Ошибки

В случае ошибки сервер возвращает HTTP‑код ответа и краткое описание ошибки.

Примеры

Запрос:

curl -i \
-H 'Authorization: <ключ>' \
'https://api.content.market.yandex.ru/v3/affiliate'\
'/models/1759344314/offers'\
'?geo_id=213'\
'&count=1'\
'&fields=OFFER_CHECKOUT_LINK'\
'&format=json'

Ответ:

HTTP/1.1 200 OK
Date: Fri, 31 Jul 2020 08:35:22 GMT
Content-Type: application/json;charset=utf-8
...

{
  "status": "OK",
  "context": 
  {
    "id": "1570801721736/b754d237142e471102ffa2c6a2940500",
    "time": "2020-07-31T11:35:22.294+03:00",
    "link": "https://market.yandex.ru/product/100427327870?offerid=3ejy9QijVqpMtXQWKFyDhg
            &hid=91491&pp=1930&mclid=1003&distr_type=7&clid=2310490",
    "marketUrl": "https://market.yandex.ru?pp=1930&mclid=1003&distr_type=7&clid=2310490",
    "region":
    {
      "id": 213,
      "name": "Москва",
      "type": "CITY",
      "childCount": 14,
      "country": 
      {
        "id": 225,
        "name": "Россия",
        "type": "COUNTRY",
        "childCount": 10
      }
    },
    "currency": 
    {
      "id": "RUR",
      "name": "руб."
    },
    "page":
    {
      "number": 1,
      "count": 1,
      "total": 242,
      "totalItems": 242
    }
  },
  "offers": 
  [
    {
      "sku": "100210864686",
      "name": "Смартфон Apple iPhone X 64GB серый космос (MQAC2RU/A)",
      "url": 
      "https://market.yandex.ru/product/smartfon-apple-iphone-x-64gb-seryi-kosmos-mqac2ru-a
        /100210864686?show-uid=15688930084968704733806001&pp=1930&mclid=1003
        &distr_type=7&clid=2310490",
      "price":
      {
        "value": "63990",
        "discount": "9.86054",
        "base": "70990"
      },
      "checkoutUrl":
        "https://market-click2.yandex.ru/redir/RKDYKz87q2rHJnSelAXt
        ?market-order-params=pp%3D1930%26mclid%3D1003%26distr_type%3D7%26clid%3D2310490%0A"
    }
  ]
}