analytic.local

Настройка OAuth Яндекса

← К аккаунтам Директа  ·  Агенты Яндекса

✓ OAuth-приложение настроено в .env

Архитектура подключения

В системе две сущности:

Это позволяет одним OAuth-подключением обслуживать все клиентские аккаунты, к которым у агента есть представительский доступ.

Реальные аккаунты в нашей конфигурации

Подключать агентом нужно тот аккаунт, у которого есть представительский доступ к нужным клиентам Директа. Если такого доступа нет — приложение автоматически отрабатывает фолбэк через clients/get и работает как с прямым рекламодателем (1 клиент = сам агент).

Шаг 1. Создайте приложение на oauth.yandex.ru

  1. Войдите на Яндекс под аккаунтом direct-itvbg@yandex.ru (или другим, на котором будет жить приложение)
  2. Откройте https://oauth.yandex.ru/
  3. Нажмите «Создать приложение»
  4. Выберите тип «Для авторизации пользователей».

Почему именно этот тип: для нашего OAuth-flow нужен Redirect URI на наш сайт (callback после подтверждения). Тип «Для доступа к API или отладки» использует фиксированный https://oauth.yandex.ru/verification_code — для веб-приложения с redirect он не подходит.

Шаг 2. Заполните параметры

Если забудете отметить direct:api, приложение поймает это сразу при OAuth-подключении агента и покажет понятную ошибку: «приложение не получило обязательные права». Без явной отметки токен будет «пустой», и на каждом запросе к API будет ошибка #1002 «Authorization error».

Шаг 3. Подайте заявку на доступ к API Директа

OAuth-приложение даёт право запрашивать токен с правом direct:api, но сами API-запросы Direct пропустит только если на ClientID есть одобренная заявка на доступ.

  1. В Директе под аккаунтом разработчика (direct-itvbg) создайте хотя бы одну кампанию (без неё нельзя зайти в настройки API)
  2. Откройте Настройки API → Мои заявки
  3. Примите пользовательское соглашение API (только при первом заходе)
  4. Нажмите «Новая заявка» и выберите тип:
    • «Тестовый доступ» — мгновенно, но работает только в Песочнице. Подходит для отладки, пока ждёте одобрения полного.
    • «Полный доступ» — нужен для production-API. Срок рассмотрения до 7 дней.
  5. В форме заявки выберите ClientID шага 1, укажите контактную почту, заполните сведения о приложении и отправьте.

До одобрения «Полного доступа» все запросы на api.direct.yandex.com будут падать с ошибкой авторизации. Чтобы не блокировать разработку — параллельно включите Песочницу (Шаг 4) и отметьте у агента флажок «Sandbox-режим».

Шаг 4. (Для отладки) Включите Песочницу

Песочница — изолированная среда Direct API с тестовыми данными. Не требует одобрения «Полного доступа», работает с любым валидным OAuth-токеном.

  1. Под тем же аккаунтом разработчика откройте Настройки API → Песочница
  2. Нажмите «Начать пользоваться Песочницей»
  3. Выберите роль «Агентство» и валюту RUB. Если выбрать «Клиент» — у вас не будет тестовых клиентов (agencyclients/get вернёт пусто), а наша интеграция в этом случае автоматически отработает фолбэк через clients/get и покажет один тестовый аккаунт.
  4. Установите галочку «Создать тестовые кампании» — Яндекс автоматически создаст 3 тестовых клиентов с 3 кампаниями
  5. Нажмите «Продолжить»

Песочница не имеет веб-интерфейса — посмотреть тестовые кампании можно только через API. Через месяц без обращений данные удаляются. При смене роли все тестовые данные сбрасываются.

Шаг 5. Пропишите ключи в .env

YANDEX_CLIENT_ID=ваш_client_id
YANDEX_CLIENT_SECRET=ваш_client_secret

Шаг 6. Подключите агента

  1. Откройте /yandex-direct/agents
  2. Нажмите «+ Подключить агента (OAuth)»
  3. В окне Яндекса выберите аккаунт, у которого есть представительский доступ к нужным клиентам Директа (например, marcar-reklama или аккаунт-представитель Vitamin.tools)
  4. Подтвердите доступ → вернётесь на карточку агента — токен сохранён
  5. Если работаете в Песочнице — на карточке агента поставьте галочку «Sandbox-режим»: запросы пойдут на api-sandbox.direct.yandex.com

Если в браузере залогинен «не тот» аккаунт Яндекса — добавьте нужный через passport.yandex.ru/profile (кнопка «Добавить аккаунт»), либо откройте flow в окне инкогнито и войдите там под нужным.

Шаг 7. Подтяните клиентов и кампании

  1. На карточке агента нажмите «⤓ Получить клиентов из API». Приложение сначала вызовет agencyclients/get, при его недоступности автоматически фолбэкнется на clients/get.
  2. Отметьте нужных клиентов и нажмите «Создать клиентские аккаунты для отмеченных»
  3. Откройте созданный клиентский аккаунт и нажмите «Синхронизировать кампании»
  4. Опционально — настройте дефолтный источник или правила маппинга кампаний

Замечания