API / интеграции

Рекламные API: когда нужны и как подключать безопасно

Обычный запуск можно сделать в интерфейсе. API полезен для повторяемых операций, отчётов и интеграций — когда понятны задача, доступы и последствия изменений.

Содержание статьи

Простыми словами

API позволяет программе читать или изменять рекламный кабинет без ручного открытия каждой страницы. Начинайте с чтения отчёта: ошибки массового редактирования могут повлиять на расход.

Термины простыми словами · 5
API
Правила обмена данными между программой и рекламной платформой.
OAuth
Предоставление разрешённого доступа без передачи пароля пользователя программе.
Developer token
Отдельное разрешение разработчика Google Ads API; оно не заменяет авторизацию клиента.
URL
Полный адрес страницы или файла, например https://example.com/catalog. При проверке ссылки важны также путь и параметры после знака вопроса.
ID
Идентификатор — код конкретного объекта. Например, номер счётчика или код товара. При настройке нужно брать ID нужного объекта, а не любой похожий номер.
Что даст эта статья

Сервер авторизован в нужном аккаунте, выполняет проверенное чтение и имеет правила контроля повторов, ошибок и будущих изменений.

Что подготовить перед началом

  • Опишите конкретную операцию, владельца интеграции, список аккаунтов и требуемые поля; начните с чтения кампаний или отчёта расходов.
  • Подготовьте серверную среду, хранилище секретов, доступ владельца рекламного аккаунта и отдельную тестовую конфигурацию.
  • Для Google Ads подготовьте manager account, developer token и OAuth; для Директа зарегистрируйте приложение OAuth и пройдите процедуру доступа к API.

01Определите первый безопасный сценарий

В интерфейсеТехническое задание → продукт API → операция чтения

Сначала автоматизируйте чтение, которое можно сверить вручную. Массовое изменение ставок и публикация объявлений требуют отдельного контроля прав и пределов. API нужен для конкретной рутины, а не вместо любого интерфейса.

  1. Выберите один аккаунт и один запрос: расходы за закрытый день без изменений.
  2. Опишите проверку результата: аккаунт, дата, валюта и итог должны совпасть с кабинетом.
  3. Храните секреты на сервере, ограничьте доступ и добавьте журнал ошибок и повторов.
Пример заполнения

Первый скрипт читает расходы одной компании. Он не удаляет кампании и не меняет ставки.

Проверка

Результат чтения сверен с кабинетом, а у интеграции есть ответственный и понятная область доступа.

02Подготовьте developer token Google Ads

В интерфейсеGoogle Ads manager account → Admin → API Center

Токен разработчика относится к приложению и уровню доступа API; OAuth относится к правам пользователя или поддерживаемой схемы авторизации. Это разные составляющие. Пройдите заявку/доступ по текущей документации и проверьте ограничения тестового и рабочего режима. ID управляющего аккаунта и ID клиента также отличаются.

  1. В аккаунте менеджера откройте API Center и оформите developer token.
  2. Проверьте статус доступа и разрешённые аккаунты среды теста.
  3. Запишите клиентский customer_id без дефисов; login_customer_id укажите, когда запрос проходит через менеджера.
Пример заполнения

developer token получен у менеджера, а данные запрашиваются у конкретного рекламодателя.

Проверка

Developer token и customer_id не перепутаны; уровень доступа допускает выбранный сценарий.

03Настройте OAuth Google

В интерфейсеGoogle Cloud → OAuth consent screen / Google Auth Platform → OAuth client

Создайте подходящий OAuth client и согласованный redirect URI. Разрешение Google Ads API использует scope https://www.googleapis.com/auth/adwords; доступ пользователя к рекламному аккаунту проверяется отдельно. Для серверного приложения получайте и храните refresh token по документированному OAuth-процессу; не копируйте его в код браузера. Проверяйте состояние приложения и условия тестовых пользователей.

  1. Настройте согласие и клиент OAuth по типу приложения.
  2. Авторизуйте пользователя с правами нужного аккаунта; проверьте возвращённые разрешения.
  3. Сохраните client secret и refresh token в серверном хранилище; обеспечьте обновление access token через официальную библиотеку.
Пример заполнения

Пользователь дал OAuth-разрешение, но не имеет доступа к customer_id: исправьте права, а не повторяйте запрос бесконечно.

Проверка

Авторизация работает под нужной учётной записью, секреты не попадают в интерфейс сайта.

04Выполните первый Google Ads запрос

В интерфейсеСервер → официальная клиентская библиотека → GoogleAdsService.search

