Формат JSON

Взаимодействие с API Яндекс Директа в формате JSON.

Преимущество JSON в большей компактности по сравнению с SOAP/XML, а также в скорости анализа запросов на стороне Яндекс Директа.

Во многих языках программирования существуют модули и библиотеки для работы с JSON. Ниже перечислены рекомендуемые модули и библиотеки для популярных языков.

  • Perl: модуль JSON.
  • PHP: встроенная поддержка JSON началась в версии 5.2.0. В предыдущих версиях можно использовать библиотеку Services_JSON.
  • Python: модуль json.

В документе содержатся примеры работы с JSON: Perl, PHP, Python.

Запросы JSON

Запросы в формате JSON передаются методом HTTP POST на следующий адрес:

Версия 4
https://api.direct.yandex.ru/v4/json/
Версия Live 4
https://api.direct.yandex.ru/live/v4/json/

Запрос всегда содержит ключ method с именем вызываемого метода и в большинстве случаев ключ param (см. пример ниже). Некоторые методы не имеют входных параметров, и для них ключ param не требуется.

Пример запроса JSON

Пример демонстрирует вызов метода GetClientInfo. В ключе param передается массив из одной строки, которая является логином пользователя. Ключ locale устанавливает русский язык для ответных сообщений. Ключ token — авторизационный токен, выданный OAuth-сервером Яндекса с согласия пользователя (подробнее см. Авторизационные токены).

POST /v/json/ HTTP/1.1
Host: api.direct.yandex.ru
Content-Length: 204
Content-Type: application/json; charset=utf-8

{
    "method": "GetClientInfo",
    "param": ["agrom"],
    "locale": "ru",
    "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}

Язык ответных сообщений

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

  • ru — русский;
  • ua — украинский;
  • en — английский.

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

Доступ к финансовым методам

Для вызова финансовых методов CreateInvoice, TransferMoney, GetCreditLimits, PayCampaigns необходимо дополнительно указывать номер операции и финансовый токен в ключах operation_num и finance_token. Об их формировании рассказывается в разделе Доступ к финансовым методам.

Пример вызова финансового метода

Вызов финансового метода GetCreditLimits.

{
    "method": "GetCreditLimits",
    "finance_token": "07c2fbae9722634918bb00a70d2c467cf1bd07255012008ff249ba41b7a5cd6c",
    "operation_num": 123,
    "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}

Сообщения об ошибках

При возникновении ошибок обработка запроса прекращается и возвращается сообщение об ошибке в формате JSON. Пример сообщения показан ниже.

{
    "error_detail":"Метод HTTP запроса должен быть POST",
    "error_str":"Неверный метод запроса",
    "error_code":512
}

Параметр error_code содержит код ошибки, error_str — краткое описание ошибки, error_detail — дополнительные пояснения, если имеются. Краткое описание и дополнительное пояснение могут выводиться на разных языках, что определяется параметром locale, указанным при вызове метода.