Изменения кабинета

Предпросмотр и подтверждение

Для создания рекламных объектов, правки, смены статусов, бюджетов, ставок и записи данных маркировки используйте такой порядок:

1. Агент вызывает инструмент без confirm=true.
2. Плагин проверяет параметры и возвращает confirm_required с preview, если действие допустимо. При ошибке параметров предпросмотра может не быть.
3. Агент показывает человеку объекты, суммы и последствия изменения.
4. После согласия человека агент повторяет вызов с confirm=true.
5. Проверьте фактический результат, предупреждения и при необходимости кабинет VK.

Плагин не хранит отдельное разрешение на конкретный предпросмотр и не проверяет переписку с человеком. Технически вызов с confirm=true может быть выполнен без предыдущего предпросмотра, поэтому агент должен соблюдать этот порядок.

Предпросмотр не означает отсутствия сетевых запросов. Плагин может читать кабинет и обновлять токены VK. При подготовке кампании со ссылкой, создании или правке объявления ссылка проверяется и регистрируется в VK до проверки confirm. Загрузка изображения вообще не требует подтверждения.

Бюджеты и ставки

Все суммы передаются числами в валюте подключённого кабинета. Валюту и budget_limit_step получите через vkads_get_account; не подставляйте фиксированный шаг из примера другого кабинета.

vkads_set_budget принимает уровень campaign или adgroup, номер объекта в id и бюджет:

• budget_limit_day — дневной;
• budget_limit — общий.

Задавайте один положительный лимит. Два положительных бюджета одновременно отвергаются с both_budgets. Положительный бюджет должен быть кратен шагу кабинета: при bad_step ответ содержит ближайшие допустимые суммы.

Превышение Предела изменения бюджета и ставки, % приводит к change_too_large. Отдельно согласованную сумму можно передать с force=true, сохранив confirm=true. Если старой положительной суммы нет, процентный предел не проверяется.

Значение бюджета 0 код допускает как запрос на снятие ограничения и сопровождает предупреждением: фактическое поведение API для такого запроса не подтверждено. Не считайте его гарантированным способом снять лимит; проверяйте after и кабинет VK.

vkads_set_bid получает номер группы в adgroup_id и положительную сумму в price. При пустом режиме стратегии или fixed меняется ручная ставка price, при другом режиме — предельная цена max_price. Если бюджет задан на уровне кампании, предельная цена может изменяться на кампании и затронуть все её группы. Перед подтверждением смотрите field, applies_to и note в предпросмотре.

В примере агент показывает увеличение бюджета с 2000 до 3000 рублей и проверяет сумму после согласия.

Создание кампании и группы

1. Через vkads_get_packages подберите доступный пакет и соответствующую цель objective.
2. Через vkads_get_account проверьте валюту и шаг бюджета.
3. При необходимости найдите регионы и интересы через vkads_find_regions и vkads_get_interests, сегменты — через vkads_get_audiences.
4. Подготовьте vkads_create_campaign: name, objective, package_id и один положительный бюджет. Необязательное group_name по умолчанию совпадает с названием кампании.
5. Согласуйте предпросмотр и подтвердите создание.

Создаётся кампания с одной группой и без объявлений. Обе сущности запрашиваются со статусом blocked. В существующую кампанию группу добавляет vkads_create_adgroup: нужны campaign_id и name; пакет по умолчанию берётся у кампании.

Для новой группы можно задать ставку price либо предельную цену max_price и стратегию autobidding_mode. При max_price код требует явно указанную автостратегию, отличную от fixed. Первоначальные суммы должны быть положительными; процентный предел изменения старого бюджета к созданию не применяется.

Таргетинг

Без таргетинга при создании кампании код предупреждает о значениях VK по умолчанию — всей аудитории. Проверяйте состав аудитории в предпросмотре.

Картинки и объявления

vkads_upload_image принимает либо image_url, либо image_base64. Поддерживаются JPG и PNG до 5 МБ. По ссылке нужен прямой публичный адрес HTTP/HTTPS: редиректы и внутренние адреса не поддерживаются. Плагин проверяет файл и определяет размеры; автоматически приводить его к нужному формату он не умеет.

Номер загруженного изображения используется в аргументе, соответствующем размеру: image_600x600, image_1080x607, image_1080x1350; логотип — icon_256x256. Загрузка картинки не запускает рекламу и выполняется без confirm.

Для vkads_create_ad нужны группа adgroup_id, ссылка url, заголовок title, короткий текст text и изображение. Подготовьте изображения формата выбранного пакета; требования VK могут быть строже проверки плагина.

Название объявления name необязательно: по умолчанию берётся заголовок. Объявление создаётся со статусом blocked. Проверьте результат через vkads_get_ads, включая статус модерации.

Маркировка

Если VK отвечает ord_data_required, вызовите vkads_get_ord_profile. Подтверждённый профиль «VK для бизнеса» не гарантирует заполненности названия рекламодателя в данных ОРД.

vkads_set_ord_profile может изменить name, site и phone, с предпросмотром и confirm=true. ИНН инструмент не меняет. Значения должен сообщить сам рекламодатель; агенту не следует придумывать их или автоматически брать из названия профиля.

Правка и запуск

• vkads_update_campaign: название name и даты date_start, date_end в формате YYYY-MM-DD.
• vkads_update_adgroup: название и таргетинг. Переданные части таргетинга заменяются целиком; остальные сохраняются. Плагин предупреждает, что изменение таргетинга работающей группы сбрасывает обучение.
• vkads_update_ad: название, тексты, ссылка, картинки. Передавайте только изменяемые поля; плагин предупреждает о повторной модерации и возможной приостановке показов. После правки проверьте также сохранность остальных текстов и картинок в VK.

Все три инструмента правки получают номер изменяемого объекта в id. Деньги и статусы меняются отдельными инструментами.

Запуск и остановка доступны на каждом уровне: vkads_set_campaign_status, vkads_set_adgroup_status, vkads_set_ad_status. Статус active означает запрос запуска, blocked — остановки; максимум 20 номеров за вызов. Для показов учитывается состояние кампании, группы и объявления, а также модерация и ограничения VK. Установка active сама по себе не гарантирует немедленных показов.

Удаление

vkads_delete_objects получает level, список ids до 20 номеров и требует одновременно:

• confirm=true;
• confirm_text вида удалить N, где N — число уникальных номеров в ids, включая не найденные или уже удалённые.

Например, для списка из трёх разных номеров контрольная фраза — удалить 3. Без подтверждения вернётся предпросмотр; при неверной фразе с confirm=true — confirm_text_mismatch. Удаление необратимо. Для временной остановки используйте статус blocked.

Проверка результата и ошибки связи

Для массовых операций смотрите результат каждого объекта: часть изменений может выполниться, а часть — завершиться ошибкой. После изменения сумм проверяйте after и warnings.

При сетевом сбое или ошибке сервера во время записи неизвестно, применилось ли действие. Плагин не повторяет POST автоматически по этим причинам. Перед повторным созданием или другим изменением перечитайте кабинет, чтобы не создать дубликат и не повторить уже выполненное действие.