Yandex Direct V501 Operations

Яндекс Директ v501: операции

Использовать этот skill вместе с предметными skills аудита, ставок, фидов и атрибуции. Он задаёт технический контракт и не заменяет проверку текущей официальной документации: Директ развивается, а правила конкретного аккаунта имеют приоритет.

Безопасный порядок

1. Определить владельца, целевые кампании и запретные зоны аккаунта; не выводить токены, Client-Login, cookies и персональные данные.
2. Для первого прохода использовать только get и reports; фиксировать период, часовой пояс, задержку API и неполные дни.
3. Проверить тип кампании и использовать адрес, подходящий типу: для ЕПК — JSON API /json/v501/<service> и структуры UnifiedCampaign / UnifiedAdGroup.
4. Перед записью зафиксировать исходное состояние, лимиты, стратегию, гео, статус модерации и критерий отката. Явно запросить согласование на изменение кампаний, ставок, бюджетов, объявлений, фидов, целей, аудиторий или запуск показа.
5. После каждой записи немедленно перечитать изменённый объект и сверить ожидаемые поля. Успешный HTTP-ответ без ошибок не доказывает, что поле применилось.
6. Не заявлять о влиянии на экономику без надёжно связанной выручки/продаж; отдельно указывать ограничения измерений.

Выбор API и типы данных

• Для JSON использовать именно https://api.direct.yandex.com/json/v501/<service>; URL без /json/ предназначен для SOAP.
• Рассматривать v5 как совместимый контур только после подтверждения его применимости. Не создавать и не редактировать ЕПК через совместимый эндпоинт.
• Проверять Campaign.Type, AdGroup.Type и Ad.Type до выбора полей запроса. У ЕПК тип кампании — UNIFIED_CAMPAIGN; для неё применимы UnifiedCampaign и UnifiedAdGroup.
• Хранить и передавать все 64-битные ID как десятичные строки. Никогда не пропускать 16+ значные ID через JavaScript Number, Excel или незащищённую сериализацию.
• Суммы Директа передавать в микроединицах: рубли × 1 000 000. Для отчётов использовать returnMoneyInMicros: false и явно нормализовать десятичный разделитель TSV.

См. api-contracts.md для полей, статусов, отчётов и расширений.

Изменения кампаний и объявлений

• Гео у поисковой группы задавать в AdGroups.RegionIds; не переносить его в кампанию по аналогии с другими платформами.
• Для WB_MAXIMUM_CLICKS не считать пофразовые ставки рабочим механизмом управления: проверять предупреждения API и применять только согласованный BidCeiling или стратегию.
• При создании ЕПК-группы передавать UnifiedAdGroup.OfferRetargeting; явным образом проверять значения автотаргетинга — API может создать все категории по умолчанию.
• Учитывать жизненный цикл: добавление → отправка на модерацию → возобновление. State=OFF вместе с Status=MODERATION после resume — ожидаемое промежуточное состояние, а не повод повторно создавать объявления.
• Для комбинаторного объявления использовать структуру ResponsiveAd; не трактовать отсутствие Title2 как универсальную ошибку. Поля и результат редактирования зависят от типа объявления.
• При привязке быстрых ссылок и уточнений использовать фактическую схему чтения/записи для типа объявления; проверить привязку повторным Ads.get.
• Не использовать × в текстах, заголовках или ключах; применять русскую х. Не использовать / в минус-фразах без предварительной проверки валидности.

Отчёты, Метрика и Wordstat

• Повторять запрос Reports при HTTP 201/202 с паузой 4–5 секунд и ограниченным числом попыток. Пустой отчёт не доказывает отсутствие кампании: отдельно выполнить Campaigns.get.
• В Метрике использовать Authorization: OAuth <token>, а не Bearer. Для собственного UTM-трафика формировать фильтр явным перечислением кампаний, а не исключением «чужих»: пустой UTM тоже может проходить условие исключения.
• Сверять визиты Метрики с кликами Директа. Доходимость обычно оценивают как диапазон 85–95%; визитов больше кликов или менее 80% — диагностический сигнал, а не готовый бизнес-вывод.
• Проверять sampled и sample_share, посадочную страницу, UTM-терм/контент и разрез кампании. Не смешивать в одном выводе внешние кампании и UTM-кампании без явной связи.
• Wordstat Yandex Cloud требует отдельный API key. Расширять семантику малыми пакетами (2–3 фразы), затем проверять реальные поисковые запросы через SEARCH_QUERY_PERFORMANCE_REPORT; частотность сама по себе не подтверждает коммерческий спрос.

См. measurement.md для измерений и контроля качества и boundaries.md для UI-only объектов.

Контроль перед завершением

• Подтвердить, что были изменены только согласованные кампании и объекты.
• Сверить сохранённые стратегию, лимиты, расширенный геотаргетинг, счётчики, UTM, гео, расширения и статус модерации.
• Проверить отсутствие точных дублей фраз в конкурирующих группах, но не удалять их без понимания ассортиментной и коммерческой роли.
• Сохранить компактный отчёт: исходное/итоговое состояние, request ID, предупреждения, измерительные ограничения, откат и срок следующей проверки.
• Для PowerShell с кириллицей и JSON null использовать правила из windows-powershell.md.