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

Первый шаг подключения VK Рекламы без правки конфигурации и без перезапуска клиента. Ничего не отправляет в сеть — возвращает инструкцию, которую нужно показать пользователю целиком: где в кабинете создать приложение и откуда скопировать client_id и client_secret. Полученную пару передайте в finish_login. Предупредите, что client_secret — это пароль от рекламного кабинета: он сохранится на диске только для владельца и нужен, чтобы продлевать токен.

Второй шаг подключения: обменивает client_id и client_secret из start_login на токен доступа (grant client_credentials), сохраняет всё в файл только для владельца (0600) и сразу проверяет живым запросом к VK Рекламе. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Токен живёт около суток и продлевается автоматически, поэтому повторно вызывать это не требуется: каждый вызов создаёт НОВЫЙ токен, а у VK не больше 5 активных токенов на пару client_id + пользователь. Ошибка invalid_client означает, что пара скопирована не полностью или относится к разным приложениям.

Удаляет сохранённые токен и данные приложения VK Рекламы с диска. Токен, заданный переменной окружения VK_ADS_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. На стороне VK токен остаётся активным до истечения срока: отозвать его можно запросом POST v2/oauth2/token/delete.json, но он удаляет ВСЕ токены этого пользователя для данного client_id, поэтому здесь не вызывается.

Возвращает информацию о текущем аккаунте VK Рекламы (user.json), включая additional_info.client_name. Позволяет убедиться, на какой аккаунт рекламодателя указывает токен.

Возвращает текущий баланс аккаунта VK Рекламы: доступные средства и валюту. Вызывает user.json с полем account, в котором лежит кошелёк (account.balance, account.currency). Показывает баланс того аккаунта, на который указывает токен (параметров нет). Важно: точное имя поля с балансом в v3/user.json на новой платформе ads.vk.com не подтверждено на живом кабинете (домен закрыт JS); схема следует объектной модели myTarget/VK Ads (v2/v3). Инструмент отдаёт СЫРОЙ ответ VK без изменений, поэтому вызывающая сторона может аккуратно прочитать account.balance независимо от точной формы ответа — проверить на первом живом аккаунте с доступом read_payments.

Возвращает текущие лимиты запросов VK Рекламы и их остаток (throttling.json) — чтобы не упереться в лимит.

Возвращает гео-регионы VK Рекламы (id, name, type), при необходимости отфильтрованные по подстроке названия. Id регионов нужны для гео-таргетинга группы объявлений.

Возвращает список ad_plan (верхнеуровневый объект кампании в VK Рекламе) с необязательной фильтрацией по id и статусу. Денежные поля (budget_limit, budget_limit_day, max_price) — в валюте аккаунта.

Создаёт кампанию (ad_plan). Денежные поля — в валюте аккаунта. Сложные и редкие поля передаются через extra (подмешиваются в тело запроса как есть).

Меняет у кампании название, бюджеты, предельную ставку или даты. Денежные поля — в валюте аккаунта. Для смены статуса — ad_plan_action.

Меняет статус кампаний по id: activate (status=active), stop (status=blocked) или delete (status=deleted).

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

Создаёт группу объявлений внутри кампании. Таргетинг задаётся в targetings (например, {"geo":{"regions":[188]},"age":{"age_list":[25,26]}}). Денежные поля — в валюте аккаунта. Остальные поля — через extra.

Меняет у группы объявлений название, бюджеты, предельную ставку, даты или таргетинг. Денежные поля — в валюте аккаунта. Для смены статуса — ad_group_action.

Меняет статус групп объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).

Возвращает список banner (объект объявления/креатива в VK Рекламе) с необязательной фильтрацией по id, родительской группе объявлений и статусу. moderation_status (pending/allowed/banned) и delivery объясняют, почему объявление показывается или не показывается.

Создаёт объявление внутри группы объявлений. Креатив ссылается на загруженные медиа через content, тексты объявления — в textblocks, ссылки — в urls. Эти структуры отправляются как есть; точная форма для каждого формата объявления — в документации VK Рекламы.

Меняет у объявления название, текстовые блоки или ссылки. Для смены статуса — banner_action. Структуры отправляются как есть.

Меняет статус объявлений по id: activate (status=active), stop (status=blocked) или delete (status=deleted).

Возвращает статистику по кампаниям (ad_plans), группам объявлений (ad_groups) или объявлениям (banners) из сервиса статистики VK Рекламы v3. По умолчанию группировка summary — одна сводная строка на объект за весь период; day/week/month нужны ТОЛЬКО для динамики по дням и вопросов про тренд (каждая добавляет по строке на объект за период). Ранжирование на стороне сервера — через sortBy (например, base.spent) и order; в ответе есть также total — сводка по ВСЕМ объектам за период (для вопросов «сколько всего» суммировать строки не нужно). Метрики лежат в base (shows, clicks, spent, ...); spent — в валюте аккаунта.

Универсальный запрос напрямую к любому эндпоинту API VK Рекламы (например, path "v2/ad_plans.json", method GET). Нужен для эндпоинтов, у которых нет отдельного инструмента. query уходит в строку запроса, body отправляется как JSON для POST. GET выполняется свободно; POST и DELETE — запись, для них нужен confirmWrite=true.