Как я пользуюсь API Яндекс Директа в агентстве

14.10.2026 · 8 мин чтения

В агентстве я больше не снимаю статистику Директа по одному кабинету. Для отчётов держу один контур: свой OAuth-токен, список клиентов через AgencyClients и заголовок Client-Login, а дальше сервис Reports. Здесь показываю, как получаю доступ, как обхожу логины и что проверяю в файле, прежде чем отдать выгрузку клиенту.

API Яндекс Директа для меня не вторая кнопка кабинета. В документации версия называется v5, в адресах сервисов я вижу v501. Запрос отправляю методом HTTPS POST, в теле передаю JSON. Тот же интерфейс умеет SOAP и XML. Вход идёт по протоколу OAuth 2.0. Отдельной платы за вызовы нет: в обзоре интерфейс указан как бесплатный.

В веб-кабинете выгрузка отчёта — отдельный клик и только внутри одного логина. Когда рекламодателей несколько, одно и то же занимает утро. Запросом я повторяю операцию по шаблону. В справке Яндекс пишет, что API полезен в первую очередь агентствам и крупным заказчикам со своей отчётностью.

Доступ я собираю в одном порядке и не меняю шаги местами. Сначала приложение в Яндекс ID. Потом заявка внутри Директа. Потом свой токен у каждого сотрудника, который реально ходит в API. Общий пароль на команду я не завожу: токен привязан к человеку и к его правам в кабинете.

Токен принадлежит представителю агентства, а не клиенту. У руководителя, директолога и автора интеграции токены разные. Если доступ отозвали или срок вышел, обновляю его по правилам Yandex OAuth. Чужой токен в скрипт и в переписку не кладу.

Токен сотрудника и секрет приложения я храню отдельно друг от друга.

ClientID и Client Secret говорят только о том, какое приложение обращается к Яндексу. Это не пароль от кабинета и не подпись запроса к данным рекламодателя. В заголовок Authorization я ставлю схему Bearer и OAuth-токен сотрудника. Секрет приложения в этот заголовок не входит. Его же не пишу в таблицу, в чат и в промпт к модели.

Список рекламодателей забираю сервисом AgencyClients. В актуальной версии путь выглядит как json/v501/agencyclients. В документации у сервиса три метода: add, update и get. Этот вызов идёт без заголовка Client-Login. Я спрашиваю данные агентства, а не один кабинет. Если заголовок всё-таки поставить, легко получить ответ не про тот контур и решить, что клиентов нет.

С 16 июня 2025 метод AgencyClients.add больше не поддерживается. Нового клиента я регистрирую через addPassportOrganization: доступ открывают по заявке агентствам с большим числом клиентов. С 19 июня 2025 метод addPassportOrganizationMember добавляет сотрудника в паспортную организацию. Старый add в шаблоне онбординга молча перестаёт пополнять список.

Из ответа get мне нужен логин рекламодателя. Длинный список листаю через LimitedBy и Offset. Логин в адрес сервиса не подставляю: он пойдёт отдельным заголовком, когда я запрошу кампании или отчёт.

Кампании и отчёт клиента я запрашиваю уже с Client-Login: в заголовке логин рекламодателя. Токен остаётся токеном сотрудника агентства. Если их перепутать, запрос смотрит не в тот кабинет или не смотрит ни в один, хотя код ответа может быть спокойным.

Баллы в документации называются Units. Это суточный лимит, свой у кабинета и завязанный на показы, клики и расход. Пересчёт раз в сутки. Каждый час приходит одна двадцать четвёртая часть лимита плюс остаток за двадцать три часа. Запрос с Client-Login по умолчанию тратит баллы клиента. Use-Operator-Units со значением true списывает их с агентства. Так я делаю, если у нового клиента лимит ещё не накопился. Остаток смотрю в заголовке ответа Units.

Reports — асинхронный сервис: файл редко приходит в том же ответе. В processingMode значение auto оставляет выбор сервису, online просит собрать сразу, offline ставит отчёт в очередь. Сводку по нескольким логинам я собираю в offline и оставляю тяжёлую выгрузку на ночь.

Пока код не стал 200, в таблицу клиента я ничего не кладу.

Если пришли 201 или 202, следующий запрос делаю не сразу, а через паузу retryIn из ответа. Пока код не стал 200, строки в сводку не пишу. Боевой адрес держу в конфиге как api.direct.yandex.com/json/v501 и дальше имя сервиса. Для статистики это Reports. Тело, как и у остальных сервисов, содержит method и params. Обход у меня один: AgencyClients.get, затем для каждого логина отдельный Reports с заголовком Client-Login.

Колонки держу в одном шаблоне, иначе сводка разъезжается. Если нужны конверсии, в FieldNames одновременно указываю Goals и Conversions. Одна колонка без второй даёт успешный ответ без нужных чисел. Для денег ставлю returnMoneyInMicros в false, иначе суммы приходят в микроединицах. Период и тип отчёта тоже беру из шаблона.

Код 200 значит только, что интерфейс не отклонил операцию. Пустой список ошибок говорит о том же. Перед отправкой сверяю файл с кабинетом на знакомом срезе. В письмо не попадают ни токен, ни секрет приложения, ни заголовок Authorization.

Сначала логин и период, потом цели, деньги и остаток баллов.

В песочнице чеклист короче: одна кампания на отчёт и тестовые клиенты, а не боевые логины. Когда сверка на тесте сошлась, тот же набор полей переношу на боевой Client-Login. Так я ловлю пустые конверсии и микросуммы до того, как файл увидит клиент.

Документацию держу на yandex.ru/dev/direct/doc/ru. Свой порядок короче: кампания и заявка, токен представителя, песочница, один Reports на одном Client-Login. После сверки файла включаю цикл AgencyClients.get по остальным логинам. Клиенту уходит сводка из проверенных колонок, а не из первого успешного кода.

SEO

Посмотрю заявку, токен, Client-Login и выгрузку Reports и скажу, какие поля сверить до отправки клиенту.