Admin API: формат запросов, ответов и ошибок

Правила на этой странице действуют для всех методов Admin API. Адрес, токен и виды доступа описаны на странице Admin API: обзор и авторизация, параметры отдельных методов — на страницах своих разделов.

Тело запроса

• Тело — один JSON-объект в кодировке UTF-8. Массив на верхнем уровне и несколько объектов подряд не принимаются.
• Размер тела — до 1 МиБ.
• Неизвестные поля пропускаются без ошибки. Исключения: POST /api/v1/spend/snapshots и поле definition сохранённого отчёта — там лишнее поле даёт ошибку 422.
• Заголовок Content-Type для JSON-запросов не проверяется. Файлы и архивы загружаются как multipart/form-data.

Пустое тело, тело больше 1 МиБ, невалидный JSON и значение не того типа в большинстве методов дают код 400:

{"code": "bad_request", "message": "invalid json"}

У части методов текст сообщения другой или ответ приходит с кодом 422 и code = validation.

Пример запроса с телом:

curl -X POST https://panel.example.com/api/v1/affiliate-networks \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Network"}'

Ответ — код 201 и созданная запись.

Идентификаторы

Идентификаторы записей — UUID, например 3f2b8c1e-5a47-4d1b-9c0e-7a6d2f4b8e10. Они приходят в поле id при создании и в списках и подставляются в адрес: /api/v1/campaigns/{id}. Клик идентифицируется значением subid.

Идентификатор в неверном формате даёт код 400:

{"code": "bad_request", "message": "некорректный идентификатор или значение"}

Запись с верным по форме, но несуществующим идентификатором даёт 404 с code = not_found.

Коды успеха и формы ответа

Ответ — JSON с заголовком Content-Type: application/json; charset=utf-8.

Запись приходит объектом без обёртки. Списки приходят в одной из форм:

Пустой список — [], а не null.

Не JSON возвращают выгрузка отчёта (text/csv) и скачивание архива страницы или расширения расходов (application/zip).

Ошибки

Тело ошибки у всех методов одинаковое:

{"code": "validation", "message": "name is required"}

• code — код для обработки в интеграции.
• message — пояснение для человека, на русском или английском.

Других полей нет. Проверяйте код HTTP и code вместе: у отдельных методов validation приходит с кодом 400.

У отдельных методов есть свои коды, например export_quota или currency_rate. Они перечислены в описании метода. Коды 401, 402, 403 и 429 разобраны на странице Admin API: обзор и авторизация.

Изменение через PUT

PUT ведёт себя по-разному в зависимости от ресурса.

Постраничность

Параметры страниц зависят от метода.

Указывайте limit не больше максимума. В журналах кампании, reports/clicks, logs/audit, logs/{stream} и domain-replacements значение больше максимума ошибки не даёт: оно заменяется значением по умолчанию. В отчёте такое значение даёт код 422, в logs/clicks и deliveries/search — код 400 с code = validation.

Чтобы пройти журнал с курсором, передавайте в следующем запросе cursor со значением next_cursor из предыдущего ответа. Пустой next_cursor означает, что записей больше нет.

curl "https://panel.example.com/api/v1/logs/clicks?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&limit=200&cursor=<next_cursor>" \
  -H "Api-Key: <токен>"

Остальные списки приходят целиком. GET /api/v1/deliveries отдаёт последние 200 записей, GET /api/v1/report-exports — до 20, GET /api/v1/currency-rates — до 1000.

Сортировка

Сортировка задаётся только в запросе отчёта — полем sort:

{"sort": {"field": "profit", "direction": "desc"}}

• field — одна из выбранных группировок или метрика.
• direction — asc или desc.
• Без sort отчёт отсортирован по clicks по убыванию.

Порядок остальных списков не настраивается:

• кампании, офферы, лендинги, источники, сети, домены, токены — новые первыми;
• пользователи, типы конверсий, свои метрики, реестры блокировок — старые первыми;
• потоки — по position;
• группы доменов — по имени;
• сохранённые отчёты — по дате изменения, новые первыми.

Даты и часовой пояс

• Дата и время — строка RFC 3339: 2026-10-04T12:30:00Z или со смещением 2026-10-04T15:30:00+03:00. В строке запроса знак + кодируйте как %2B.
• Календарная дата — ГГГГ-ММ-ДД: поле day в расходах и курсах валют.
• Границы периода from и to — точные моменты времени. Пояс берётся из самой строки.
• Время Unix: в секундах — server_time, expires_at и lease_until в GET /api/v1/license, в миллисекундах — ts в GET /api/v1/logs/{stream}.

Без from и to журналы кампании, reports/clicks и logs/clicks отдают записи за последние 24 часа. Дата, которую не удалось разобрать, в журналах кампании и reports/clicks считается непереданной, ошибки нет. В logs/clicks и deliveries/search она даёт код 400, в logs/audit — 422.

Часовой пояс отчёта задаётся полем timezone — именем из базы IANA, например Europe/Moscow. Пустое значение означает UTC. Пояс влияет на календарные группировки hour, day, week, month, year, dow, hour_of_day. Неделя начинается с понедельника. Подробнее — на странице Период, часовой пояс и атрибуция.

У суточного лимита оффера, лимитов кликов потока и расписания потока свои поля пояса: cap_timezone, click_limits.timezone, schedule.tz. Пустое значение — UTC. В настройках расходов поле timezone обязательно.

Деньги и валюты

• Суммы — числа JSON, например 12.5.
• Валюта отчётов — USD. Настройка currency принимает только USD.
• cost_value кампании задаётся в USD, от 0 до 1 000 000 000. Для модели revshare это проценты от 0 до 100.
• Курс валюты задаётся полем usd_rate — сколько USD стоит одна единица валюты.

Выплата постбека в другой валюте переводится в USD по курсу на дату события, курс сохраняется в конверсии. Если курса нет, ответ — 422 с code = currency_rate. Подробнее — на странице Валюты и курсы.

Повтор запросов

Код 503 с code = unavailable означает временный сбой:

{"code": "unavailable", "message": "temporary error, retry later"}

Если в ответе есть заголовок Retry-After, подождите указанное в нём число секунд и повторите тот же запрос. Обычное значение — 5. Отчёт при временном сбое отвечает 503 с кодом report_unavailable: такой запрос тоже повторите позже.

Ответ 503 с обычным текстом Tracker maintenance in progress приходит во время обслуживания — см. раздел Базовый адрес.

На ответ сервер отводит 90 секунд. Для загрузки файлов и архивов страниц и скачивания архива страницы сроки длиннее: 10 минут на приём тела запроса и 15 минут на ответ. Большие отчёты получайте фоновой выгрузкой: Admin API: отчёты.