add

Создает объявления.

Узнайте больше

Ограничения

Для работы с товарными объявлениями используется адрес https://api.direct.yandex.com/v501/.

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

Не допускается добавление объявлений в архивную кампанию.

Не более 1000 объявлений в одном вызове метода.

Ограничение на количество объявлений в группе для пользователя можно получить с помощью метода Clients.get или AgencyClients.get (элемент ADS_TOTAL_PER_ADGROUP массива Restrictions).

Запрос

Структура запроса в формате JSON:

{
  "method": "add",
  "params": { /* params */
    "Ads": [{  /* AdAddItem */
      "AdGroupId": (long), /* required */
      "TextAd": {  /* TextAdAdd */
        "Title": (string), /* required */
        "Title2": (string),
        "Text": (string), /* required */
        "Href": (string),
        "Mobile": ( "YES" | "NO" ), /* required */
        "DisplayUrlPath": (string),
        "VCardId": (long),
        "AdImageHash": (string),
        "SitelinkSetId": (long),
        "AdExtensionIds": [(long), ... ],
        "VideoExtension": {  /* VideoExtensionAddItem */
          "CreativeId": (long)
        },
        "PriceExtension": {  /* PriceExtensionAddItem */
          "Price": (long), /* required */
          "OldPrice": (long),
          "PriceQualifier": ( "FROM" | "UP_TO" | "NONE" ), /* required */
          "PriceCurrency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" | "UZS" ) /* required */
        },
        "TurboPageId": (long),
        "BusinessId": (long),
        "PreferVCardOverBusiness": ( "YES" | "NO" ),
        "ErirAdDescription" : (string)
      },
      "TextImageAd": {  /* TextImageAdAdd */
        "AdImageHash": (string), /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TurboPageId": (long)
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TurboPageId": (long)
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "TurboPageId": (long)
      },
      "CpmVideoAdBuilderAd": {  /* CpmVideoAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "TurboPageId": (long)
      },
      "ShoppingAd" : {
        "SitelinkSetId" : (long),
        "AdExtensionIds" : [ (long) ],
        "BusinessId" : (long),
        "FeedId" : (long) /* required */,
        "FeedFilterConditions" : [ {
          "Operand" : (string) /* required */,
          "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
          "Arguments" : [ (string) ] /* required */
        }, ... ],
        "TitleSources" : [ (string) ],
        "TextSources" : [ (string) ],
        "DefaultTexts" : [ (string) ] /* required */
      },
      "ListingAd" : {
        "SitelinkSetId" : (long),
        "AdExtensionIds" : [ (long) ],
        "BusinessId" : (long),
        "FeedId" : (long) /* required */,
        "FeedFilterConditions" : [ {
          "Operand" : (string) /* required */,
          "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
          "Arguments" : [ (string) ] /* required */
        }, ... ],
        "TitleSources" : [ (string) ],
        "TextSources" : [ (string) ],
        "DefaultTexts" : [ (string) ] /* required */
      }
    }, ... ] /* required */
  }
}

Структура params (для JSON) / AddRequest (для SOAP)

Параметр

Тип

Описание

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

Ads

array of AdAddItem

Объявления, которые требуется добавить.

Да

Структура AdAddItem

AdGroupId

long

Идентификатор группы, в которую добавляется объявление.

Да

TextAd

TextAdAdd

Параметры текстово-графического объявления. См. Тип объявления.

Либо TextAd, либо MobileAppAd, либо DynamicTextAd, либо TextImageAd, либо MobileAppImageAd, либо TextAdBuilderAd, либо MobileAppAdBuilderAd, либо MobileAppCpcVideoAdBuilderAd, либо CpcVideoAdBuilderAd, либо CpmBannerAdBuilderAd, либо CpmVideoAdBuilderAd, либо SmartAdBuilderAd

TextImageAd

TextImageAdAdd

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

TextAdBuilderAd

TextAdBuilderAdAdd

Параметры графического объявления, создаваемого на основе креатива (при добавлении в группу текстово-графических объявлений).

CpmBannerAdBuilderAd

CpmBannerAdBuilderAdAdd

Параметры медийного объявления.

CpmVideoAdBuilderAd

CpmVideoAdBuilderAdAdd

Параметры медийного видеообъявления (в кампании с типом «Медийная кампания»).

ShoppingAd

ShoppingAdAdd

Параметры товарного объявления.

ListingAd

ListingAdAdd

Параметры объявлений для страниц каталога.

Структура TextAdAdd

Title

string

Заголовок 1.

Не более 56 символов c учетом «узких». Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Да

Title2

string

Заголовок 2.

Не более 30 символов без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Нет

