Войти Заработать
Главная Документация API

API Reference

REST-API для интеграции: создание кампаний, креативов, получение статистики, S2S-postback.

Содержание

  1. Аутентификация
  2. Кампании (advertiser)
  3. Креативы
  4. Сайты (publisher)
  5. Блоки (publisher)
  6. Статистика
  7. S2S postback - входящий
  8. S2S postback - исходящий
  9. OpenRTB 2.5 (для DSP)
  10. Widget endpoints
  11. VAST 4.0
  12. Rate limits и ошибки

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

Базовый URL:https://sladu.net

API использует Bearer-токены (Laravel Sanctum). Получить токен:

POST /api/auth/token
Content-Type: application/json

{ "email": "you@example.com", "password": "your-password" }

→ 200 OK
{ "token": "1|abc...xyz", "user": { "id": 42, "role": "advertiser" } }

Все последующие запросы:

Authorization: Bearer 1|abc...xyz
Accept: application/json

2. Кампании (advertiser)

Список кампаний

GET /api/adv/campaigns
→ 200 OK
{
  "campaigns": [
    {
      "id": 7, "name": "Casino RU CPM",
      "vertical": "gambling", "format": "native",
      "bid_type": "cpm", "bid_micro_cents": 200000,
      "status": "active",
      "daily_budget_cents": 5000,
      "daily_spent_cents": 1234,
      "created_at": "2026-06-15T12:00:00Z"
    }
  ]
}

Создать кампанию

POST /api/adv/campaigns
{
  "name": "Casino RU CPM",
  "vertical": "gambling",
  "format": "native",
  "bid_type": "cpm",
  "bid_usd": 2.0,
  "daily_budget_usd": 50,
  "geo_include": ["ru","ua","kz"],
  "languages": ["ru"]
}

→ 201 Created
{ "id": 8, "name": "Casino RU CPM", "status": "draft", ... }

Активировать / приостановить

POST /api/adv/campaigns/{id}/activate
POST /api/adv/campaigns/{id}/pause

3. Креативы

Добавить креатив

POST /api/adv/campaigns/{campaign_id}/creatives
Content-Type: multipart/form-data

title=Получи $50 бонус
body=Регистрация за 1 минуту...
landing_url=https://your-offer.com/?sub1={click_id}
image=@banner.jpg          # файл, для не-video
video_url=https://cdn.../ad.mp4   # для video / floating_video
cta_text=Зарегистрироваться
orientation=vertical       # для floating_video

→ 201 Created
{
  "id": 42, "status": "pending_moderation",
  "tracking_token": "tt_video_xyz",
  "moderation_eta_seconds": 120
}

AI-генерация заголовков (Claude)

POST /api/adv/campaigns/{id}/ai-generate
{
  "offer": "Казино с бонусом 5000₽ на первый депозит",
  "cta": "Зарегистрироваться",
  "geo": "RU", "lang": "ru"
}

→ 200 OK
{
  "variants": [
    { "title": "...", "body": "...", "hook_type": "fear" },
    { "title": "...", "body": "...", "hook_type": "curiosity" },
    ... (8 шт)
  ],
  "image_prompts": [
    { "prompt": "...", "style": "photoreal" },
    ... (4 шт)
  ],
  "usage": { "input_tokens": 350, "output_tokens": 1200 }
}

HeyGen AI-видео

POST /api/adv/heygen/generate
{
  "campaign_id": 7,
  "avatar_id": "Anna_public_3_20240108",
  "voice_id": "...",
  "script": "Привет! 👋 Если ты ищешь...",
  "language": "ru",
  "orientation": "vertical"
}

→ 200 OK
{ "ok": true, "job_id": 123, "status": "processing", "cost_cents": 100 }

GET /api/adv/heygen/status/{job_id}
→ 200 OK
{ "status": "completed", "video_url": "https://...", "duration_sec": 18 }

4. Сайты (publisher)

Добавить сайт

POST /api/pub/sites
{
  "domain": "example.com",
  "category": "adult_video",      # см. /pub/sites/create - 29 категорий
  "language": "ru",
  "traffic_estimate_daily": 50000
}

→ 201 Created
{
  "id": 42,
  "domain": "example.com",
  "verification_code": "SLADU-XYZ123ABC",
  "status": "draft"
}

Проверить владение

POST /api/pub/sites/{id}/verify

→ 200 OK
{ "ok": true, "method": "meta", "status": "pending_review" }

# Если не нашли код - 422:
{ "ok": false, "error": "Не нашли verification code на странице..." }

5. Блоки (publisher)

Создать блок

POST /api/pub/zones
{
  "site_id": 42,
  "name": "Главная боковая",
  "format": "floating_video",
  "fv_corner": "br",          # br/bl/tr/tl
  "fv_delay_sec": 3,
  "fv_freq_cap_hours": 6,
  "banner_width": 320,
  "banner_height": 568
}

→ 201 Created
{
  "id": 100,
  "subid": "abc12345",
  "widget_url": "https://sladu.net/w/abc12345.js",
  "vast_url": "https://sladu.net/vast/abc12345.xml",   # только для video
  "status": "active"
}

6. Статистика

GET /api/adv/stats?from=2026-06-01&to=2026-06-23&group_by=day,campaign

→ 200 OK
{
  "rows": [
    {
      "date": "2026-06-23", "campaign_id": 7,
      "impressions": 12500, "clicks": 142, "ctr": 1.14,
      "spent_cents": 2500, "conversions": 8,
      "ecpa_cents": 312
    },
    ...
  ]
}

