Мой дэйли дайджест

одно техническое понятие в день

API Яндекс.Директа

18 июля 2026 · ~14 мин чтения

api реклама интеграции oauth яндекс

API Яндекс.Директа

API Яндекс.Директа — это программный интерфейс, через который внешние приложения (собственные скрипты, CRM, сервисы автоматизации, агентские платформы) читают и меняют объекты рекламных кампаний Яндекс.Директа: сами кампании, группы объявлений, ключевые фразы, ставки, бюджеты, отчёты. По сути, это способ делать всё то же, что делает менеджер руками в веб-кабинете, только машиной и в масштабе.

История

Сам Яндекс.Директ — это сервис контекстной рекламы Яндекса, запущенный в 2001 году. Он был первой массовой системой контекстной рекламы в Рунете и опередил приход в Россию Google AdWords (нынешнего Google Ads) на несколько лет. С самого начала Директ был про самообслуживание: рекламодатель сам заводил кампании, сам подбирал слова, сам выставлял ставки — в отличие от классических медийных агентств с ручным размещением.

Пока рекламодателей было немного и кампании были маленькие, веб-интерфейса хватало. Но довольно быстро появился класс профессиональных пользователей — агентства, крупные интернет-магазины, партнёрские сети, — которым нужно было управлять сотнями кампаний и десятками тысяч ключевых слов. Кликать мышкой в такой ситуации нереально: людям нужен был программный доступ.

Основные вехи (даты приблизительные, я опираюсь на общедоступную документацию и здравый смысл — если тебе важна точность до года, сверься с yandex.ru/dev/direct):

Владелец сервиса — компания Яндекс (в текущем корпоративном контуре). Директ остаётся одним из основных источников выручки для рекламного бизнеса Яндекса, и API — не второстепенная фича, а полноценная точка входа для большого класса партнёров.

Что это такое

Технически API Яндекс.Директа v5 — это набор HTTPS-эндпоинтов, каждый из которых отвечает за свой класс объектов. Ты шлёшь POST-запрос с JSON-телом на URL вроде https://api.direct.yandex.com/json/v5/campaigns, в заголовках передаёшь OAuth-токен и язык интерфейса, в теле — что именно хочешь сделать: получить список, создать, обновить, удалить, приостановить, возобновить.

Логика ресурсов повторяет предметную область Директа:

Чем API отличается от соседних вещей:

API vs веб-интерфейс. Веб-интерфейс direct.yandex.ru — это кабинет для человека: ты видишь таблицы, графики, кнопки. Всё, что там есть, теоретически можно сделать и через API, но не наоборот — некоторые тонкие фичи и настройки бывают только в веб-интерфейсе, потому что появляются там раньше, чем в API. Для разовых операций и осмотра глазами веб-интерфейс удобнее; для массовых и повторяющихся — только API.

API vs Direct Commander. Direct Commander — это отдельное десктопное приложение Яндекса для массового редактирования кампаний офлайн: выгрузил из облака к себе, поправил в удобных таблицах, залил обратно. Commander сам под капотом ходит в API. Условно, Commander — это готовый GUI-клиент над API для менеджера, который не хочет писать код.

API vs фиды и XLS-выгрузки. Есть отдельный сценарий динамических объявлений с фидами (feeds) — когда объявления генерируются из товарного XML/CSV. Фиды — это данные, а API — это способ управлять всей остальной обвязкой вокруг них.

Аналогии из жизни

Аналогия с пультом умного дома. Веб-интерфейс Директа — это стенка с физическими выключателями: свет, кондиционер, шторы. API — это протокол умного дома, по которому Siri, HomeKit или скрипт могут послать те же команды удалённо и массово. Ты можешь один раз описать сценарий «когда я ухожу — выключить всё» и повторять его сотнями кампаний.

Где ломается: в умном доме команды обычно исполняются мгновенно и локально. В API Директа между «отправил» и «увидел эффект» есть задержки — модерация объявлений, обновление статистики, репликация. Никакого «мгновенного отклика» нет.

Аналогия с рестораном и кухней. Веб-кабинет — это зал ресторана: официант принимает заказ, приносит блюдо. API — это прямой канал на кухню: ты можешь сам крикнуть повару, что тебе нужно, минуя официанта. Быстрее, гибче, но требует, чтобы ты понимал, как устроена кухня (то есть модель данных Директа), и умел говорить с ней на её языке.

Где ломается: повар всё равно не приготовит блюдо, если у него нет продуктов. API Директа не всесилен: он не может обойти правила модерации, лимиты бюджета, ограничения площадки. «Прямой канал» не значит «безлимитный».

Аналогия с банковским API вместо кассы. Раньше, чтобы перевести деньги, ты шёл в отделение банка. Потом появился банк-клиент. А ещё позже — открытый банковский API (Open Banking): бухгалтерская программа сама забирает выписку и сама делает платежи, не заходя в кабинет. Похожим образом бухгалтерия рекламы (агентство, оптимизатор, in-house-сервис) вместо ежедневного захода в веб-кабинет Директа гоняет данные через API.

