Предложения магазина

Описание

GET /campaigns/{campaignId}/offers

Позволяет фильтровать информацию о предложениях магазина, размещенных на Яндекс.Маркете, и искать предложения по заданному поисковому запросу.

Поиск предложений, размещенных на Яндекс.Маркете, работает по поисковому запросу аналогично поиску Яндекс.Маркета. Результаты возвращаются с использованием пейджера.

В ответе на запрос для каждого найденного предложения указывается URL и наименование этого предложения, его цена и валюта, в которой она указана, карточка модели Яндекс.Маркета, с которой соотнесено предложение, и аукционные ставки на него.

Примечание.

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

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

URL ресурса:

https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/offers.[format]

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

Параметр

Тип

Значение

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

campaignId

Int64

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

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

currency

Enum

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

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

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

  • KZT — казахстанский тенге.

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

  • UAH — украинская гривна.

Значение по умолчанию: используется национальная валюта магазина (национальная валюта страны происхождения магазина).

feedId

Int64

Идентификатор прайс-листа.

При задании данного параметра поиск предложений происходит среди предложений данного прайс-листа.

Параметр указывается, если задан параметр shopCategoryId и у магазина зарегистрировано более одного прайс-листа.

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

matched

Boolean

Фильтр по признаку соотнесения предложения и карточки модели.

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

  • 0 / FALSE / NO — поиск выполняется среди предложений, не соотнесенных ни с какой карточкой модели.

  • 1 / TRUE / YES — поиск выполняется среди предложений, соотнесенных с карточками моделей).

page

Int32

Номер страницы результатов, которую необходимо показать в ответе.

Если указан номер страницы, превышающий общее количество найденных страниц, выдаются результаты по последней странице.

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

Максимальное значение: 50.

pageSize

Int32

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

Значение по умолчанию и максимально возможное значение: 50.

query

String

Поисковый запрос.

Поддерживается язык запросов.

Значение по умолчанию: все предложения магазина, размещенные на Яндекс.Маркете.

shopCategoryId

String

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

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

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

Внимание. Ассортимент Яндекс.Маркета обновляется примерно раз в 3-6 часов. Значения ставок обновляются в течение 3 часов при идентификации товаров по названию и в течение 30 минут при идентификации товаров по ID. Поэтому не имеет смысла выполнять запрос по одним и тем же предложениям чаще, чем раз в час или раз в 30 минут соответственно.

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

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

<response>
  <offers>
    <offer bid="{double}" cbid="{double}" currency="{enum}" discount="{int32}" feed-id="{int64}" id="{string}" market-category-id="{int32}" model-id="{int32}" pre-discount-price="{float}" price="{float}" shop-category-id="{string}">
      <name>{string}</name>
      <url>{string}</url>
    </offer>
    ...
  </offers>
  <pager current-page="{int32}" from="{int32}" pages-count="{int32}" page-size="{int32}" to="{int32}" total="{int32}"/>
</response>

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

Параметр для формата XML

Параметр для формата JSON

Тип

Значение

response

Ответ.

Параметр выводится только для формата XML.

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

offers offers

Список найденных предложений.

pager pager

Сводка по результатам поиска.

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

offer

Информация о найденном предложении.

Параметр выводится только для формата XML.

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

bid bid Double

Примененная общая ставка, в условных единицах (может отличаться от выставленной магазином).

Общая ставка — ставка, которая действует при размещении предложения на поиске Яндекса, поиске Яндекс.Маркета, на сайтах партнеров Яндекс.Дистрибуции, а также для карточки модели товара, если ставка для карточки модели не указана отдельно.

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

cbid cbid Double

Примененная ставка для карточки модели, в условных единицах (может отличаться от выставленной магазином).

Ставка для карточки модели — ставка, действующая при размещении предложений на странице карточки модели на Яндекс.Маркете. Если ставка для карточки не указана, то на карточке модели действует общая ставка.

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

currency currency Enum

Валюта, в которой указана цена предложения.

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

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

  • KZT — казахстанский тенге.

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

  • UAH — украинская гривна.

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

discount discount Int32

Скидка на предложение, в %.

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

feed-id feedId Int64

Идентификатор прайс-листа, содержащего предложение.

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

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

id id String

Идентификатор предложения из прайс-листа.

Параметр выводится, если в прайс-листе задан уникальный идентификатор. Если в прайс-листе содержится несколько предложений с одинаковыми идентификаторами, параметр id указывается только для первого из них, для остальных параметры id и feed-id не выводятся.

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

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

market-category-id marketCategoryId Int32

Идентификатор категории предложения в дереве категорий Яндекс.Маркета.

Примечание. Информацию о работе с категориями можно получить в контентном API Яндекс.Маркета в разделе Категории.

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

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

model-id modelId Int32

Идентификатор модели Яндекс.Маркета, с которой соотнесено предложение.

