Public API

Public API v1 даёт программный доступ к кампаниям, офферам, flow, отчётам и постбэкам. Токены и схема — в Settings → Access & security → API Tokens. В production интерактивный Swagger UI (/api/docs) отключён: скачайте OpenAPI JSON или Postman collection кнопкой API Docs на этой же странице.

API Docs
Settings → API Tokens → API Docs: Download OpenAPI / Postman.
API Tokens
Список токенов и кнопка Create token.

Назначение

Автоматизация CRUD, выгрузка отчётов во внешние системы, server-side постбэки из CRM. UI остаётся для операторов; API — для скриптов и интеграций.

Предварительные условия

  • Доступ к /settings?tab=api-tokens.
  • Понимание RBAC: токену выдайте минимально нужные ресурсы (campaigns, offers, reports… или * только осознанно).

Как открыть и получить схему

  1. Settings → Access & security → API Tokens (/settings?tab=api-tokens).
  2. Нажмите API Docs → Download OpenAPI spec (JSON) или Download Postman collection. Файлы отдаются через authenticated admin API — это ожидаемый путь в production.
  3. Не ищите публичный Swagger на /api/docs: в production он отключён (JSON {"error":"Not found"}). Импортируйте OpenAPI в Postman / Insomnia / IDE.

Аутентификация и первый запрос

  1. Создайте токен (+ Create token) с минимальным набором resources и скопируйте секрет сразу — повторно он может быть недоступен.
  2. Заголовок: Authorization: Bearer <token>.
  3. Проверьте простой запрос, например GET /api/v1/campaigns (curl или импортированная коллекция).
  4. Для отчётов: POST /api/v1/reports с телом периода/groupings по вашему OpenAPI — не копируйте устаревшие примеры с другого сервера.
  5. Для server-side конверсий: GET /api/v1/postback с clickid, payout, status (и другими полями по схеме).

Основные endpoints

РесурсМетод / путь
Campaigns/api/v1/campaigns (GET, POST, PUT, PATCH, DELETE)
Offers/api/v1/offers
Flow/api/v1/campaigns/:id/flow (GET, PUT)
ReportsPOST /api/v1/reports
PostbackGET /api/v1/postback
Check URLPOST /api/v1/campaigns/:id/check-url
Traffic sources/api/v1/sources и alias /api/v1/traffic-sources

Полные схемы полей, enum и примеры тел — в скачанном OpenAPI этого инстанса. Файл с другого сервера может отличаться по версии.

Лимиты и ошибки

  • Rate limit по умолчанию ~300 req/min (env API_V1_RATE_LIMIT_PER_MIN). Это лимит Public API, не путать с UI-лимитами click/track в Settings → General и не с DDoS clicks/sec в Fraud Score.
  • При 429 снизьте частоту запросов, добавьте backoff; не крутите плотный polling отчётов каждую секунду.
  • Ошибки JSON с полями error и code — читайте code перед повторной попыткой.

Практика безопасности и сценарии

Разные токены для разных интеграций (CRM postback, BI reports, внутренний скрипт). При утечке — отзовите токен в API Tokens и создайте новый. Не логируйте полный Bearer в CI. Для postback из CRM ограничивайте IP на стороне сети, если возможно, и всегда передавайте корректный clickid — иначе конверсия не привяжется к клику (сверяйте в Logs).

  • Ночной отчёт в BI: один POST /reports по расписанию с тем же period/groupings, что у UI-preset.
  • CRM → sale: GET postback с clickid/status/payout → проверка в Logs → Conversions.
  • Автосоздание офферов: POST /offers с токеном, у которого есть только нужные права write.

Устранение неполадок

  • 401/403 — токен отозван, скопирован с пробелом, или RBAC не покрывает ресурс.
  • /api/docs отдаёт Not found — нормально в production; используйте API Docs → Download OpenAPI.
  • Пустой отчёт через API при живых данных в UI — сверьте period/timezone и тело запроса со схемой.
  • Postback принят, конверсии нет — неверный clickid или status; смотрите Logs → Postbacks/Conversions.

Частые ошибки

  • Хранить токен в публичном репозитории.
  • Путать лимит API (~300) с лимитами трекинга кликов.
  • Ждать интерактивный Swagger на /api/docs в production.
  • Выдать токену * «на всякий случай» вместо минимального RBAC.