ВойтиПопробовать бесплатно
Разделы документации

Admin API: обзор и авторизация

Как подключиться к Admin API трекера: базовый адрес, токен в заголовке Api-Key, виды доступа, срок действия и ограничения.

Admin API — тот же API, через который работает панель. Внешний запрос отличается только авторизацией: вместо входа в панель передаётся токен в заголовке Api-Key. Создавать и отзывать токены могут владелец и администратор.

Базовый адрес

Все методы находятся по адресу:

text
https://panel.example.com/api/v1

Вместо panel.example.com подставьте домен своей панели. Версия в пути одна — v1.

На домене трекинга из API открыты только адреса приёма данных, которым токен не нужен: /api/v1/postback, /api/v1/lead и /api/v1/lead-file. Запросы с токеном отправляйте на домен панели.

Во время резервного копирования, восстановления из копии и обновления на любой запрос к /api/ приходит код 503 с текстом Tracker maintenance in progress. Это обычный текст, не JSON. Повторите запрос позже.

Создание токена

  1. Откройте Настройки → API.
  2. В блоке API-токены нажмите + Токен.
  3. Заполните Название, например имя интеграции. Длина — до 200 байт: это 200 латинских символов или 100 кириллических.
  4. Выберите Доступ: Сводные отчёты или Полный доступ. По умолчанию — Сводные отчёты.
  5. Выберите Срок действия: 7 дней, 30 дней, 90 дней или 365 дней. По умолчанию — 90 дней.
  6. Нажмите Создать.
  7. Скопируйте токен из блока «Новый токен — скопируйте сейчас, повторно его не показать:» кнопкой Копировать.

Токен выглядит как trk_ и 40 символов после него: цифры и буквы от a до f. Целиком он показывается один раз. В списке потом видны название, первые 12 символов токена, вид доступа, срок, дата создания и дата последнего использования.

Токен для расширения расходов создаётся в другом месте: Настройки → Расходы, блок Подключить профиль, кнопка Создать ключ. Подробнее — на странице Расширение для расходов Facebook.

Те же действия через API описаны на странице Admin API: API-токены, работа со списком в панели — на странице API-токены.

Внимание.

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

Заголовок Api-Key

Передавайте токен в заголовке Api-Key каждого запроса:

bash
curl https://panel.example.com/api/v1/campaigns \
  -H "Api-Key: trk_0123456789abcdef0123456789abcdef01234567"

Этот запрос требует доступа Полный доступ. Для токена Сводные отчёты проверьте подключение запросом отчёта:

bash
curl -X POST https://panel.example.com/api/v1/reports \
  -H "Api-Key: trk_0123456789abcdef0123456789abcdef01234567" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-01T00:00:00Z","to":"2026-10-02T00:00:00Z","dimensions":["campaign"],"metrics":["clicks","leads"],"timezone":"UTC"}'

Успешный ответ — код 200 и JSON. Поля отчёта описаны на странице Admin API: отчёты, общий формат запросов, ответов и ошибок — на странице Формат запросов, ответов и ошибок.

Если в запросе есть и Api-Key, и Authorization, используется Api-Key.

На неверный, отозванный или истёкший токен сервер отвечает кодом 401:

json
{"code": "unauthorized", "message": "invalid api key"}

От чьего имени работает токен

Запрос выполняется от имени пользователя, который создал токен, с его текущей ролью.

  • Токен действует, пока создатель остаётся владельцем или администратором. Подробнее о ролях — на странице Команда и роли.
  • Если создателя удалить или дать ему роль ниже администратора, его токены удаляются. Запросы с ними получают 401.
  • Ограничения доступа по разделам, группам кампаний и полям отчётов на запросы с токеном не действуют: они не задаются для владельца и администратора.
  • Время последнего запроса видно в списке токенов в строке «использован».

Виды доступа

У токена один вид доступа. В API он передаётся в поле scopes — массив из одного значения.

Доступ в панелиЗначение в APIЧто разрешено
Сводные отчётыreports:readPOST /api/v1/reports, POST /api/v1/reports/export, GET /api/v1/custom-metrics, GET /api/v1/conversion-types
Расходы расширенияspend:writePOST /api/v1/spend/snapshots, GET /api/v1/spend
Полный доступfullВсе методы, которые требуют авторизации, кроме методов владельца установки

Запрос к методу вне своего доступа получает код 403:

json
{"code": "token_scope", "message": "API token scope does not allow this action"}

Что недоступно даже с полным доступом

Восемь методов работают только из панели под учётной записью владельца установки. С токеном они отвечают 403 с кодом forbidden:

  • резервные копии — GET и POST /api/v1/backups;
  • обновления — GET и POST /api/v1/updates;
  • активация лицензии — POST /api/v1/license/activate;
  • IP2Proxy — GET и PUT /api/v1/ip2proxy, POST /api/v1/ip2proxy/update.

Подробнее — на странице Admin API: лицензия, копии и обновления.

Ограничения доступа «Сводные отчёты»

