Рекомендации для карточки товара

Описание

POST /campaigns/{campaignId}/auction/recommendations/bids

Возвращает рекомендованные значения ставок на предложения для размещения этих предложений на карточках товаров Яндекс.Маркета.

Внимание.

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

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

URL ресурса:

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

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

Параметр

Тип

Значение

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

campaignId

Int64

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

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

target

Enum

Тип размещения, для которого необходимо получить рекомендации ставок:

  • MODEL-CARD — размещение на конкретной позиции на карточке товара Яндекс.Маркета.

Значение по умолчанию: MODEL-CARD.

positions

String

Список номеров позиций на карточке товара Яндекс.Маркета, для которых необходимо получить рекомендации ставок. Номера позиций указываются через запятую. Например:

positions=1,2,3

Допустимые значения: от 1 до 10.

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

region_id

Int64

Идентификатор региона, для которого необходимо получить рекомендованные ставки.

Если параметр не задан, в ответе выдаются рекомендации для домашнего региона магазина.

Структура тела POST-запроса:

<get-recommendations-request>
  <offers>
    <offer feed-id="{int64}" offer-id="{string}" offer-name="{string}"/>
    ...
  </offers>
</get-recommendations-request>

Параметры тела POST-запроса:

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

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

Тип

Значение

get-recommendations-request

Информация о предложениях, для которых нужно получить рекомендации.

Обязательный параметр, указывается только для формата XML.

offers

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

Обязательный параметр.

Параметры, вложенные в get-recommendations-request

offers

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

Обязательный параметр.

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

offer

Предложение.

Обязательный параметр, указывается только для формата XML.

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

feed-id feedId Int64

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

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

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

offer-id offerId String

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

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

Взаимоисключающий с параметром offer-name.

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

offer-name offerName String

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

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

Взаимоисключающий с параметром offer-id.

Максимальная длина: 512 символов.

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

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

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

<response>
  <status>{enum}</status>
  <result>
    <recommendations>
      <offer feed-id="{int64}" offer-id="{string}" offer-name="{string}" bid="{double}" min-bid="{double}" dont-pull-up-bids="{boolean}" error="{enum}">
        <model-card current-pos-all="{int64}" current-pos-top="{int64}" top-offers-count="{int64}" error="{enum}">
          <pos-recommendations>
            <position pos="{int64}" bid="{double}" error="{enum}"/>
            ...
          </pos-recommendations>
        </model-card>
      </offer>
      ...
    </recommendations>
  </result>
  <errors>
    <error code="{enum}" message="{string}"/>
    ...
  </errors>
</response>

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

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

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

Тип

Значение

response

Ответ.

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

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

status status Enum

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

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

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

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

result result

Результат выполнения запроса.

Выводится, если status="OK".

errors errors

Список ошибок при выполнении запроса.

Выводится, если status="ERROR".

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

recommendations recommendations

Список рекомендаций.

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

offer

Рекомендация ставок для предложения.

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

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

feed-id feedId Int64

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

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

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

offer-id offerId String

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

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

Взаимоисключающий с параметром offer-name.

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

offer-name offerName String

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

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

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

bid bid Double

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

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

min-bid minBid Double

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

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

dont-pull-up-bids dontPullUpBids Boolean

Запрет на автоматическое повышение ставки bid до минимальной:

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

Подробнее см. в разделе Минимальная стоимость клика Помощи Яндекс.Маркета.

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

error error Enum

Описание произошедшей ошибки. Параметр выводится только в случае возникновения ошибки.

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

  • OFFER_NOT_FOUND — предложение не опубликовано.

  • OFFER_NOT_MATCHED — предложение не соотнесено с карточкой товара Яндекс.Маркета.

  • SEARCH_TIMEOUT — по техническим причинам рекомендации для данного предложения временно недоступны.

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

model-card modelCard

Рекомендация ставки bid для размещения на карточке товара Яндекс.Маркета.

Ставка bid влияет на ранжирование предложений на карточке модели Яндекс.Маркета.

Параметры, вложенные в model-card / modelCard

current-pos-all currentPosAll Int64

Позиция предложения на первой странице раздела Цены карточки товара Яндекс.Маркета.

Если параметр не выдается или имеет значение 0 — предложение не попало на первую страницу раздела Цены.

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

current-pos-top currentPosTop Int64

Позиция предложения в блоке Топ на карточке товара Яндекс.Маркета.

Если параметр не выдается или имеет значение 0 — предложение не попало в блок Топ.

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

top-offers-count topOffersCount Int64

Количество предложений, попавших в блок Топ на карточке товара Яндекс.Маркета.

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

error error Enum

Описание произошедшей ошибки. Параметр выводится только в случае возникновения ошибки.

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

  • UNAVAILABLE — рекомендации по размеру ставки недоступны. Обратитесь в службу поддержки.

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

pos-recommendations posRecommendations

Рекомендации ставки для разных позиций на карточке товара.