Доступные группировки:day, hour, campaign, creative, geo, device, site, zone.

7. S2S postback - входящий (от твоего трекера к нам)

Когда у тебя в трекере (Voluum, BeMob, RedTrack, Keitaro) фиксируется конверсия - дай этот URL с макросами:

https://sladu.net/postback/in?secret=ABC123&click_id={click_id}&payout=500&status=approved&txid={tx_id}

Параметры:

  • secret- из/cabinet/profile → «Postback secret»
  • click_id- тот UUID который мы передали вlanding_urlчерез макрос{click_id}
  • payout- сумма конверсии вцентах (500 = $5)
  • status - approved / pending / rejected
  • txid- уникальный ID транзакции (дедупликация)
  • sig(опционально, но рекомендуется) - HMAC-подпись

HMAC подпись (защита от подделок)

Формула:

payload = "{click_id}|{payout}|{status}|{txid}"
sig = hash_hmac('sha256', payload, secret)

Пример (PHP):

$secret = 'ABC123';
$payload = $clickId . '|' . $payout . '|' . $status . '|' . $txid;
$sig = hash_hmac('sha256', $payload, $secret);
$url = "https://sladu.net/postback/in?secret={$secret}&click_id={$clickId}&payout={$payout}&status={$status}&txid={$txid}&sig={$sig}";

Без sig - принимаем (обратная совместимость), но в лог логируем warning. С sig - проверяем точное совпадение.

8. S2S postback - исходящий (от нас к тебе)

В/cabinet/profileукажи URL шаблон, например:

https://your-tracker.com/postback?cid={click_id}&payout={payout_cents}&status={status}&geo={geo}&device={device}

Доступные макросы:

  • {click_id}- UUID клика
  • {payout_cents}- сумма конверсии
  • {status} - approved/pending/rejected
  • {geo}- ISO-код страны
  • {device} - desktop/mobile/tablet
  • {os}, {browser}, {vertical}, {campaign_id}

Постбэк дёргается с retry-логикой: до 5 попыток с exponential backoff (5s, 30s, 5min, 30min, 2h). Если все провалились - конверсия помечается какpostback_failed, продолжаем считать в наших метриках.

9. OpenRTB 2.5 (для DSP-партнёров)

Sladu выступает какSSPдля внешних DSP. Каждый показ - аукцион. Если ты хочешь подключить свой DSP к нашим показам - вот endpoint:

POST https://sladu.net/openrtb/bid
Content-Type: application/json
x-openrtb-version: 2.5

{
  "id": "bid-request-uuid",
  "imp": [{
    "id": "1",
    "bidfloor": 0.5,
    "banner": { "w": 300, "h": 250 },
    ...
  }],
  "site": { "domain": "publisher.com", "cat": ["IAB7"] },
  "device": { "ua": "...", "ip": "1.2.3.4", "geo": { "country": "RU" } },
  "user": { "id": "hashed-cookie-id" }
}

← 200 OK
{
  "id": "bid-request-uuid",
  "seatbid": [{
    "bid": [{
      "id": "1",
      "impid": "1",
      "price": 1.5,
      "adm": "...creative HTML...",
      "nurl": "https://your-dsp/win-notify?...",
      "crid": "creative-id"
    }]
  }]
}

Тайм-аут аукциона - 200мс. QPS-лимит индивидуален (по дефолту 100 req/sec, увеличиваем после прохождения интеграционных тестов).

Для подключения - напиши вdsp@sladu.net, мы дадим IP whitelist и тестовый endpoint.

10. Widget endpoints (для разработчиков)

Это эндпоинты которые дёргает наш JS-виджет на сайтах вебмастеров. Понадобится если будешь делать кастомного клиента:

  • GET /w/{subid}.js- сам виджет (JavaScript)
  • GET /imp?z={subid}&fp={fingerprint}⊥={signals}- запрос на показ, возвращает JSON с креативом
  • GET /c/{impression_id}/{tracking_token}?ttc=&x=&y=&focus=&fp=⊥=- клик-трекинг, редирект на landing
  • GET /vast/{subid}.xml- VAST 4.0 XML для video формата
  • POST /push/subscribe- подписка на web-push
  • GET /openrtb/imptracker/{imp_id} - VAST impression pixel

12. Rate limits и ошибки

Rate limits

  • API общий:60 req/minна токен
  • AI-генерация креативов:1 в 30 сек(Claude дорогой)
  • HeyGen generation: 1 в 5 секна пользователя
  • OpenRTB /bid: индивидуально, см.раздел 9

Превышение - HTTP 429 + заголовокRetry-Afterв секундах.

Коды ответов

  • 200 OK- всё хорошо
  • 201 Created- ресурс создан
  • 400 Bad Request- ошибка валидации, в теле{"errors": {...}}
  • 401 Unauthorized- токен невалидный / отсутствует
  • 402 Payment Required- закончились деньги (для AI-операций)
  • 403 Forbidden- нет прав (чужой ресурс)
  • 404 Not Found- ресурс не существует
  • 429 Too Many Requests - rate limit
  • 500 Internal Server Error- наша ошибка, пиши в саппорт

Вопросы по API - в Telegram @sladu_supportили наapi@sladu.net. Тестовый стенд / sandbox -sandbox.sladu.net (по запросу).