Где ломается: банковский API строго регламентирован — там законы, аудит, лицензии. API Директа — коммерческий продукт одной компании, правила которого могут меняться (объявляют устаревшие методы, вводят новые лимиты, меняют структуру ответа). Стабильность есть, но она гарантируется не законом, а желанием Яндекса не сломать экосистему партнёров.

Как это работает

Разберём типичный жизненный цикл интеграции с v5.

Шаг 1. Регистрация приложения. Ты идёшь на страницу разработчика Яндекса и регистрируешь OAuth-приложение: даёшь ему имя, указываешь права (какие сервисы Директа ему нужны — чтение, запись, отчёты, агентские операции), получаешь пару client_id / client_secret. Это удостоверение самого приложения, не конкретного пользователя.

Шаг 2. Авторизация пользователя (OAuth 2.0). Дальше пользователь (тот самый рекламодатель или менеджер агентства) должен разрешить твоему приложению действовать от его имени. Ты формируешь ссылку на страницу OAuth Яндекса вида https://oauth.yandex.ru/authorize?response_type=token&client_id=..., пользователь входит в свой Яндекс-аккаунт, видит запрос «Приложение X просит доступ к вашему Директу», нажимает «Разрешить» — и Яндекс отдаёт OAuth-токен. Этот токен ты хранишь у себя, обычно на стороне сервера, и подставляешь в каждый запрос к API.

Токены живут долго (у Яндекса, насколько я знаю, порядка года по умолчанию), но не вечно: их можно отозвать вручную из настроек аккаунта, они инвалидируются при смене пароля, и вообще любой токен теоретически может внезапно перестать работать. Поэтому нормальная интеграция обязана уметь обнаружить факт «токен умер» и уметь его перевыпустить (или хотя бы уронить внятную ошибку).

Шаг 3. Запрос. Простейший запрос выглядит примерно так (псевдокод):

POST https://api.direct.yandex.com/json/v5/campaigns
Authorization: Bearer <OAUTH_TOKEN>
Accept-Language: ru
Content-Type: application/json; charset=utf-8

{
  "method": "get",
  "params": {
    "SelectionCriteria": {},
    "FieldNames": ["Id", "Name", "Status", "State"]
  }
}

В ответ приходит JSON со списком кампаний. Обрати внимание на структуру: method + params — это остатки идеологии JSON-RPC, а FieldNames — обязательный список полей, которые ты хочешь получить. API не отдаёт «всё подряд»: ты сам выбираешь, что тебе нужно. Это разумно — экономит трафик и лимиты.

Шаг 4. Лимиты (баллы/units). У Яндекс.Директа исторически работает система «баллов»: каждый вызов метода тратит какое-то количество единиц из дневного бюджета аккаунта. Простые операции дёшевы, массовые (получить много объектов, изменить много ставок) — дороже. Точные тарифы описаны в документации и периодически меняются. В ответе API возвращает служебные заголовки с остатком лимита — их надо мониторить и, при подходе к нулю, притормаживать.

Дополнительно есть rate limit — ограничение количества запросов в единицу времени. Если превысить, вернётся ошибка, и надо будет подождать.

Шаг 5. Отчёты — отдельная история. Reports API работает не так, как остальные сервисы. Ты отправляешь запрос отчёта с параметрами (даты, поля, группировки, фильтры), получаешь ответ с HTTP-статусом:

Клиент должен уметь опрашивать сервер в цикле, пока статус не станет 200, а потом распарсить TSV/CSV-ответ. Такая схема нужна, потому что тяжёлые отчёты по большим аккаунтам считаются не мгновенно.

Шаг 6. Песочница (sandbox). У Директа есть отдельный тестовый контур — sandbox с собственным URL (https://api-sandbox.direct.yandex.com/). Там можно завести тестовые кампании и объявления, погонять запросы, отладить логику — и ничего не потратить в живой рекламе. Крайне полезная штука, особенно на этапе разработки.

Шаг 7. Обработка ошибок. API возвращает как HTTP-коды (401 — нет авторизации, 429 — слишком часто, 500 — ошибка сервера), так и структурированные ошибки в теле ответа с числовыми кодами и текстовыми описаниями. Хорошая интеграция логирует и то, и другое, различает временные сбои (retryable — можно повторить) и постоянные (неверные параметры, отозванный токен — повторять бесполезно).

Где встречается в обычной жизни

Обычный человек не открывает документацию API Яндекс.Директа. Но он постоянно видит его результаты:

Где встречается в IT и бизнесе

Программисты и маркетологи сталкиваются с этим API постоянно:

Кто пользуется

Альтернативы и конкуренты

Замечание: в контексте контекстной рекламы в Рунете у Директа фактически нет прямого конкурента-заменителя. Есть дополнения (VK, Telegram), но именно поисковый контекст в Яндексе покрывает только сам Директ.

Когда НЕ стоит использовать

Связанные понятия

Литература и источники

Где встретилось у меня

Вчера во внутреннем сервисе автоматизации рекламы OAuth-токен Яндекс.Директа умер раньше срока и API начал отвечать HTTP 401 — пришлось диагностировать, перевыпустить токен через OAuth-ссылку, разложить его по конфигам, перезапустить сервис через systemd и убедиться сквозной проверкой, что API снова отвечает.

Краткое резюме