---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.1
alternate:
  - https://yandex.com/dev/direct/doc/dg-v4/en/concepts/JSON.md
  - https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/JSON.md
  - href: https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/JSON.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt?revision=r22047995
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt?revision=r22047995

# Формат JSON

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

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

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

- **Perl**: модуль [JSON](http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm).
- **PHP**: встроенная поддержка JSON началась в версии 5.2.0. В предыдущих версиях можно использовать библиотеку [Services_JSON](http://pear.php.net/package/Services_JSON).
- **Python**: модуль [json](https://docs.python.org/library/json.html).

## Запросы JSON {#json-request}

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

**Версия 4**

 
```httpget
https://api.direct.yandex.ru/v4/json/ 
```

**Версия Live 4**

```httpget
https://api.direct.yandex.ru/live/v4/json/
```

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

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

Пример демонстрирует вызов метода `GetClientInfo`. В ключе `param` передается массив из одной строки, которая является логином пользователя. Ключ `locale` устанавливает русский язык для ответных сообщений. Ключ `token` — авторизационный токен, выданный OAuth-сервером Яндекса с согласия пользователя (подробнее см. [Авторизационные токены](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/auth-token.md)).

```javascript
POST /v4/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`, указывающий язык ответных сообщений. На выбранном языке возвращаются статусы кампаний, статусы баннеров и сообщения об ошибках. Возможны следующие значения `locale`:

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

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


## Доступ к финансовым методам {#fin-method}

Для доступа к финансовым методам [CreateInvoice](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateInvoice.md), [TransferMoney](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/TransferMoney.md), [GetCreditLimits](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetCreditLimits.md) и [PayCampaigns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/PayCampaigns.md) необходимо дополнительно указать номер операции и финансовый токен в ключах `operation_num` и `finance_token`. О том, как они формируются, см. в разделе [Доступ к финансовым методам](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/finance-token.md).

### Пример вызова финансового метода {#fin-method-example}

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

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

## Сообщения об ошибках {#errors}

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

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

Параметр `error_code` содержит код ошибки, `error_str` — краткое описание ошибки, `error_detail` — дополнительные пояснения, если имеются. Краткое описание и дополнительное пояснение могут выводиться на разных языках, что определяется параметром [locale](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/JSON.md#locale), указанным при вызове метода.

## Узнайте больше {#more}

- [Описание формата JSON](http://www.json.org/json-ru.html)