Загрузите параметры доступа из переменных окружения либо защищённого файла вне публичного сайта. Для первого чтения используйте короткий GAQL-запрос с ограниченным числом результатов. Версию API и клиентской библиотеки сверяйте с актуальной документацией: фиксировать случайную устаревшую версию из статьи не следует. При финансовом отчёте учитывайте, что cost_micros требует деления на миллион.

  1. Установите официальную библиотеку поддерживаемой версии.
  2. В серверной среде задайте GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_USE_PROTO_PLUS=true; при работе через менеджера также GOOGLE_ADS_LOGIN_CUSTOMER_ID.
  3. Выполните чтение, сравните ID и состояния с кабинетом, запишите request ID ошибок без секретов.
Пример заполнения

Пример Python читает список кампаний; load_from_env ожидает корректную серверную конфигурацию официальной библиотеки.

Пример кода
import os
from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()
service = client.get_service('GoogleAdsService')
query = 'SELECT campaign.id, campaign.name, campaign.status FROM campaign LIMIT 10'
for row in service.search(customer_id=os.environ['ADS_CUSTOMER_ID'], query=query):
    print(row.campaign.id, row.campaign.name, row.campaign.status)
Замените демонстрационные идентификаторы на значения своего проекта.
Проверка

Ответ содержит ожидаемые кампании выбранного клиента, а не аккаунт менеджера.

05Оформите доступ Директа

В интерфейсеЯндекс OAuth → приложение; Директ → доступ к API → заявка

Зарегистрируйте приложение с нужным разрешением Директа, затем подайте заявку на доступ по документации. OAuth-токен выдаётся пользователем с соответствующими правами. Для агентской работы заголовок Client-Login выбирает рекламодателя; он не заменяет доступ пользователя к клиенту. Используйте песочницу для операций, которым не нужны рабочие данные.

  1. Зарегистрируйте приложение и сохраните Client ID/секрет в серверной конфигурации.
  2. Получите пользовательский OAuth-токен через документированный поток и проверьте доступ API.
  3. Запишите допустимые клиентские логины и отдельную конфигурацию песочницы/продакшена.
Пример заполнения

Один агентский токен может работать только с доступными клиентами; указание чужого логина не создаёт права.

Проверка

Авторизация и выбранный рекламодатель проверены до выполнения рабочих операций.

06Проверьте campaigns.get Директа

В интерфейсеPOST https://api.direct.yandex.com/json/v5/campaigns

Передавайте Authorization: Bearer и JSON тела, а не токен в URL. Код ниже выполняет чтение с явным клиентским логином из серверной среды. Транспортный HTTP-успех не гарантирует успех операции: API может вернуть объект error. Для ЕПК специальные возможности могут использовать v501; выбирайте адрес по документации конкретной операции, не заменяйте все URL вслепую.

  1. Сначала вызовите get с минимальными общими FieldNames.
  2. Проверьте result, error, request ID и список объектов.
  3. Обработайте пагинацию и ограничения выбранного метода; сопоставьте несколько ID с интерфейсом.
Пример заполнения

Campaigns.get возвращает существующие имена и состояния; токен не выводится в журнал.

Пример кода
import os, requests
response = requests.post(
    'https://api.direct.yandex.com/json/v5/campaigns',
    headers={
        'Authorization': 'Bearer ' + os.environ['YANDEX_DIRECT_TOKEN'],
        'Client-Login': os.environ['YANDEX_DIRECT_CLIENT_LOGIN'],
        'Accept-Language': 'ru'
    },
    json={'method': 'get', 'params': {
        'SelectionCriteria': {},
        'FieldNames': ['Id', 'Name', 'State'],
        'Page': {'Limit': 100, 'Offset': 0}
    }}, timeout=30
)
response.raise_for_status()
data = response.json()
if 'error' in data:
    raise RuntimeError('Direct API error: ' + str(data['error'].get('error_code')))
for campaign in data['result']['Campaigns']:
    print(campaign['Id'], campaign['Name'], campaign['State'])
Замените демонстрационные идентификаторы на значения своего проекта.
Проверка

Чтение успешное, клиент правильный, ответ ошибки не принят за пустой рекламный аккаунт.

07Добавьте контроль интеграции

В интерфейсеСервер → очередь задач → журнал запросов → план изменений

