Установка рекомендованных ставок

Описание

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

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

При установке ставок возможно применение модификаторов к рекомендованным значениям этих ставок: относительного (задается в процентах) и абсолютного (задается в условных единицах). Если указаны одновременно оба модификатора, сначала применяется относительный, затем — абсолютный.

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

Внимание. Для использования этого метода необходимо, чтобы в личном кабинете в качестве источника информации о ставках был выбран вариант «Партнерский интерфейс и API».

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

URL ресурса:

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

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

Параметр

Тип

Значение

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

campaignId

Int64

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

position

Int32

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

При установке рекомендаций для ставки для карточки товара допустимые значения: от 1 до 10.

При установке рекомендаций для поиска Яндекса допустимые значения: от 1 до 9.

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

target

Enum

Тип ставки, для которой устанавливается рекомендованное значение:

  • MODEL-CARD — ставка для карточки товара.

  • SEARCH — общая ставка.

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

offset_pct

Double

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

offset

Double

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

max_bid

Double

Максимальное значение устанавливаемых ставок в условных единицах.

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

<set-recommended-request>
  <offers>
    <offer feed-id="{int64}" offer-id="{string}" offer-name="{string}" query="{string}"/>
    ...
  </offers>
</set-recommended-request>

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

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

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

Тип

Значение

set-recommended-request

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

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

offers

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

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

Параметры, вложенные в set-recommended-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.

query query String

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

Обязательный параметр, если в строке запроса передан входной параметр target=SEARCH.

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

Внимание.

Ставки на Яндекс.Маркете обновляются:

Поэтому, в зависимости от типа идентификации, не имеет смысла изменять значения ставок чаще чем раз в 3–6 часов либо раз в 30 минут соответственно.

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

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

<response>
  <status>{enum}</status>
  <result>
    <bids-set>
      <bid feed-id="{int64}" offer-id="{string}" offer-name="{string}" bid="{double}" error="{enum}"/>
      ...
    </bids-set>
  </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

bids-set bidsSet

Список установленных ставок.

Параметры, вложенные в bids-set

bid

Информация об установленной ставке.

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

Параметры, вложенные в bid / bidsSet

feed-id feedId Int64

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

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

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

offer-id offerId String

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

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

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

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

offer-name offerName String

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

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

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

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

bid bid Double

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

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

error error Enum

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

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

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

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

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

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

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

error

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

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

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

code code Enum

Код ошибки.

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

message message String

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

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

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

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

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

Описание

Пояснение

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

Ошибка 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 maxBid value: 'maxBid'

В параметре max_bid указано некорректные значение.

Проверьте корректность параметра max_bid.

Invalid position number: 'position'

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

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

Offer name should not be empty

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

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

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

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

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

Query should be specified

Если в строке запроса передан входной параметр target=SEARCH, для каждого предложения должен быть указан поисковой запрос query.

Укажите поисковой запрос.

Too many offers: 'offersCount'

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

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

Ошибка 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, а также устаревших PUT /campaigns/{campaignId}/bids и POST /campaigns/{campaignId}/bids/recommended действует групповое ресурсное ограничение. Ограничение вводится на суммарное количество предложений, по которым при помощи этих методов выставлены ставки или получены рекомендации.

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

Примечание.

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

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

Примеры

Запрос:

curl -i -H 'Content-Type: application/xml' -X PUT 'https://api.partner.market.yandex.ru/v2/campaigns/10001/auction/recommended/bids.xml?position=5&target=model-card'

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

-d '<set-recommended-request>
  <offers>
    <offer feed-id="30919" offer-id="239982"/>
    <offer feed-id="30919" offer-id="239983"/>
    <offer feed-id="30919" offer-id="239984"/>
  </offers>
</set-recommended-request>'

Ответ:

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

<response>
  <status>OK</status>
  <result>
    <bids-set>
      <bid feed-id="30919" offer-id="239982" bid="0.33"/>
      <bid feed-id="30919" offer-id="239983" bid="0.27"/>
      <bid feed-id="30919" offer-id="239984" error="OFFER_NOT_FOUND"/>
    </bids-set>
  </result>
</response>