Токен reports:read строит только сводные отчёты. Разрешённые поля:

  • объекты, в группировках и фильтрах: campaign, stream, offer, lander, source, campaign_group;
  • гео и устройство, в группировках и фильтрах: country, region, city, device, os, os_version, browser, browser_version, device_model, lang, connection, isp;
  • признаки, в группировках и фильтрах: bot, unique, cloak, proxy, empty_referer;
  • время, только в группировках: hour, day, week, month, year, dow, hour_of_day;
  • тип адреса, только в фильтрах: ipv4, ipv6.

В фильтрах дополнительно разрешены базовые метрики, например clicks или roi. На список метрик в поле metrics ограничение не распространяется.

Группировки и фильтры по sub_id_1–sub_id_30, ip, user_agent, referer, click_id, subid, external_id, creative_id, keyword, ad_campaign_id, adset_name, ad_name запрещены. Ответ на такой отчёт — код 403:

json
{"code": "token_scope", "message": "report includes fields outside the aggregate report scope"}

Журналы кликов, фоновые выгрузки и сохранённые отчёты этому токену недоступны.

Доступ «Расходы расширения»

Токен spend:write выпускается только на платной лицензии. На пробной лицензии создание ключа и все методы /api/v1/spend отвечают кодом 403:

json
{"code": "spend_paid_required", "message": "Расширение для расходов доступно после оплаты лицензии."}

Методы расходов описаны на странице Admin API: расходы.

Срок действия

  • В панели срок выбирается из четырёх значений: 7, 30, 90 или 365 дней.
  • При создании через API срок задаётся полем expires_at. Дата должна быть в будущем и не дальше 365 суток от момента запроса. Иначе сервер отвечает кодом 422 с сообщением expires_at must be in the next 365 days. Без этого поля токен действует 90 суток.
  • В списке у действующего токена стоит «До» и дата, у просроченного — «Истёк» и дата.
  • После окончания срока запросы получают 401 с сообщением invalid api key. Продлить токен нельзя — создайте новый.
  • У токена с пометкой «Без срока · старый токен» срок не задан. Он действует, пока его не отзовут.

Чтобы отозвать токен, нажмите значок ✕ в его строке и подтвердите действие. Отзыв действует сразу.

Истёкшая лицензия

Когда лицензия неактивна, запросы с токеном получают код 402:

json
{"code": "license_required", "message": "Доступ к трекеру закрыт до продления лицензии. Трафик и приём конверсий работают, исходящие события ожидают продления."}

Исключение — GET /api/v1/license: по токену Полный доступ он продолжает отдавать состояние лицензии. По нему интеграция может отличить неактивную лицензию от сбоя.

Приём постбеков и лидов по адресам /api/v1/postback, /api/v1/lead и /api/v1/lead-file не останавливается. Что ещё работает и что закрыто — на странице Истечение лицензии.

Доступ проверяется раньше лицензии: токен, которому метод не разрешён, получит 403, а не 402.

Ограничения частоты

Общего лимита на запросы с токеном нет. Ограничены отдельные методы:

МетодЛимитОтвет при превышении
POST /api/v1/spend/snapshots120 запросов в минуту с одного IP429, код rate_limited
POST /api/v1/blocklist-sources/{id}/check, POST /api/v1/blocklist-sources/test10 запросов в минуту с одного IP, счётчик общий для обоих методов429, код rate_limited
POST /api/v1/domains/{id}/verify20 проверок в минуту на всю команду429, код rate_limit
POST /api/v1/report-exports2 активные выгрузки на пользователя и 20 сохранённых на команду429, код export_quota

При кодах rate_limited и rate_limit подождите минуту и повторите запрос. При коде export_quota дождитесь окончания активных выгрузок или удалите ненужные.

Вызовы из браузера

Отправляйте запросы к Admin API со своего сервера. В заголовке Access-Control-Allow-Origin трекер отдаёт адрес панели, поэтому скрипт на другом сайте получит в браузере ошибку CORS.

В ответах указаны разрешённые методы — GET, POST, PUT, DELETE, OPTIONS — и заголовки — Authorization, Content-Type, Api-Key.

Совет.

Не вставляйте токен в код страниц и лендингов: его увидит любой посетитель. Держите токен на своём сервере или в сервисе автоматизации.

Журнал действий

В журнал Логи → Audit log попадают запросы с действующим токеном, отправленные методами POST, PUT, PATCH и DELETE, включая построение отчёта через POST /api/v1/reports. Запросы GET в журнал не записываются.

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

Как читать журнал — на странице Audit log: журнал действий пользователей.

Если не получилось

invalid api key

Токен введён с ошибкой, отозван, истёк, либо его создатель удалён или больше не владелец и не администратор. Откройте Настройки → API и сравните начало токена со строками списка. Токен должен быть в списке со сроком «До» или с пометкой «Без срока · старый токен». Если токена нет или стоит «Истёк», создайте новый.

API token scope does not allow this action

Метод не входит в доступ токена. Сверьтесь с таблицей в разделе Виды доступа и создайте токен с нужным доступом. Изменить доступ у готового токена нельзя.

missing bearer token

В запросе нет заголовка Api-Key или его значение пустое. Проверьте имя заголовка и значение токена.

Доступ к трекеру закрыт до продления лицензии

Лицензия неактивна: истёк срок, лицензия отозвана или не подтверждена. Порядок продления — на странице Продление и заказы. После продления токены, у которых не вышел срок, продолжат работать.

Обновлено Нужна помощь? ↗