Публичный API и вебхуки

Платформа предоставляет публичный API для чтения данных (офферы, статистика, конверсии) и вебхуки — уведомления о конверсиях на ваш сервер. Подходит для интеграции с вашими системами аналитики и BI.

═══ Доступ ═══ API-ключи выдаёт администратор платформы — напишите в поддержку или своему менеджеру, укажите, какие данные нужны (статистика / офферы / конверсии). Ключ показывается ОДИН раз при создании — сохраните его в надёжном месте, повторно его узнать нельзя (только перевыпустить).

Базовый адрес: https://api.traffo.ru

═══ Авторизация ═══ Ключ передаётся в заголовке: Authorization: Bearer ak_live_ВАШ_КЛЮЧ

Лимит запросов: 1000 в час на ключ. При превышении — ответ 401/403 для неверного ключа и 429 при превышении лимита (с полем retry_after_seconds).

Скоупы (права ключа): stats:read, offers:read, conversions:read. Ключ работает только в рамках выданных прав; запрос вне скоупа вернёт 403.

═══ Эндпоинты (чтение) ═══

1) Офферы — GET /api/v1/public/v1/offers (право offers:read) Ответ: { "items": [ { "id", "name", "vertical", "geos": ["RU", ...], "payoutModel": "cpa|cpl|cps|cpi|revshare|hybrid" } ] }

2) Сводная статистика — GET /api/v1/public/v1/stats (право stats:read) Ответ: { "reporting_currency": "RUB", "reporting_timezone", "today", "yesterday", "last_7_days, ... } Каждый период: { "clicks", "unique_visitors", "conversions", "cr" (0..1), "epc", "revenue_gross", "hold_amount", "approved_amount", "rejected_amount" }. Денежные поля — строки.

3) Последние конверсии — GET /api/v1/public/v1/conversions?limit=50 (право conversions:read) limit: 1..200 (по умолчанию 50). Ответ: { "items": [ { "conversion_id", "ts" (ISO), "offer_id", "transaction_id", "payout", "currency", "platform_status": "pending|approved|rejected|reversed", "country" } ] }

═══ Пример запроса ═══ curl -H "Authorization: Bearer ak_live_ВАШ_КЛЮЧ" \ "https://api.traffo.ru/api/v1/public/v1/conversions?limit=20"

═══ Вебхуки (уведомления о конверсиях) ═══ Вместо периодического опроса конверсий можно получать их push-уведомлением. Эндпоинт вебхука (ваш URL + список событий) регистрирует администратор платформы; вам выдаётся СЕКРЕТ вебхука (тоже показывается один раз) — он нужен для проверки подписи.

События: conversion.approved, conversion.rejected, conversion.reversed.

Доставка: POST на ваш URL (только HTTPS), заголовки: Content-Type: application/json X-Webhook-Event: conversion.approved X-Webhook-Signature: sha256=ПОДПИСЬ

Тело запроса: { "event": "conversion.approved", "delivered_at": "2026-06-04T10:00:00.000Z", "data": { "conversion_id": "...", "offer_id": "...", "affiliate_id": "...", "payout": "100.0000", "currency": "RUB" } }

═══ Проверка подписи (ОБЯЗАТЕЛЬНО) ═══ Подпись = HMAC-SHA256 от СЫРОГО тела запроса (ровно те байты, что пришли — не пересобирайте JSON заново) с вашим секретом, в hex. Сравните со значением заголовка X-Webhook-Signature после префикса "sha256=".

Пример на Node.js: import { createHmac } from "crypto"; const expected = createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex"); const received = req.headers["x-webhook-signature"].replace("sha256=", ""); const ok = expected === received; // если false — отклоните запрос

Никогда не доверяйте телу вебхука без проверки подписи.

═══ Повторные доставки ═══ Если ваш сервер не ответил 2xx, доставка повторяется до 6 раз с нарастающей задержкой. Отвечайте быстро (в пределах ~30 секунд) статусом 2xx; ошибки 4xx считаются окончательными (без повторов), 5xx и таймауты — повторяются. Обрабатывайте возможные дубли по conversion_id идемпотентно.

Вопросы по интеграции — через поддержку.