API документация

Базовый URL: https://tovarkin.com/api
Авторизация: Authorization: Bearer <jwt_or_api_key>

Быстрый старт

Шаги интеграции
  1. Создайте API ключ в профиле (раздел API и Webhook).
  2. Получите tracking token партнёра.
  3. Отправляйте postback в /api/events с external_id.
  4. Проверяйте статусы в /api/status-center.

Ключевые endpoints

Tracking

GET /t/:token — фиксирует клик и делает redirect на целевую страницу.

Postback events

POST /api/events — создаёт lead/sale событие (идемпотентно по token + external_id).

Status center

GET /api/status-center — единый статус, причина, nextStep и retryAllowed.

Realtime

GET /api/realtime/stream — SSE-уведомления в реальном времени.

API keys

POST /api/me/api-key, GET /api/me/api-keys, PATCH /api/me/api-keys/:id/revoke

Пример запроса

curl -X POST "https://tovarkin.com/api/events" \
  -H "Content-Type: application/json" \
  -d "{\"token\":\"tk-xxxx\",\"event_type\":\"lead\",\"external_id\":\"order-123\",\"amount\":1500}"

Полная спецификация

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

JWT или API ключ в заголовке:

Authorization: Bearer <token>
Postback: структура payload
{
  "token": "tk-xxxx",
  "event_type": "lead",
  "amount": 1200,
  "currency": "RUB",
  "external_id": "order-100500",
  "source": "facebook",
  "subid1": "campaignA",
  "utm_source": "google",
  "utm_campaign": "spring_sale"
}

Событие идемпотентно по паре (trackingLinkId, external_id). Повторный postback не приводит к двойной оплате.

API v1 (versioned)
  • GET /api/v1/affiliate/events (scope: affiliate:events.read)
  • GET /api/v1/supplier/events (scope: supplier:events.read)
  • POST /api/v1/events (scope: events.write)
Affiliate endpoints
  • GET /api/affiliate/events
  • GET /api/affiliate/analytics-sources
  • POST /api/affiliate/events/:id/dispute
Supplier endpoints
  • GET /api/supplier/analytics-sources
  • GET /api/supplier/offers/:id/audit
  • GET /api/supplier/affiliate-participations
Admin endpoints
  • GET /api/admin/payouts/registry
  • GET /api/admin/payouts/export.csv
  • PATCH /api/admin/payouts/bulk-status
  • GET /api/admin/moderation/sla-summary
  • POST /api/admin/moderation/sla-ping
Коды ответов
  • 200 OK
  • 201 Created
  • 400 Validation error
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not found
  • 409 Conflict (idempotency/duplicate)
  • 500 Server error
Рекомендации по безопасности
  • Храните API ключи только в секретном хранилище.
  • Ротируйте ключи каждые 60-90 дней.
  • Сразу отзывайте ключ при подозрительной активности.
  • Включите 2FA для admin-аккаунтов.