Храните секреты в менеджере секретов или защищённых переменных и закрывайте их в логах. Разделяйте запросы чтения и изменения. Повторы чтения с backoff допустимы по документированным ошибкам; перед повтором изменения проверяйте, не применилось ли оно уже. Для будущего управления бюджетом выводите конкретное «до/после», лимит изменения и список ID.

  1. Добавьте таймауты, обработку квот/лимитов и ограниченное число повторов.
  2. Логируйте метод, аккаунт, объект, результат и request ID без Authorization/refresh token.
  3. Для изменений используйте тестовые аккаунты, песочницу или validate_only там, где поддерживается; затем проверяйте реальные результаты чтением.
Пример заполнения

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

Проверка

Интеграция управляет только разрешёнными аккаунтами, позволяет объяснить каждый результат и остановить повторяющуюся ошибку.

УЧЕБНЫЙ РАЗБОР

Автоматический отчёт по расходам

Учебный пример: цифры и названия показывают способ работы, а не результаты клиента.

НА ПРИМЕРЕБезопасный первый запрос
Разрешение

Доступ только к нужной компании

Запрос

Расходы за выбранный день

Сверка

Аккаунт, валюта и итог

Контроль

Ошибка записана, повтор ограничен

Схема работы интеграции. Секретные токены не публикуют в примерах.

Авторская учебная схема SOAgency
  1. Запишите задачу: только прочитать расходы выбранного аккаунта за закрытый день.
  2. Получите разрешённый доступ API и храните токены на сервере, не в публичной странице.
  3. Сделайте один запрос чтения и сравните аккаунт, даты, валюту и сумму с кабинетом.
  4. Добавьте журнал ошибок и лимиты повторов, прежде чем автоматизировать расписание.
Что должно получиться

Программа возвращает сверенный отчёт нужной компании. Никакие ставки и объявления при учебной проверке не меняются.

Выполните и проверьте

Отмечайте шаг после проверки результата. Отметки действуют до перезагрузки страницы; они не подтверждают, что настройка выполнена правильно.

Чек-лист по шагам · 7

Рекламные API: когда нужны и как подключать безопасно

    • Выберите один аккаунт и один запрос: расходы за закрытый день без изменений.
    • Опишите проверку результата: аккаунт, дата, валюта и итог должны совпасть с кабинетом.
    • Храните секреты на сервере, ограничьте доступ и добавьте журнал ошибок и повторов.

    Проверка: Результат чтения сверен с кабинетом, а у интеграции есть ответственный и понятная область доступа.

    • В аккаунте менеджера откройте API Center и оформите developer token.
    • Проверьте статус доступа и разрешённые аккаунты среды теста.
    • Запишите клиентский customer_id без дефисов; login_customer_id укажите, когда запрос проходит через менеджера.

    Проверка: Developer token и customer_id не перепутаны; уровень доступа допускает выбранный сценарий.

    • Настройте согласие и клиент OAuth по типу приложения.
    • Авторизуйте пользователя с правами нужного аккаунта; проверьте возвращённые разрешения.
    • Сохраните client secret и refresh token в серверном хранилище; обеспечьте обновление access token через официальную библиотеку.

    Проверка: Авторизация работает под нужной учётной записью, секреты не попадают в интерфейс сайта.

    • Установите официальную библиотеку поддерживаемой версии.
    • В серверной среде задайте GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_USE_PROTO_PLUS=true; при работе через менеджера также GOOGLE_ADS_LOGIN_CUSTOMER_ID.
    • Выполните чтение, сравните ID и состояния с кабинетом, запишите request ID ошибок без секретов.

    Проверка: Ответ содержит ожидаемые кампании выбранного клиента, а не аккаунт менеджера.

    • Зарегистрируйте приложение и сохраните Client ID/секрет в серверной конфигурации.
    • Получите пользовательский OAuth-токен через документированный поток и проверьте доступ API.
    • Запишите допустимые клиентские логины и отдельную конфигурацию песочницы/продакшена.

    Проверка: Авторизация и выбранный рекламодатель проверены до выполнения рабочих операций.

    • Сначала вызовите get с минимальными общими FieldNames.
    • Проверьте result, error, request ID и список объектов.
    • Обработайте пагинацию и ограничения выбранного метода; сопоставьте несколько ID с интерфейсом.

    Проверка: Чтение успешное, клиент правильный, ответ ошибки не принят за пустой рекламный аккаунт.

    • Добавьте таймауты, обработку квот/лимитов и ограниченное число повторов.
    • Логируйте метод, аккаунт, объект, результат и request ID без Authorization/refresh token.
    • Для изменений используйте тестовые аккаунты, песочницу или validate_only там, где поддерживается; затем проверяйте реальные результаты чтением.

    Проверка: Интеграция управляет только разрешёнными аккаунтами, позволяет объяснить каждый результат и остановить повторяющуюся ошибку.

