SO-AGENCY · КАЗАХСТАН

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

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

API / интеграцииso-agency · 06.10.20265 мин чтения
Что получится после настройки

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

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

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

Учебная схема процесса; не скриншот рекламного кабинета.

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

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

Для первого подключения выберите конкретный отчёт или список объектов. Запишите аккаунт, даты, часовой пояс, валюту и ожидаемый результат. API Директа, Метрики и AppMetrica решают разные задачи; доступ к одному продукту не даёт автоматически административный доступ к другому. Не начинайте с массового изменения бюджета, если ещё не проверено чтение правильного клиента.

  1. Выберите список кампаний либо ежедневный отчёт расходов.
  2. Запишите customer_id Google Ads или client-login Директа, проверив его с владельцем.
  3. Составьте контрольный набор нескольких кампаний для сравнения ответа с интерфейсом.
Пример заполнения

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

Проверка

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

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 там, где поддерживается; затем проверяйте реальные результаты чтением.
Пример заполнения

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

Проверка

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

Пример для бизнеса

Автоматический отчёт о расходах — хороший первый сценарий. Автоматическое увеличение бюджета требует дополнительных правил и проверки экономики.

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

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

Вопросы по настройке

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

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

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

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

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

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

Нужна помощь с настройкой?

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

Написать в WhatsApp

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

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

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

На сайте установлен Google Tag Manager для управления аналитикой. События успешной заявки, открытия контактов и перехода в проекты передаются без имени, телефона и текста обращения. Сервисы аналитики могут использовать технические данные устройства и cookies в зависимости от настроек подключённых тегов.

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

Напишите в WhatsApp

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

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

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