Что изменилось в версии 5

В версии 5 нет единых адресов для всех запросов. API версии 5 состоит из отдельных сервисов, и каждый сервис имеет собственные адреса.

Сервисы предназначены для работы с определенными классами объектов. Например, сервис Campaigns предназначен для управления кампаниями и имеет следующие адреса:

• для JSON-запросов:

  https://api.direct.yandex.com/json/v5/campaigns

• для SOAP-запросов:

  https://api.direct.yandex.com/v5/campaigns

• WSDL-описание:

  https://api.direct.yandex.com/v5/campaigns?wsdl

Адреса и список методов для каждого сервиса приведены в справочнике API.

Для доступа к API версии 5 разработчику необходимо подать заявку и дождаться ее одобрения. Это обязательно для всех приложений, в том числе для тех, которые подключились к API до введения процедуры регистрации приложений и продолжали работу с версией 4 и Live 4 без подачи заявки.

Как и в старых версиях API, в запросе к API версии 5 необходимо указать OAuth-токен, разрешающий доступ к данным конкретного пользователя. Отличие состоит в том, что токен следует передавать не в теле запроса, а в HTTP-заголовке Authorization. Например:

Authorization: Bearer 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f

В версии 5 агентство может в одном запросе оперировать данными только одного рекламодателя — клиента агентства. Логин рекламодателя следует передавать в HTTP-заголовке Client-Login.

Например:

Client-Login: agrom

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

Визитки, быстрые ссылки, уточнения и ключевые фразы в API версии 5 стали самостоятельными объектами, и для работы с ними предусмотрены отдельные сервисы. Управлять данными стало проще — например, чтобы изменить телефон в визитке, нет необходимости редактировать все объявления, в которых она используется. Также в API версии 5 реализована полная поддержка групп объявлений.

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

Так, в запросе на создание или изменение нескольких объектов каждый объект обрабатывается отдельно. Например, если приложение отправило запрос на создание 100 объявлений и в одном из них некорректные значения параметров, то остальные 99 объявлений будут успешно созданы.

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

Похожее правило действует и при получении данных — сервер возвращает не все параметры объекта, а только запрошенные приложением. Запрашивая только нужные параметры, можно существенно ускорить обмен данными.

В версии 5 все методы принимают и возвращают денежные значения в валюте рекламодателя. Параметр Currency, введенный в версии Live 4 для обеспечения обратной совместимости, не используется.

В API версии 4 и Live 4 допускалось не более 5 одновременных запросов от имени одного пользователя. В API версии 5 допускается не более 5 одновременных запросов от имени одного рекламодателя. Не имеет значения, какой из представителей рекламодателя или агентства, обслуживающего рекламодателя, выполняет запрос.

Ограничения на количество вызовов отдельных методов в API версии 5 не применяются.

Система баллов в версии 5 в целом аналогична версии 4 и Live 4, однако имеется ряд отличий:

• баллы начисляются не раз в сутки, а равномерно в течение суток;

• баллы списываются не только за успешные вызовы, но и за ошибки;

• агентство может расходовать собственные баллы на операции с данными рекламодателя — клиента агентства;

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

API версии 5 присваивает каждому запросу уникальный идентификатор и возвращает его в ответе на запрос. Пожалуйста, указывайте этот идентификатор при обращении в службу поддержки.