Параметры, вложенные в pos-recommendations

position

Рекомендация ставки для размещения на определенной позиции на карточке товара.

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

Параметры, вложенные в position / posRecommendations

pos pos Int64

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

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

bid bid Double

Рекомендованная ставка для достижения указанной позиции на карточке товара Яндекс.Маркета, в условных единицах.

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

error error Enum

Код произошедшей ошибки. Параметр выводится только в случае возникновения ошибки.

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

  • UNREACHABLE — позиция недостижима.

  • UNKNOWN — произошла неизвестная ошибка. Обратитесь в службу поддержки.

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

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

error

Информация об ошибке.

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

Параметры, вложенные в error / errors

code code Enum

Код ошибки.

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

message message String

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

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

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

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

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

Описание

Пояснение

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

Ошибка 206 Partial Content

Запрос выполнен частично. По техническим причинам рекомендации для части предложений временно недоступны.

Выполните повторный запрос по тем предложениям offer, у которых error="SEARCH_TIMEOUT".

Ошибка 400 Bad Request

Current offer identification type is: 'idType'

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

Идентифицируйте ставки в соответствии с установленным типом. При необходимости смените тип идентификации в личном кабинете.

Either offer-id or offer-name should be specified

В теле запроса указаны взаимоисключающие параметры offer-id и offer-name.

Укажите в теле запроса только один из параметров: offer-id или offer-name.

Укажите параметр offer-id, если вы используете тип идентификации товаров по идентификатору предложения.

Укажите параметр offer-name, если вы выбрали тип идентификации товаров по названию предложения.

Feed should be specified

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

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

Invalid position number: 'position'

Номер позиции, указанный в запросе, не число.

Проверьте корректность указанных в запросе позиций.

Offer name should not be empty

Название предложения, переданное в теле запроса, не должно быть пустым.

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

Offer name should be 512 characters at most

Название предложения, переданное в теле запроса, не должно быть длиннее 512 символов.

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

Position number should be in 'availablePositions': 'position'

Номер позиции должен быть из списка допустимых значений availablePositions.

Проверьте корректность указанных в запросе позиций.

Position number should be positive and not greater than 'maxPosition': 'position'

Номер позиции, указанный в запросе, должен быть положительным числом и не превышать значение maxPosition.

Проверьте корректность указанных в запросе позиций.

Too many offers: 'offersCount'

В запросе указано больше 500 предложений.

Уменьшите количество передаваемых предложений.

Too many positions specified

Количество позиций в параметре positions превышает максимальное количество позиций.

Уменьшите количество позиций в параметре positions.

Ошибка 403 Forbidden

Auction is not allowed for campaign 'campaignId'. Reason: SOURCE_NOT_WEB

В личном кабинете магазина campaignId в качестве источника информации о ставках указан источник, отличный от «Партнерский интерфейс и API».

Укажите в личном кабинете в качестве источника информации о ставках вариант «Партнерский интерфейс и API».

Ошибка 404 Not Found

Feed not found: 'feedId'

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

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

Ограничения

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

Для запросов PUT /campaigns/{campaignId/auction/bids, POST /campaigns/{campaignId}/auction/recommendations/bids, POST /campaigns/{campaignId}/bids/recommended/top/market-search и PUT /campaigns/{campaignId}/auction/recommendations/bids действует групповое ресурсное ограничение. Ограничение вводится на суммарное количество предложений, по которым при помощи этих методов выставлены ставки или получены рекомендации.

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

Примечание.

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

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

Примеры

Запрос:

curl -i -H 'Content-Type: application/xml' -X POST 'https://api.partner.market.yandex.ru/v2/campaigns/10001/auction/recommendations/bids.xml?target=MODEL-CARD'

Тело POST-запроса:

-d '<get-recommendations-request>
  <offers>
    <offer feed-id="3456" offer-id="12"/>
  </offers>
</get-recommendations-request>'

Ответ:

HTTP/1.1 200 OK
Date: Wed, 19 Dec 2018 11:13:44 GMT
Content-Type: application/xml;charset=utf-8
...

<response>
  <status>OK</status>
  <result>
    <recommendations>
      <offer feed-id="3456" offer-id="12" bid="0.32" min-bid="0.32" dont-pull-up-bids="false">
        <model-card current-pos-all="4" current-pos-top="4">
          <pos-recommendations>
            <position pos="1" bid="1.26"/>
            <position pos="2" bid="1.03"/>
            <position pos="3" bid="0.86"/>
            <position pos="4" bid="0.62"/>
            <position pos="5" bid="0.51"/>
            <position pos="6" bid="0.50"/>
            <position pos="7" bid="0.46"/>
            <position pos="8" bid="0.41"/>
            <position pos="9" bid="0.36"/>
            <position pos="10" bid="0.26"/>
          </pos-recommendations>
        </model-card>
      </offer>
    </recommendations>
  </result>
</response>