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

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

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

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

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

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

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

Перечисляет рекламодателей, с которыми может работать токен: клиентов агентства (AgencyClients.get) и кабинеты в управлении из YANDEX_DIRECT_CLIENTS. Логин из ответа передаётся в параметр client_login любого инструмента данных — так один сервер работает со всеми клиентами без перезапуска. accountType=agency — токен агентства: без client_login (и без YANDEX_DIRECT_LOGIN) инструменты видят собственный аккаунт агентства, где обычно нет кампаний. accountType=advertiser — обычный аккаунт: API не перечисляет кабинеты, где этот логин представитель, поэтому список есть только если его задали в YANDEX_DIRECT_CLIENTS. Архивные клиенты агентства по умолчанию скрыты. Сводка по всем клиентам сразу (баланс, кампании) — clients_overview.

Сводка по всем клиентам агентства и кабинетам в управлении за один вызов — для вопросов вроде «что у меня по аккаунтам в управлении»: по каждому клиенту баланс общего счёта и число кампаний по состояниям (on — идут или могут идти, suspended — остановлены пользователем, off — не идут по другой причине, ended) и статусам модерации (moderation, rejected, draft). Архивные кампании не считаются. Клиенты — из list_clients, либо явный список logins. Ошибка по одному клиенту (нет доступа, нет общего счёта) не прерывает остальных и попадает в его строку. С параметром stats добавляет показы, клики и расход (с НДС, в валюте клиента) за период — по одному отчёту Reports на клиента, строго по очереди: Яндекс пускает примерно один отчёт в 10 секунд, так что 30 клиентов — около 5 минут; клиенты без неархивных кампаний не запрашиваются, а кто не уложился в 5 минут, помечается statsSkipped. Без stats ответ приходит за секунды — запрашивать расход, только когда вопрос про деньги или трафик. Не вызывать list_campaigns по каждому клиенту в цикле — эта сводка дешевле. Тратит баллы API каждого клиента: один запрос кампаний на клиента и один запрос баланса на 50 клиентов у агентства (у обычного аккаунта — на каждого).

Возвращает список кампаний с необязательными фильтрами по 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). API требует передавать режим бюджета (Mode) вместе с суммой, поэтому если dailyBudgetMode не задан, текущий режим кампании дочитывается через campaigns/get и сохраняется — смена суммы не меняет темп открутки.

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

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

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

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

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

Создаёт текстовое объявление (TextAd) в группе объявлений. Новые объявления создаются черновиками. TextAdAdd требует хотя бы одно из Href/TurboPageId/BusinessId — этот инструмент передаёт посадочную страницу через href (обязателен); объявление с BusinessId вместо ссылки создаётся через raw_request. Визитки (VCardId) Директ больше не поддерживает: контакты задаются организацией из Яндекс Бизнеса (BusinessId). Директ создаёт такие объявления комбинаторными (тип RESPONSIVE_AD), а Title2 объединяет с Title через «. », если вместе они короче 56 символов, иначе отбрасывает; о таких изменениях API сообщает предупреждениями.

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

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

Возвращает список ключевых фраз. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них. Bid и ContextBid отдаются в валюте аккаунта.

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

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

Задаёт ручные ставки на поиске и в сетях для ключевых фраз либо для всех фраз указанных групп объявлений или кампаний (keywordbids/set). Ставки — в валюте аккаунта. Тип цели один на весь вызов: все элементы bids используют только keywordId, только adGroupId или только campaignId; для целей разных типов нужны отдельные вызовы.

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

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

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

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

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

Добавляет корректировку ставок на кампанию или группу объявлений. Значения BidModifier — проценты по правилам API (например, 0–1300), а не деньги. API принимает в одном элементе BidModifiers только один тип корректировки, поэтому каждый переданный тип (mobile, desktop, demographics, retargeting, regional) уходит отдельным элементом в одном вызове bidmodifiers/add, в этом порядке. Каждая запись AddResults помечена полем Type (MOBILE_ADJUSTMENT, DESKTOP_ADJUSTMENT, DEMOGRAPHICS_ADJUSTMENT, RETARGETING_ADJUSTMENT, REGIONAL_ADJUSTMENT): типы создаются независимо, при частичной ошибке повторять только типы с Errors. Внутри одного типа (массивы demographics/retargeting/regional) API создаёт всё или ничего.

Меняет процент существующих корректировок (bidmodifiers/set) по id корректировки. BidModifierSetItem принимает только Id и BidModifier; включить/выключить корректировку через API нельзя (метод bidmodifiers/toggle устарел и не поддерживается) — чтобы отключить корректировку, удалить её через delete_bid_modifiers.

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

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

Создаёт набор быстрых ссылок (1–8 штук). Лимиты API: текст ссылки до 30 символов, описание до 60, URL до 1024 (с протоколом и доменом); длиннее API отвечает «Превышена допустимая длина», поэтому сокращать заранее. Наборы неизменяемы — чтобы поменять ссылки, нужно создать новый набор и переназначить его объявлению.

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

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

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

Удаляет уточнения по id (adextensions/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).