Введение

​

Base URL

https://studio-api.onlytraffic.com/api/external/v1

​

Аутентификация

curl https://studio-api.onlytraffic.com/api/external/v1/subscribers \
  -H "X-API-Key: your-api-key-here"

​

Лимиты запросов

​

Заголовки ответа (в каждом ответе, успешном или с ошибкой)

HTTP/1.1 200 OK
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1947
X-RateLimit-Reset: 1746453296
X-RateLimit-Tier: read

​

Когда лимит превышен

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again in 37 seconds.",
  "retry_after": 37
}

​

Пагинация

​

Постраничная (по умолчанию для заказов / кампаний)

{
  "pagination": {
    "page": 1,
    "total": 150,
    "total_pages": 2
  }
}

​

Курсорная (ленты большого объёма)

GET /api/external/v1/transactions?limit=50

{
  "data": [/* 50 rows, newest first */],
  "pagination": {
    "next_cursor": "eyJ0cyI6MTc0NjQ1MzI5NiwiaWQiOjk4NzY1fQ==",
    "has_next": true,
    "limit": 50
  }
}

GET /api/external/v1/transactions?limit=50&after=eyJ0cyI6MTc0NjQ1MzI5NiwiaWQiOjk4NzY1fQ==

• Стабильный порядок, даже когда между вызовами добавляются новые строки (постраничная пагинация сдвигалась бы).
• Нет счётчика total: курсорные ленты оптимизированы под частичное чтение, а не под подсчёт строк.
• O(1) на страницу независимо от того, как глубоко вы пролистали.

​

Повторы и идемпотентность

​

Одновременные изменения

​

Можно безопасно повторять

​

НЕЛЬЗЯ повторять вслепую

​

Рекомендуемый back-off

​

Пример: обработка 429

async function fetchWithRetry(url, options) {
  const res = await fetch(url, options);
  if (res.status !== 429) return res;
  const retryAfter = Number(res.headers.get('Retry-After')) || 5;
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  return fetch(url, options); // retry once
}

​

Формат ответа

{
  "success": true,
  "data": [ ... ],
  "pagination": { ... }
}

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable message"
}

​

Ответы на запись и эволюция схемы

​

Запись возвращает только id

{
  "success": true,
  "data": { "order_id": "cplo_xxxxxxx" }
}

• Эндпоинты загрузки изображений дополнительно возвращают thumbnail_url (подписанный URL на 3 дня), чтобы только что сохранённое изображение можно было показать без дополнительного вызова. Оригиналы остаются за обычным GET.
• Одноразовые секреты (открытый API-ключ, возвращаемый при создании ключа, токены верификации) появляются в data только в этом единственном ответе и документированы как «показывается один раз и больше никогда».

​

Политика эволюции схемы

• Настройте парсер так, чтобы он допускал лишние поля, а не отклонял их.
• Входные данные проверяйте строго, к выходным относитесь гибко.