Документация
API версии 5. Руководство разработчика
API версии 5. Справочник

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

Варианты использования и возможности API Директа подробно описаны в документации. Если вы не нашли ответ на свой вопрос, обратитесь к нашим специалистам — мы обязательно вас проконсультируем.

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

Совет. Только начинаете осваивать API? Рекомендуем пройти обучающий курс Как начать работать с API Яндекc.Директа.

Частые вопросы по работе с API Директа

Что такое API Яндекс.Директа и в каких целях его можно использовать?

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

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

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

Есть ли разница в управлении рекламной кампанией через API и через веб-интерфейс?

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

Есть ли готовые программы, использующие API Директа?

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

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

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

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

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

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

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

Сколько стоит использование API?

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

Как подключиться к API?

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

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

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

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

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

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

  3. От имени пользователя создана хотя бы одна рекламная кампания в веб-интерфейсе (достаточно создать одно объявление-черновик с одной ключевой фразой).
  4. Пользователь принял условия пользовательского соглашения на странице API сервиса Яндекс.Директ.
  5. Пользователь разрешил приложению выполнять запросы от своего имени.

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

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

Как получить токен для пользователя?
Получение токена вручную

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

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

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

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

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

Внимание! Независимо от того, получен ли токен вручную или автоматически, он дает возможность управлять реальными рекламными материалами пользователя.
Какой режим получения токена выбрать?

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

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

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

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

Почему токен стал недействительным?

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

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

Как я могу увеличить количество доступных мне баллов?

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

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

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

См. также

Как можно вывести XML-код запроса и ответа сервера?

В целях обнаружения ошибок и отладки иногда требуется вывести 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 Директа:

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

Где найти документацию версии 4 и Live 4?

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

Чем отличается версия 5 от версий 4 и Live 4?

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