Admin API: источники трафика

Методы этой страницы делают то же, что раздел Источники в панели: создают источники трафика, меняют их токены и постбек, переносят параметры в кампании. Всем методам нужен токен с доступом Полный доступ (full). Авторизация описана на странице Admin API: обзор и авторизация, формат запросов и общие коды ошибок — на странице Формат запросов, ответов и ошибок.

Объект источника

Методы списка, чтения, создания и изменения возвращают источник в таком виде:

Токен

Элемент массива tokens. В массиве до 128 токенов.

Пробелы по краям name и param отбрасываются.

Строка постбека

Элемент массива postbacks. В массиве до 20 строк.

Адрес постбека — полный адрес http:// или https:// до 2048 символов, без пробелов и переносов строк. Фигурные скобки допустимы только у макросов.

В режиме single отправляется postback_url, строки postbacks не используются. В режиме per_status отправляются строки postbacks с подходящим статусом, postback_url не используется.

Секреты

Значения postback_secret и capi_token из API прочитать нельзя: в ответах вместо них стоит ***. Изменить и удалить секрет можно методом Изменить источник.

Каталог шаблонов

Получить каталог шаблонов

GET /api/v1/traffic-source-templates

Возвращает каталог шаблонов источников. Параметров нет.

Ответ — код 200 и объект:

Источники

Список источников

GET /api/v1/traffic-sources

Возвращает все источники команды. Параметров нет.

Ответ — код 200 и массив объектов источника, новые первыми. Постраничной выдачи нет.

Получить источник

GET /api/v1/traffic-sources/{id}

Возвращает один источник. {id} в пути — идентификатор источника.

Ответ — код 200 и объект источника.

Ошибки: 400 bad_request — {id} не в формате UUID, 404 not_found — источника нет.

Создать источник

POST /api/v1/traffic-sources

Создаёт источник из шаблона каталога или с полями из запроса.

Если передан template_id, поля tokens, cost_model и postback_url берутся из шаблона, а значения из запроса не учитываются. Режим постбека становится single, строки postbacks — пустыми. У шаблона с setup_required адрес постбека остаётся пустым: задайте его методом Изменить источник.

Ответ — код 201 и объект созданного источника.

curl -X POST https://panel.example.com/api/v1/traffic-sources \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Facebook Ads","template_id":"facebook","template_version":1}'

Ошибки:

Ошибки постбека приходят с кодом 400, ошибки названия и токенов — с кодом 422. Тексты ошибок постбека разобраны на странице S2S-постбэк в источник, тексты ошибок токенов — на странице Токены источника.

Изменить источник

PUT /api/v1/traffic-sources/{id}

Сохраняет источник. {id} в пути — идентификатор источника. Тело заменяет запись, поэтому передавайте источник целиком: получите его методом Получить источник, измените нужные поля и отправьте обратно. Секреты в виде *** при этом сохранятся.

Поля template_id и template_version этим методом не меняются.

Ответ — код 200 и объект источника. Новые токены действуют на клики всех кампаний источника сразу. Параметры в ссылках кампаний не меняются — для этого есть перенос параметров.

Ошибки: те же 400 и 422, что при создании, 400 bad_request — {id} не в формате UUID, 404 not_found — источника нет.

Удалить источник

DELETE /api/v1/traffic-sources/{id}

Удаляет источник. Кампании остаются, поле источника в них становится пустым. {id} в пути — идентификатор источника.

Ответ — код 204 без тела.

Ошибки: 400 bad_request — {id} не в формате UUID, 404 not_found — источника нет.

Перенос параметров в кампании

Перенос идёт в два запроса: сначала просмотр, затем применение. Правила слияния описаны на странице Применение источника к кампаниям.

Получить просмотр изменений

POST /api/v1/traffic-sources/{id}/apply/preview

Показывает, как сохранённые токены источника изменят параметры каждой кампании с этим источником. В кампаниях ничего не меняется. Тело запроса не нужно, {id} в пути — идентификатор источника.

Ответ — код 200 и объект:

Ошибки:

Применить просмотр

POST /api/v1/traffic-sources/{id}/apply

Записывает в кампании параметры из поля after просмотра. {id} в пути — идентификатор источника.

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

curl -X POST https://panel.example.com/api/v1/traffic-sources/3f6c1c1e-8a52-4a4b-9c0d-2b7e5d1a9f10/apply \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"preview_id":"b1d7a0c4-52e3-4c8f-a6b9-0e4f7d2c3a15"}'

Ответ — код 200 и объект:

{
  "updated": 1,
  "total": 2,
  "outcomes": [
    {"id": "7a1e0f3b-6c2d-4e58-b9a1-3d5c8e2f4a60", "state": "updated"},
    {"id": "c4b2d9e1-0f7a-4b36-8d5e-1a9c6f3b2e74", "state": "conflict"}
  ]
}

updated — число обновлённых кампаний, total — число кампаний в просмотре. Значения state:

Для кампаний с исходами conflict и unavailable получите новый просмотр и примените его. Повторный запрос с тем же preview_id возвращает сохранённый результат и ничего не меняет.

Ошибки: