API Яндекс Директа v5: Создать объявления в группе

Сценарий из mcp-everything. Актуально на 2026-10-24.

Массово завести текстово-графические объявления: под новые товары, акции, города.

Узнай ID группы объявлений (AdGroupId) — например, из существующих объявлений через Ads.get: POST /json/v5/ads с method = get и SelectionCriteria.CampaignIds.
Создай объявления: Ads.add — POST /json/v5/ads с method = add и params.Ads, где у каждого объявления AdGroupId и TextAd с Title, Text, Href и Mobile = NO.
Результат — в result.AddResults: для каждого объявления Id или Errors. Ошибка одного объявления не отменяет остальные — проверяй каждый элемент.
Ads.add стоит 20 баллов за вызов и 20 за каждое объявление — собирай объявления пачками, а не по одному.
Отлаживай на песочнице https://api-sandbox.direct.yandex.com — данные там удаляются через месяц после последнего обращения.

curl -X POST https://api.direct.yandex.com/json/v5/ads \
  -H "Authorization: Bearer $DIRECT_TOKEN" -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"method": "add", "params": {"Ads": [{
        "AdGroupId": 123456789,
        "TextAd": {"Title": "Кружки с логотипом от 50 шт", "Text": "Печать за 3 дня. Доставка по России.", "Href": "https://example.ru/mugs", "Mobile": "NO"}
      }]}}'

Базовые URL

Боевой: https://api.direct.yandex.com
Тестовый (песочница): https://api-sandbox.direct.yandex.com
Песочница (SOAP): https://api-sandbox.direct.yandex.com/v5/{service}

Авторизация

Тип: OAuth 2.0

OAuth 2.0: приложение регистрируется заранее, OAuth-токен пользователя Директа передаётся в заголовке Authorization: Bearer <токен>.

Методы сценария

POST /json/v5/ads — Ads.get: получение объявлений

Параметр	Где	Тип	Обяз.	Описание
`method`	body	string	да	get
`params.SelectionCriteria`	body	object	да	Нужен хотя бы один из Ids, AdGroupIds, CampaignIds
`params.SelectionCriteria.Ids`	body	array	нет	ID объявлений, до 10 000
`params.SelectionCriteria.AdGroupIds`	body	array	нет	ID групп, до 1000
`params.SelectionCriteria.CampaignIds`	body	array	нет	ID кампаний, до 10
`params.FieldNames`	body	array	да	Поля верхнего уровня
`params.TextAdFieldNames`	body	array	нет	Поля текстово-графического объявления
`params.Page`	body	object	нет	Limit и Offset

POST /json/v5/ads — Ads.add: создание объявлений

Тот же адрес, "method": "add". В result.AddResults[] для каждого объявления — Id или Errors.

Параметр	Где	Тип	Обяз.	Описание
`method`	body	string	да	add
`params.Ads`	body	array	да	Объявления
`params.Ads[].AdGroupId`	body	integer	да	ID группы объявлений
`params.Ads[].TextAd.Text`	body	string	нет	Текст текстово-графического объявления
`params.Ads[].TextAd.Title`	body	string	нет	Заголовок
`params.Ads[].TextAd.Href`	body	string	нет	Ссылка
`params.Ads[].TextAd.Mobile`	body	string	нет	Мобильное объявление: YES/NO

Нюансы

Все запросы — HTTPS POST; в теле JSON всегда есть method и, как правило, params. Поддерживается и SOAP/XML.
Ошибки уровня запроса приходят с HTTP 200 в объекте error (request_id, error_code, error_string, error_detail) — проверяйте наличие error, а не только статус.
Ошибки отдельных объектов при add/update возвращаются в Errors соответствующего элемента результата.
Заголовки ответа: RequestId (указывать в обращениях в поддержку), Units (списано/остаток/суточный лимит, например 10/20828/64000), Units-Used-Login.
Денежные значения в фильтрах Reports — целые числа, умноженные на 1 000 000.
Товарные объявления работают через адрес https://api.direct.yandex.com/v501/.
В песочнице действуют те же ограничения; данные удаляются через месяц после последнего обращения.

Другие сценарии

Если этого недостаточно — официальная документация: https://yandex.ru/dev/direct/doc/ru/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-direct.md