--- metadata: - name: generator content: Diplodoc Platform v5.50.1 alternate: - https://yandex.com/dev/adfox/doc/en/v.1/format.md - https://yandex.com/dev/adfox/doc/ru/v.1/format.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/adfox/doc/ru/llms.txt # Структура запроса к API ## Структура запроса {#structure} Запрос к API состоит из блоков, передаваемых в URL: 1. [Обращение к хосту API с указанием версии](#reguest). 1. Авторизация. 1. [Навигационный блок](#section-action). 1. [Параметры](#params). В качестве разделителя параметров используется символ `&` (амперсанд). Параметр и значение разделяются символом `=` (равно). {% note alert %} API Adfox является регистрозависимым — все имена объектов нужно передавать с применением заглавных и строчных букв, как указано в документе. {% endnote %} ## Обращение к хосту API с указанием версии {#reguest} Хост для всех запросов к API: ```no-highlight https://adfox.yandex.ru/api/vX ``` Где `X` — номер версии, начиная с 1 (версия v0 не поддерживается). Например, запрос к API версии 1 будет такой: ```no-highlight https://adfox.yandex.ru/api/v1 ``` ## Навигационный блок {#section-action} Один запрос к API позволяет выполнить одно действие. В запросе необходимо передать информацию о том, в каком контексте какое действие необходимо произвести с объектом. За эту информацию отвечает навигационный блок с параметрами: 1. `object` — контекст, в котором производится действие. 2. `action` — действие, производимое над объектом. Для каждого контекста определен набор возможных действий. Примеры действий: - `add` — добавление объекта (доступно только в контексте `account`); - `list` — получение списка; - `modify` — редактирование объекта; - `update` — изменение параметров объекта; - `delete` — удаление объекта (доступно только в контексте `account`). 3. `actionObject` — название объекта, над которым производится действие. В некоторых методах `actionObject` может отсутствовать (например, в методах: [account-auth](https://yandex.com/dev/adfox/doc/ru/v.1/account/account-auth.md), [advertiser-modify](https://yandex.com/dev/adfox/doc/ru/v.1/advertiser/advertiser-modify.md), [assistant-modify](https://yandex.com/dev/adfox/doc/ru/v.1/assistant/assistant-modify.md)). ## Параметры {#params} Последний блок в запросе API составляют параметры вызываемого метода: 1. `обязательные` — например: ![](_images/params.png) 2. `необязательные` — параметры указываются в квадратных скобках, например: ![](_images/params_user.png) Если параметр не будет передан в запросе, то API будет использовать для этого параметра значение по умолчанию. Значения по умолчанию смотрите на странице у конкретного `actionObject`. ### Поиск нужного метода в документации Описания методов API в документе сгруппированы по контекстам, в которых они производятся, а внутри контекста — по типам действий. Поэтому чтобы найти нужный метод в документе, нужно построить цепочку контекст—действие—объект, аналогичную навигационному блоку запроса. Ниже приведено несколько примеров. {% cut "Добавить рекламную кампанию" %} Все новые объекты добавляются в контексте `account`. 1. Откройте в меню документации раздел [account](https://yandex.com/dev/adfox/doc/ru/v.1/account/account.md). 1. Выберите раздел с действием, которое необходимо совершить — например, добавление (add). 1. Выберите из списка тот объект, который необходимо добавить — [campaign](https://yandex.com/dev/adfox/doc/ru/v.1/account/account-add-campaign.md). ![](_images/account-add-campaign.png) Навигационный блок будет таким: ``` object=account&action=add&actionObject=campaign ``` {% endcut %} {% cut "Добавить баннер" %} Все новые объекты добавляются в контексте `account`. 1. Откройте в меню документации раздел [account](https://yandex.com/dev/adfox/doc/ru/v.1/account/account.md). 1. Выберите раздел с действием, которое необходимо совершить — например, добавление (add). 1. Выберите из списка тот объект, который необходимо добавить — [banner](https://yandex.com/dev/adfox/doc/ru/v.1/account/account-add-banner.md). ![](_images/account-add-banner.png) Навигационный блок будет таким: ``` object=account&action=add&actionObject=banner ``` {% endcut %} {% cut "Редактировать параметры баннера" %} 1. Откройте в меню документации раздел banner, так как действие нужно произвести с уже существующим объектом. 1. Выберите раздел с действием, которое необходимо совершить — например, редактирование (modify). 1. Выберите из списка тот объект, который необходимо редактировать — [banner](https://yandex.com/dev/adfox/doc/ru/v.1/banner/banner-modify-banner.md). Навигационный блок будет таким: ``` object=banner&action=modify&actionObject=banner ``` {% endcut %} {% cut "Таргетировать баннер по частоте" %} 1. Откройте в меню документации раздел [banner](https://yandex.com/dev/adfox/doc/ru/v.1/banner/banner.md), так как действие нужно произвести с уже существующим объектом. 1. Выберите раздел с действием, которое необходимо совершить — например, таргетирование (target). 1. Выберите из списка тот объект, который необходимо редактировать — [targetingFrequency](https://yandex.com/dev/adfox/doc/ru/v.1/banner/banner-target-targetingFrequency.md). Навигационный блок будет таким: ``` object=banner&action=target&actionObject=targetingFrequency ``` {% endcut %} ## Варианты передачи параметров в запросе к API Существует два варианта передачи блока навигации и блока с параметрами запроса: {% cut "Параметры запроса передаются в URL (GET)" %} В таком варианте все параметры передаются непосредственно в URL запроса к API. Параметры разделяются с помощью `&` (амперсанд), а пара «параметр-значение» записывается через знак `=` (равно). Порядок действий: 1\. Составьте запрос к API, состоящий из: - обращения к хосту: ``` https://adfox.yandex.ru/api/v1? ``` - блока навигации: ``` object=account&action=add&actionObject=campaign& ``` - параметров запроса (обязательных и, при необходимости, необязательных): ``` name=Adfox_company&advertiser=427&status=1&level=5 ``` 2\. В результате получим: ``` https://adfox.yandex.ru/api/v1?object=account&action=add&actionObject=campaign&name=Adfox_company&advertiser=427&status=1&level=5 ``` {% endcut %} {% cut "Параметры запроса передаются в тело (POST)" %} В таком варианте запрос собирается из обращения к хосту: ``` https://adfox.yandex.ru/api/v1 ``` И параметров запроса в body: ``` --form 'object=account' \ --form 'action=list' \ --form 'actionObject=website' \ ``` Пример POST запроса: ``` curl -k --location --request POST 'https://adfox.yandex.ru/api/v1' \ --header 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037' \ --form 'object=account' \ --form 'action=list' \ --form 'actionObject=website' \ ``` {% endcut %} ## Формат передачи значений «Дата и время» {#date-time} Формат передачи даты: `YYYY-MM-DD`. Формат передачи времени: `HH:mm`. Формат передачи времени с секундами: `HH:mm:ss`. Формат передачи даты и времени: `YYYY-MM-DD HH:mm`, где - `YYYY` — год; - `MM` — месяц; - `DD` — день; - `HH` — час; - `mm` — минута. {% note info %} Значения даты и времени записываются через пробел. {% endnote %} Например: ```css dateStart=2022-04-25 11:00&action=… ``` {% note info %} Для параметров дата/время — время является необязательным значением. По умолчанию выставляется в 00:00. {% endnote %} ## Кодировка входных параметров {#encoding} Если в запросе к API передаются кириллические символы, то необходимо указывать кодировку входных параметров в параметре `encoding`. Допустимые значения: - `UTF-8` (рекомендуется); - `CP-1251`. Например: ```xml encoding=UTF-8 ``` ## Лимиты количества запросов {#limits} Для запросов действуют ограничения по количеству — не более: - 100 запросов в минуту; - 3 запросов одновременно для одного владельца аккаунта.