О чем вы хотите спросить у службы поддержки?

API сервиса Яндекс Директ предоставляет программный доступ к данным и позволяет создавать приложения для управления рекламными кампаниями. Через API внешние приложения добавляют и редактируют кампании, объявления, фразы, задают ставки.

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

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

Все изменения, сделанные через API, отражаются в ваших рекламных кампаниях.

Поскольку разные компании подходят к управлению рекламой по-разному, на рынке появилось множество решений для управления рекламой на основе API Яндекс Директа.

Многие рекламные агентства предлагают своим клиентам инструменты для автоматического управления рекламой в Директе, а также оптимизируют с их помощью собственные рабочие процессы. Все эти инструменты построены на методах API Директа.

У Яндекса также есть готовые решения на основе API Яндекс Директа:

• Программа Директ Коммандер — предназначена для управления масштабными рекламными кампаниями в удобном интерфейсе.
• Мобильный Директ для iPhone и Android — предоставляет рекламодателям возможность управлять своими кампаниями максимально оперативно.

Запросы к API Директа выполняются по протоколу HTTPS методом POST. Входные и выходные структуры данных передаются в теле запроса и ответа.

API Директа поддерживает два формата взаимодействия: JSON и SOAP.

Для авторизации используетcя протокол OAuth 2.0: в запросах необходимо указывать авторизационный токен.

Подключение к API Директа и его использование является бесплатным.

Приложение (программа, скрипт и др.) выполняет запрос к API от имени пользователя Директа — представителя рекламодателя или рекламного агентства — и управляет данными, принадлежащими этому пользователю.

Доступ приложения к данным пользователя возможен при выполнении следующих условий:

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

2. Пользователь имеет аккаунт в Директе и является представителем прямого рекламодателя, рекламного агентства или клиента агентства, которому агентство разрешило доступ к его данным.

   Примечание.

   • Если агентство предоставило клиенту доступ в веб-интерфейс только на чтение, то и через API представитель клиента сможет только получать данные.

   • Если агентство предоставило клиенту право на редактирование кампаний, то представитель клиента сможет управлять кампаниями клиента как в веб-интерфейсе, так и через API.

3. Пользователь принял условия пользовательского соглашения на странице API сервиса Яндекс Директ.
4. Пользователь разрешил приложению выполнять запросы от своего имени.

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

   Чтобы получить токен, приложение должно открыть для пользователя на страницу запроса доступа. Пользователь авторизуется на Яндексе (под своим логином в Директе) и нажимает кнопку Подтвердить. Далее сервер Яндекса генерирует токен и передает его приложению.

Получение токена вручную

На этапе отладки приложения вы можете вручную получить так называемый отладочный токен от имени тестового пользователя. См. раздел Отладочный токен документации Яндекс.OAuth.

Получение токена в автоматическом режиме

При переходе к работе с данными реальных пользователей необходимо реализовать в приложении удобный для пользователей механизм получения токена. Чтобы получить токен, приложение должно открыть для пользователя специальную страницу Яндекс.OAuth — страницу запроса доступа. Пользователь авторизуется на Яндексе (под своим логином в Директе) и подтверждает доступ приложения к своим данным — нажимает кнопку «Разрешить». Яндекс.OAuth генерирует токен и передает его приложению в автоматическом режиме.

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

См. также пример на PHP, пример на Python.

Какой режим получения токена выбрать?

В некоторых случаях допустимо использовать токен, полученный вручную, и после перехода к работе с данными реальных пользователей. Например:

• если с приложением работает небольшое количество пользователей — представителей одного рекламодателя;

• если приложение не взаимодействует с пользователем — например, скрипт обновляет ставки в автоматическом режиме.

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

Токен может стать недействительным, например, если пользователь сменил пароль на Яндексе. Полный список причин приведен в разделе Отзыв токенов документации Яндекс.OAuth. В этом случае требуется получить новый токен.

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

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

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

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

См. также

• Ограничения, баллы

В целях обнаружения ошибок и отладки иногда требуется вывести SOAP-запрос клиента и SOAP-ответ сервера.

Для Perl:

my $client = SOAP::Lite->service($client->on_debug(sub {print @_}));

Проверьте выполнение следующих условий:

• Убедитесь, что ключевая фраза активна (значение ON параметра State), с помощью метода Keywords.get.
• Убедитесь, что в группе есть хотя бы одно активное объявление (значение ON параметра State), с помощью метода Ads.get. Объявления можно отбирать одновременно по идентификатору группы (входной параметр AdGroupIds) и состоянию (входной параметр States).
• Убедитесь, что кампания активна (значение ON параметра State), с помощью метода Campaigns.get.

Если все условия выполнены, показы объявлений по фразе возможны. Однако выполнение показов непосредственно в текущий момент не гарантируется. Наиболее частые причины отсутствия показов:

• кампания находится в процессе активизации;
• показы автоматически приостановлены в соответствии с настройками дневного бюджета или автоматической стратегии;
• показы автоматически приостановлены в соответствии с настройками временного таргетинга.

Более подробная информация приведена в разделе Проблемы с показами помощи Директа.

Список изменений по версиям API представлен в следующих разделах:

• Для API версии 5 — в разделе API версии 5. История изменений.
• Для API версии Live 4 — в разделе Версия Live 4 (deprecated).

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

Документация версии 4 и Live 4 находится по адресу https://tech.yandex.ru/direct/doc/dg-v4.

Полную информацию об изменениях в версии 5 по сравнению с предыдущими версиями, а также о соответствии методов и их параметров вы найдете в Руководстве по переходу.