Yandex Direct

echo

Ищет id регионов для таргетинга (те самые regionIds, которые нужны create_ad_group). Фильтр — подстрока названия; количество результатов ограничено limit.

Возвращает справочники Яндекс Директа (валюты, часовые пояса, константы, категории объявлений, …). GeoRegions может быть очень большим — для поиска регионов лучше get_regions.

Возвращает список ключевых фраз с фильтром по кампании, группе объявлений или id. Bid и ContextBid отдаются в валюте аккаунта.

Добавляет ключевые фразы в группу объявлений, при необходимости — со ставками для поиска и сетей.

Выполняет действие над ключевыми фразами по id: suspend, resume или delete.

Задаёт ручные ставки на поиске и в сетях для ключевых фраз либо для всех фраз указанных групп объявлений или кампаний (keywordbids/set). Ставки — в валюте аккаунта.

Читает корректировки ставок (мобильные, десктоп, демография, ретаргетинг, регионы, видео) для кампаний или групп объявлений. BidModifier — это процент, а не деньги.

Добавляет корректировку ставок на кампанию или группу объявлений. Значения BidModifier — проценты по правилам API (например, 0–1300), а не деньги.

Меняет процент существующих корректировок (bidmodifiers/set) по id корректировки.

Удаляет корректировки ставок по id (bidmodifiers/delete).

Возвращает список групп объявлений. Нужно передать campaignIds и/или ids — API Яндекс Директа требует хотя бы один критерий отбора.

Создаёт группу объявлений в кампании с заданными регионами показа.

Обновляет название и/или регионы показа группы объявлений (adgroups/update).

Удаляет группы объявлений по id (adgroups/delete). Вместе с группой удаляются её объявления и ключевые фразы; отменить это нельзя.

Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа. По умолчанию отчёт АГРЕГИРОВАН за весь период (одна строка на объект) — добавлять \"Date\" в fieldNames только для динамики по дням или вопросов о трендах. ALL_TIME без фильтра по кампаниям отклоняется для отчётов SEARCH_QUERY/CRITERIA: нужно передать campaignIds или ограниченный период. SEARCH_QUERY_PERFORMANCE_REPORT возвращает не сырые строки, а ВЫЧИСЛЕННУЮ СВОДКУ (итоги по ВСЕМ строкам + детализация top-N + свёртка хвоста + количество строк без кликов и без конверсий); её форму задают sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly, а для подсчётов по конверсиям нужно добавить Conversions в fieldNames. Остальные типы отчётов возвращают строки, разделённые табуляцией (без заголовка).

Возвращает данные текущего аккаунта рекламодателя (логин, валюта, тип, страна) через сервис `clients` Яндекс Директа.

Возвращает баланс общего счёта и финансовые поля (Amount, AmountAvailableForTransfer, Currency, Discount, AccountID) через устаревший сервис AccountManagement Live v4 — единственный API Яндекс Директа, который отдаёт баланс (в v5 финансового метода нет). Amount — строка в ВАЛЮТЕ АККАУНТА (не в микроединицах); отрицательный Amount означает задолженность. По умолчанию — собственный аккаунт токена; чтобы получить конкретные общие счета, передать logins.

Возвращает сегодняшнюю квоту баллов API (потрачено / осталось / лимит) из заголовка Units — чтобы не упереться в дневной лимит.

Возвращает список кампаний с необязательными фильтрами по id, типу, состоянию и статусу. Денежные поля (DailyBudget.Amount и Funds общего счёта — Sum, Balance, SumAvailableForTransfer, Spend) отдаются в валюте аккаунта.

Создаёт кампанию TextCampaign (текстово-графические объявления). Без biddingStrategy применяются ручные ставки на поиске с отключёнными сетями (Search HIGHEST_POSITION, Network SERVING_OFF); чтобы включить автостратегию или сети, передать biddingStrategy целиком — {Search, Network}.

Выполняет действие над кампаниями по id: suspend, resume, archive, unarchive или delete.

Обновляет название, дату окончания и/или дневной бюджет кампании (campaigns/update).

Возвращает список объявлений с необязательными фильтрами по кампании, группе, id, состоянию и статусу.

Создаёт текстовое объявление (TextAd) в группе объявлений. Новые объявления создаются черновиками.

Выполняет действие над объявлениями по id: moderate, suspend, resume, archive, unarchive или delete.

Обновляет заголовок, текст или посадочную страницу текстового объявления (ads/update). Правка активного объявления отправляет его на повторную модерацию.

Показывает, подключён ли Яндекс Директ: есть ли токен, откуда он взят (переменная окружения YANDEX_DIRECT_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Директа отвечают, что подключение не настроено.

Первый шаг подключения Яндекс Директа без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом, у которого есть доступ к нужному рекламному кабинету, подтвердить доступ и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.

Второй шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Директу. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.

Удаляет сохранённый токен Директа с диска. Токен, заданный переменной окружения YANDEX_DIRECT_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.

Читает наборы быстрых ссылок по id. API требует id наборов — их можно взять из поля SitelinkSetId объявлений.

Создаёт набор быстрых ссылок (1–8 штук). Наборы неизменяемы — чтобы поменять ссылки, нужно создать новый набор и переназначить его объявлению.

Удаляет наборы быстрых ссылок по id (удалить можно только наборы, не привязанные ни к одному объявлению).

Возвращает список уточнений из библиотеки adextensions. Привязать уточнение к объявлению можно через сервис Ads.

Создаёт уточнения, до 25 символов каждое. Уточнения неизменяемы — чтобы поменять, нужно удалить и создать заново. Привязка к объявлениям — через сервис Ads.

Удаляет уточнения по id (adextensions/delete).

Читает виртуальные визитки по id. API требует id — их можно взять из поля VCardId объявлений.

Создаёт виртуальную визитку в кампании. Визитки неизменяемы — чтобы поменять, нужно удалить и создать заново.

Удаляет визитки по id (vcards/delete).

Возвращает список изображений из библиотеки изображений, ключ — хеш изображения. Новые изображения загружает upload_ad_image.

Читает видео из библиотеки видео по id (API требует id). Загрузка идёт через raw_request (advideos/add).

Возвращает список креативов (смарт-баннеры, HTML5) из библиотеки креативов.

Загружает изображение в библиотеку изображений (adimages/add) и возвращает его AdImageHash — этот хеш подставляется в поле AdImageHash текстово-графического объявления. Изображение передаётся публичным URL (сервер сам скачает и закодирует) или в base64 через imageData. Яндекс принимает JPG/PNG/GIF до 10 МБ; текстово-графическому объявлению нужна горизонтальная картинка (минимум 1080×607).

Универсальный запрос: вызывает напрямую любой сервис или метод API Яндекс Директа v5 (например service "bidmodifiers", method "get"). Нужен для сервисов, у которых нет отдельного инструмента. Деньги — в микроединицах (без конвертации). Методы чтения (get/has/check) выполняются свободно; любой другой метод считается записью и требует confirmWrite=true.