Скачать чек-лист TSV

TSV открывается в таблицах с разделителем «табуляция». В файле сохранены шаги, действия и критерии проверки этой статьи.

Удалось решить задачу?

Отправляются адрес статьи, выбранный результат, номер шага, категория и случайный номер отправки. Имя, телефон и комментарий не запрашиваются.

Частые ошибки

  • Токен встроен в код сайта.
  • Повтор запроса повторяет нежелательное изменение.
  • Автоматизация управляет не тем клиентским аккаунтом.

Вопросы и ответы

Можно ли хранить токен в JavaScript сайта?

Нет: посетители получают этот код. Авторизацию и API-запросы выполняйте на сервере, секреты храните вне публичных файлов и журналов.

Песочница показывает реальные расходы?

Тестовая среда предназначена для проверки операций и не заменяет рабочий финансовый отчёт. Сначала проверьте запросы тестом, затем выполните разрешённое чтение рабочего аккаунта.

С какой операции начать подключение рекламного API?

Начните с чтения списка кампаний или небольшого отчёта. Сверьте аккаунт, ID кампаний, период, валюту и часовой пояс с интерфейсом. Изменение бюджетов добавляйте отдельно, когда чтение и права доступа уже проверены.

Официальные источники

Материал написан своими словами по указанным справкам. Примеры и рекомендации so-agency адаптированы к задачам бизнеса; доступность функций и интерфейс могут отличаться.

Связанные инструкции

Google Ads

Автоматизированные правила Google Ads: как убрать рутину и сохранить контроль

Правило выполняет заранее описанное действие: присылает уведомление, приостанавливает выбранную рекламу или меняет доступный параметр. Разбираем создание, условия, предварительный просмотр и журнал, чтобы автоматизация помогала работе, а не управляла всем аккаунтом вслепую.

Читать инструкцию ↗
Google Ads

Google Ads Editor: массовые изменения, импорт CSV и проверка перед публикацией

Если нужно обновить много объявлений или ключевых слов, настольный Editor помогает подготовить изменения в одном месте. Показываем, как получить актуальные данные, сохранить исходное состояние, импортировать таблицу и опубликовать только проверенные кампании.

Читать инструкцию ↗
Аналитика / UTM

Заявки в CRM, Google Sheets и Telegram: сайт и лид-формы без потерь

Свяжите сайт и рекламные лид-формы с рабочей очередью заявок. Разбираем Tilda → Google Sheets, Google Ads → CRM и формы Meta → CRM или таблицу через реальный коннектор; проверяем поля, доставку и повторы.

Читать инструкцию ↗
Написать в WhatsApp

Как используются ваши данные

Имя, телефон и описание задачи нужны, чтобы ответить на вашу заявку. Они не используются для рассылок.

Заявка передаётся владельцу so-agency через Telegram. Вместе с ней передаём страницу, с которой вы обратились, и метки источника, канала и рекламной кампании, если они есть в ссылке. При выборе WhatsApp откроется чат с подготовленным текстом; отправку сообщения подтверждаете вы.

Используем Google Tag Manager для управления аналитикой. Она помогает понять, какие страницы и услуги полезны: учитываем обращения к контактам, переходы в проекты, глубину просмотра статей, действия с инструментами и учебной демонстрацией, а также начало заполнения, отправку, ошибки и успешную доставку заявки.

В параметры этих событий не передаём имя, телефон, текст обращения, исходные списки, ссылку для QR-кода или загруженные изображения. Сервисы аналитики могут получать технические сведения об устройстве и посещённых страницах, примерном регионе и cookies в зависимости от настроек подключённых тегов.

Данные инструментов обрабатываются в вашем браузере. Шаблон названий кампаний сохраняется на устройстве только по кнопке «Сохранить шаблон на этом устройстве». При передаче списка в другой инструмент он временно сохраняется в пределах текущей вкладки.

Сайт не публикует заявки и не просит пароли от рекламных кабинетов. По вопросам данных: +7 708 900 77 26.

Напишите в WhatsApp

Откройте камеру телефона и наведите её на QR-код. Откроется чат с so-agency.

QR-код: чат WhatsApp so-agency+7 708 900 77 26
Открыть WhatsApp на компьютере ↗

Сообщение отправите вы — чат открывается без автоматической рассылки.