Text

string

Текст объявления.

Не более 81 символа без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Да

Mobile

YesNoEnum

Признак того, что объявление является мобильным: YES или NO. См. раздел Мобильные объявления помощи Директа.

Внимание

Параметр устарел, вне зависимости от переданного значения, будет использовано значение NO.

Да

Href

string

Ссылка на сайт, куда будет вести объявление. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Хотя бы один из параметров Href, TurboPageId, VCardId или BusinessId (могут присутствовать все).

TurboPageId

long

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

Внимание

Параметр устарел, переданное значение не будет сохранено.

VCardId

long

Идентификатор виртуальной визитки. Визитка должна принадлежать той же кампании, что и объявление.

Внимание

Параметр устарел, переданное значение не будет сохранено.

BusinessId

long

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

PreferVCardOverBusiness

YesNoEnum

Признак, который определяет приоритетность источника данных при показе объявления: YES — визитка, NO — профиль организации.

Внимание

Параметр устарел, вне зависимости от переданного значения, будет использовано значение NO.

Нет

ErirAdDescription

string

Описание объекта продвижения.

Нет

AdImageHash

string

Хэш изображения.

Для текстово-графических объявлений подходят только изображения с типом REGULAR и WIDE, см. Тип изображения.

Нет

SitelinkSetId

long

Идентификатор набора быстрых ссылок. Допускается только при наличии параметра Href или TurboPageId.

Нет

DisplayUrlPath

string

Отображаемая ссылка. Допускается только при наличии параметра Href. Не более 20 символов. В случае использования шаблона символы # не учитываются в длине.

Может содержать буквы, цифры, символы -, №, /, %, #. Запрещены пробел, символ _, двойные символы --, //.

См. раздел Отображаемая ссылка помощи Директа.

Нет

AdExtensionIds

array of long

Идентификаторы расширений. Не более 50 элементов в массиве.

Нет

VideoExtension

VideoExtensionAddItem

Видеодополнение.

Если параметр не указан и задана настройка ENABLE_VIDEO_EXTENSION_BY_DEFAULT со значением YES, видеодополнение формируется автоматически.

См. раздел Видеодополнения помощи Директа.

Нет

PriceExtension

PriceExtensionAddItem

Цена в объявлении.

Нет

Структура VideoExtensionAddItem

CreativeId

long

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

Получить идентификатор креатива можно с помощью метода Creatives.get.

Да

Структура PriceExtensionAddItem

Price

long

Цена товара или услуги, умноженная на 1 000  000. Целое число, кратное 10 000 (что соответствует цене с двумя знаками после запятой). Максимальное значение — 10 000 000 000 000 000.

Да

OldPrice

long

Старая цена товара или услуги, умноженная на 1 000  000. Целое число, кратное 10 000. Старая цена должна быть строго больше цены.

Нет

PriceQualifier

PriceQualifierEnum

Текстовое пояснение к цене:

  • FROM — «от».
  • UP_TO — «до».
  • NONE — нет пояснения.

Да

PriceCurrency

PriceCurrencyEnum

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

Да

Структура MobileAppAdFeatureItem

Feature

MobileAppFeatureEnum

Тип дополнения:

  • PRICE — цена;
  • ICON — иконка;
  • CUSTOMER_RATING — рейтинг;
  • RATINGS — количество оценок (отображается, только если включено отображение рейтинга).

Если тип дополнения отсутствует в массиве Features, дополнение не отображается.

Да

Enabled

YesNoEnum

Отображать ли дополнение в объявлении.

Примечание

  • Если дополнение не удалось загрузить из магазина приложений, для него допустимо значение YES, однако это дополнение не отображается при показе объявления.
  • Количество оценок отображается только вместе с рейтингом: если для типа CUSTOMER_RATING задано NO, а для RATINGS — YES, количество оценок не отображается.

Да

Структура TextImageAdAdd

AdImageHash

string

Хэш изображения.

Для графических объявлений подходят только изображения с типом FIXED_IMAGE, см. Тип изображения.

Да

ErirAdDescription

string

Описание объекта продвижения.

Нет

Href

string

Ссылка на сайт, куда будет вести объявление. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Хотя бы один из параметров Href и TurboPageId (могут присутствовать оба)

TurboPageId

long

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

Структура TextAdBuilderAdAdd

Creative

AdBuilderAdAddItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для графических объявлений помощи Директа.

Да

ErirAdDescription

string

Описание объекта продвижения.

Нет

Href

string

Ссылка на сайт, куда будет вести объявление. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Хотя бы один из параметров Href и TurboPageId (могут присутствовать оба)

TurboPageId

long

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

