Admin API: потоки

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

Объект потока

Этот объект возвращают и принимают методы создания и изменения, возвращают список и копирование.

У потока без офферов или лендингов поля offers и landers равны null. Доля share, если её не передать, равна 100; явный 0 исключает элемент из ротации. Подробнее о долях — на странице Ротация и сплит-тесты, о расписании и лимитах — на странице Расписание и лимиты кликов потока.

Действие и его параметры

Что делает каждое действие и способ редиректа — на странице Действия потока и способы редиректа.

Фильтры

Каждый элемент массива filters — одно условие:

Условия с одним номером группы объединяются по ИЛИ, группы между собой — по И. Если ни у одного условия group не задан, условия объединяются по полю mode. Формат значений каждого поля — на странице Фильтры потока.

Потоки кампании

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

GET /api/v1/campaigns/{id}/streams

Возвращает массив потоков кампании по возрастанию position. {id} — идентификатор кампании. Ошибка: 404 — кампания не найдена.

Создать поток

POST /api/v1/campaigns/{id}/streams

Создаёт поток в кампании {id}. Тело — объект потока.

curl -X POST https://panel.example.com/api/v1/campaigns/3f2a1c9e-5b7d-4e8a-9c1f-0a2b3c4d5e6f/streams \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US mobile",
    "type": "regular",
    "action_type": "offers",
    "weight": 100,
    "position": 1,
    "filters": [
      {"type": "geo", "op": "in", "values": ["US"], "group": 1},
      {"type": "device", "op": "in", "values": ["mobile"], "group": 2}
    ],
    "offers": [{"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "share": 100}],
    "click_limits": {"daily": 5000, "timezone": "Europe/Warsaw"}
  }'

Ответ — код 201 и объект потока с новым id. В нём стоят те значения, которые вы передали: значения по умолчанию видны в списке потоков.

Ошибки:

• 400 bad_request — тело не разобрано как JSON-объект;
• 404 not_found — кампания не найдена;
• 422 validation — action_type is required; неизвестный тип или оператор фильтра: <тип>; Лимиты кликов: целые числа от 0 до 1 000 000 000 000; Неизвестный часовой пояс лимита; оффер недоступен: <id>; лендинг недоступен: <id>.

Изменить поток

PUT /api/v1/streams/{id}

Меняет поток {id}. Передавайте только те поля, которые нужно изменить: остальные сохраняются. Переданное поле заменяется целиком. Чтобы поменять один ключ в action_payload или один оффер в offers, получите поток из списка, измените объект и отправьте его полностью. null в schedule или click_limits снимает расписание или лимиты.

curl -X PUT https://panel.example.com/api/v1/streams/b7e6d5c4-3a2f-4b1e-9d0c-8f7e6d5c4b3a \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"state": "paused"}'

Ответ — код 200 и объект потока со всеми полями. Ошибки 400 и 422 те же, что при создании, кроме action_type is required; 404 — поток не найден. Перенести поток в другую кампанию этим методом нельзя.

Удалить поток

DELETE /api/v1/streams/{id}

Удаляет поток. Ответ — код 204 без тела. Ошибка: 404 — поток не найден.

Задать порядок потоков

POST /api/v1/campaigns/{id}/streams/reorder

Расставляет потоки кампании по списку.

Первый поток списка получает position 0, второй — 1 и так далее. Потоки, которых нет в списке, сохраняют прежнюю позицию. Идентификаторы потоков других кампаний пропускаются. Ответ — код 204 без тела. Ошибки: 400 — тело не разобрано или в списке не UUID; 404 — кампания не найдена.

Скопировать поток

POST /api/v1/streams/{id}/clone

Создаёт копию потока в той же кампании. Тело не нужно. Копия получает название с добавкой « · копия», состояние paused и позицию после последнего потока; офферы, лендинги, фильтры, расписание и лимиты переносятся. Ответ — код 201 и объект нового потока. Ошибки: 404 — поток не найден; 422 — условие, оффер или лендинг исходного потока не прошли проверку.

Шаблоны и импорт

Как шаблоны и файлы выглядят в панели — на странице Шаблоны, экспорт и импорт потоков.

Выгрузить поток в файл

GET /api/v1/streams/{id}/export

Возвращает переносимое описание потока. Ответ — код 200, заголовок Content-Disposition с именем файла stream-<id>.json и тело:

{
  "format": "tracker-stream",
  "version": 1,
  "stream": {"id": "", "campaign_id": "", "name": "US mobile", "type": "regular", "action_type": "offers", "state": "paused", "position": 0}
}

В stream — все поля объекта потока, в примере показана часть. Идентификаторы потока и кампании пустые, состояние — paused, позиция — 0. В action_payload остаются только ключи из таблицы действий. Ошибка: 404 — поток не найден.

Проверить файл перед импортом

POST /api/v1/campaigns/{id}/stream-import/preview

Проверяет файл шаблона для кампании {id} и возвращает готовый черновик. Поток при этом не создаётся.

Ответ — код 200 и объект потока в состоянии paused с позицией после последнего потока кампании. Чтобы создать поток, отправьте этот объект методом «Создать поток».

Ошибки: 400 — Не удалось прочитать файл шаблона; 404 — кампания не найдена; 422 — файл не прошёл проверку, в message стоит причина, например Нужен шаблон tracker-stream версии 1 или Шаблон больше 256 КиБ. Все пределы файла — в разделе Ограничения файла.

Сохранить поток как шаблон

POST /api/v1/streams/{id}/templates

Сохраняет настройки потока {id} в личную библиотеку шаблонов пользователя, который создал токен.

Ответ — код 201 и объект шаблона: id, name, definition — то же описание, что отдаёт выгрузка в файл, created_at. Ошибки: 400 — Некорректный запрос; 404 — поток не найден; 422 — Название шаблона: от 1 до 120 символов или поток не прошёл проверку шаблона.

Список шаблонов

GET /api/v1/stream-templates

Возвращает массив шаблонов создателя токена, новые — первыми. Поля элемента: id, name, definition, created_at. Шаблоны других пользователей в список не входят.

Удалить шаблон

DELETE /api/v1/stream-templates/{id}

Удаляет шаблон из библиотеки создателя токена. Ответ — код 204 без тела. Ошибка: 404 — шаблон не найден. Потоки, созданные из шаблона, не меняются.

Пробный расчёт

POST /api/v1/campaigns/{id}/routing-preview

Показывает, какой поток кампании получит посетитель с заданными параметрами. Клик не записывается, счётчики лимитов не меняются. Все поля необязательны, регистр букв в именах полей не учитывается.

curl -X POST https://panel.example.com/api/v1/campaigns/3f2a1c9e-5b7d-4e8a-9c1f-0a2b3c4d5e6f/routing-preview \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"Country": "US", "Device": "mobile", "OS": "Android", "Browser": "Chrome", "SubIDs": {"sub_id_1": "fb"}}'

Ответ — код 200:

• streams — потоки кампании. У каждого: id, name, type, weight, position; eligible — подходит ли поток посетителю; filters — результат каждого условия в порядке массива filters потока; selected — true у выбранного потока; reason — пояснение текстом.
• campaign_state и rotation — состояние и режим ротации кампании.
• at — момент, на который сделан расчёт.

Значения reason и порядок чтения результата — на странице Проверка выбора потока. Ошибки: 400 — тело не разобрано; 404 — кампания не найдена; 422 — invalid IP.

Счётчики и статистика

Счётчики лимитов потока

GET /api/v1/streams/{id}/click-limits

Возвращает, сколько входов учтено в лимитах потока: hourly — за текущий час, daily — за текущие сутки, total — всего. Час и сутки считаются в часовом поясе лимитов потока; если лимиты не заданы — в UTC. Ошибки: 404 — поток не найден; 503 с кодом unavailable — Счётчики временно недоступны, повторите запрос позже.

Клики по потокам кампании

GET /api/v1/campaigns/{id}/stream-stats

Возвращает клики и уникальные клики по потокам кампании за период.

Ответ — код 200 и объект с массивом items. У элемента три поля: stream_id, clicks, uniques. Потоков без кликов за период в массиве нет. Значение не в формате RFC 3339 заменяется значением по умолчанию. Ошибки: 404 — кампания не найдена; 400 с кодом report_error — запрос статистики не выполнен.

Другие показатели по потокам стройте методом отчётов с группировкой stream — см. Admin API: отчёты.

Ошибки

оффер недоступен или лендинг недоступен

Оффера или лендинга с таким id нет в команде. Проверяются только новые элементы: те, что уже были в потоке, при изменении не перепроверяются.

Изменения не видны в трафике

Изменения через API действуют сразу. Убедитесь, что поток в состоянии active: копия и поток из импорта создаются в состоянии paused.