Если предложение не соотнесено ни с какой карточкой модели, то параметр modelid содержит значение 0.

Примечание. Идентификатор модели присутствует в URL карточки модели в виде значения параметра product. Например: https://market.yandex.ru/product/13584121.

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

pre-discount-price preDiscountPrice Float

Цена предложения без скидки.

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

price price Float

Цена предложения.

До версии 2.0 партнерского API Яндекс.Маркета у параметра был тип — string.

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

shop-category-id shopCategoryId String

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

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

Параметр доступен начиная с версии 2.0 партнерского API Яндекс.Маркета.

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

name name String

Наименование предложения.

url url String

URL-адрес предложения на сайте магазина.

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

current-page currentPage Int32

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

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

from from Int32

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

Если ничего не найдено, значение параметра: 0.

До версии 2.0 партнерского API Яндекс.Маркета параметр в формате XML назывался from-offer, в формате JSON — fromOffer.

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

pages-count pagesCount Int32

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

Значение может увеличиваться по мере увеличения номера страницы. Конечное количество страниц будет достигнуто, когда значение параметра pages-count будет равно значению параметра current-page.

Если ничего не найдено, значение параметра: 0.

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

page-size pageSize Int32

Количество предложений, выводимых на текущей странице с результатами.

Если ничего не найдено, значение параметра: 0.

До версии 2.0 партнерского API Яндекс.Маркета параметр в формате XML назывался page-offers, в формате JSON — pageOffers.

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

to to Int32

Порядковый номер среди общих результатов поиска для последнего предложения на странице, выданной в ответе.

Если ничего не найдено, значение параметра: 0.

До версии 2.0 партнерского API Яндекс.Маркета параметр в формате XML назывался to-offer, в формате JSON — toOffer.

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

total total Int32

Общее количество найденных предложений магазина, размещенных на Яндекс.Маркете.

Значение может увеличиваться по мере увеличения номера страницы. Конечное количество найденных записей будет достигнуто, когда значение параметра total будет равно значению параметра to.

Если ничего не найдено, значение параметра: 0.

До версии 2.0 партнерского API Яндекс.Маркета параметр в формате XML назывался total-offers, в формате JSON — totalOffers.

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

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

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

Ошибки, содержащие характерные для данного метода краткие описания:

Описание

Пояснение

Способ возможного решения

Ошибка 400 Bad Request

Feed should be specified

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

Проверьте корректность передаваемых в запросе данных.

Page number is too big: 'pageNum'. Max page number is 'maxPageNum'

Указан слишком большой номер страницы.

Проверьте корректность передаваемого номера страницы.

Page number must be positive: 'page'

Номер страницы должен быть положительным числом.

Проверьте корректность передаваемого номера страницы.

Page size is too big: 'pageSize'. Max page size is 'maxPageSize'

Указан слишком большой размер страницы.

Проверьте корректность передаваемого размера страницы.

Page size must be positive: 'pageSize'

Размер страницы должен быть положительным числом.

Проверьте корректность передаваемого размера страницы.

Parameters 'feedId' and 'shopCategoryId' may not be used without each other

Параметры feedId и shopCategoryId не могут быть использованы отдельно друг от друга, за исключением когда у магазина один прайс-лист.

Проверьте корректность передаваемых в запросе данных.

Unsupported currency: 'currency'

Валюта не поддерживается.

Проверьте корректность значения валюты, передаваемой в запросе.

Ошибка 404 Not Found

Feed not found: 'feedId'

В path-параметре feedId передан некорректный идентификатор прайс-листа.

Проверьте корректность данных в запросе.

Ограничения

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

  • количество предложений.

Примечание.

Количество предложений считается по данным за последние семь дней (не включая сегодня).

Для новых магазинов, не разместивших еще предложения, ограничение равно 0. При размещении предложений этими магазинами ограничение пересчитывается только на следующий день.

Примеры

Пример запроса:

curl -i -H 'Content-Type: application/xml' -X GET 'https://api.partner.market.yandex.ru/v2/campaigns/21169538/offers.xml?query=Бинокли,%20Телескопы%20Nikon%20Aculon%20T11%208-24x25%20(черный)'

Пример ответа:

HTTP/1.1 200 OK
Date: Thu, 04 May 2017 00:42:42 GMT
Content-Type: application/xml;charset=utf-8
...

<response>
  <offers>
    <offer bid="1.16" cbid="0.11" currency="RUR" discount="17" feed-id="375216" id="1636288" market-category-id="226665" model-id="8350595" pre-discount-price="8990" price="7490" shop-category-id="129">
      <name>Бинокли, Телескопы Nikon Aculon T11 8-24x25 (черный)</name>
      <url>http://nuf-nuf.yandex.ru/product/21003</url>
    </offer>
  </offers>
  <pager current-page="1" from="1" pages-count="1" page-size="1" to="1" total="1"/>
</response>