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

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

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

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

```bash
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://mcp-everything.ru/integrations/yandex-direct/scenarios/vygruzit-statistiku-reklamnyh-kampaniy.md)
- [Получить список кампаний](https://mcp-everything.ru/integrations/yandex-direct/scenarios/poluchit-spisok-kampaniy.md)
- [Выгрузить ключевые фразы кампании](https://mcp-everything.ru/integrations/yandex-direct/scenarios/vygruzit-klyuchevye-frazy-kampanii.md)

---

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