Структура CpmBannerAdBuilderAdAdd

Creative

AdBuilderAdAddItem

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

См. раздел Создание медийной кампании помощи Директа.

Да

ErirAdDescription

string

Описание объекта продвижения.

Нет

Href

string

Ссылка на сайт, куда будет вести объявление. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Хотя бы один из параметров Href и TurboPageId (могут присутствовать оба)

TurboPageId

long

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

TrackingPixels

ArrayOfString

Может содержать не более двух строк:

  • Пиксель Яндекс Аудиторий — см. раздел Пиксель помощи Яндекс Аудиторий.
  • Счетчик показов ADFOX. В счетчике показов обязательно должен быть макрос %random% или %aw_random%.

Длина каждой строки не более 1024 символов.

Нет

Структура CpmVideoAdBuilderAdAdd

Creative

AdBuilderAdAddItem

Креатив, созданный в конструкторе креативов.

См. раздел Видеореклама / Как запустить кампанию помощи Директа.

Да

ErirAdDescription

string

Описание объекта продвижения.

Нет

Href

string

Ссылка на сайт, куда будет вести объявление. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Хотя бы один из параметров Href и TurboPageId (могут присутствовать оба).

TurboPageId

long

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

TrackingPixels

ArrayOfString

Счетчик показов ADFOX. В счетчике показов обязательно должен быть макрос %random% или %aw_random%. Не более 1024 символов.

Нет

Структура AdBuilderAdAddItem

CreativeId

long

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

Получить идентификатор креатива можно с помощью метода Creatives.get.

Да

Структура ShoppingAdAdd

SitelinkSetId

long

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

Нет

AdExtensionIds

array of long

Идентификаторы расширений. Не более 50 элементов в массиве.

Нет

BusinessId

long

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

Нет

FeedId

long

Идентификатор фида, на основе которого требуется сгенерировать объявления.

Да

FeedFilterConditions

FeedFilterConditionsItem

Правила отбора товарных предложений. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON).

Товарное предложение отбирается для формирования объявлений, если оно удовлетворяет одновременно всем правилам отбора. Если параметр не задан, для формирования объявлений используются все товарные предложения из фида.

Нет

TitleSources

array of string

Названия полей фида, которые используются для формирования заголовков объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

TextSources

array of string

Названия полей фида, которые используются для формирования текстов объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

DefaultTexts

array of string

Тексты по умолчанию. Можно указать только одно значение.

Да

Структура ListingAdAdd

SitelinkSetId

long

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

Нет

AdExtensionIds

array of long

Идентификаторы расширений. Не более 50 элементов в массиве.

Нет

BusinessId

long

Идентификатор профиля организации на Яндексе.

Получить данные профилей организаций можно с помощью метода Businesses.get.

Профиль организации можно привязать к объявлению, только если для него в параметре IsPublished возвращается значение YES.

Примечание

Профиль организации доступен по ссылке https://yandex.ru/profile/<id_профиля>

Нет

FeedId

long

Идентификатор фида, на основе которого требуется сгенерировать объявления.

Да

FeedFilterConditions

FeedFilterConditionsItem

Правила отбора товарных предложений. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON).

Товарное предложение отбирается для формирования объявлений, если оно удовлетворяет одновременно всем правилам отбора. Если параметр не задан, для формирования объявлений используются все товарные предложения из фида.

Нет

TitleSources

array of string

Названия полей фида, которые используются для формирования заголовков объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

TextSources

array of string

Названия полей фида, которые используются для формирования текстов объявлений. Допустимые названия полей можно получить в методе feeds.get в поле TitleAndTextSources.

Нет

DefaultTexts

array of string

Тексты по умолчанию. Можно указать только одно значение.

Да

Структура FeedFilterConditionsItem

Operand

string

Параметр фида.

Да

Operator

StringConditionOperatorEnum

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

Да

Arguments

array of string

Массив строк, с которыми сравнивается операнд.

Да

Примечание

«Узкими» считаются символы !,.;:"

Ответ

Структура ответа в формате JSON:

{
  "result": { /* result */
    "AddResults": [{  /* ActionResult */
      "Id": (long),
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ]
    }, ... ]
  }
}

Параметр

Тип

Описание

Структура result (для JSON) / AddResponse (для SOAP)

AddResults

array of ActionResult

Результаты добавления объявлений.

Структура ActionResult

Id

long

Идентификатор созданного объявления. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.

Warnings

array of ExceptionNotification

Предупреждения, возникшие при выполнении операции.

Errors

array of ExceptionNotification

Ошибки, возникшие при выполнении операции.
Предыдущая
Ads: операции с объявлениями
Следующая
archive