[{"data":1,"prerenderedAt":12},["ShallowReactive",2],{"cms-article-kb-all-public-api":3},{"id":4,"type":5,"title":6,"slug":7,"body":8,"category":9,"pinned":10,"published_at":11},"4bfd0a61-cacd-4bca-9a60-85a0c9ffc0cf","kb","Публичный API и вебхуки","kb-all-public-api","Платформа предоставляет публичный API для чтения данных (офферы, статистика, конверсии) и вебхуки — уведомления о конверсиях на ваш сервер. Подходит для интеграции с вашими системами аналитики и BI.\n\n═══ Доступ ═══\nAPI-ключи выдаёт администратор платформы — напишите в поддержку или своему менеджеру, укажите, какие данные нужны (статистика \u002F офферы \u002F конверсии). Ключ показывается ОДИН раз при создании — сохраните его в надёжном месте, повторно его узнать нельзя (только перевыпустить).\n\nБазовый адрес: https:\u002F\u002Fapi.traffo.ru\n\n═══ Авторизация ═══\nКлюч передаётся в заголовке:\n  Authorization: Bearer ak_live_ВАШ_КЛЮЧ\n\nЛимит запросов: 1000 в час на ключ. При превышении — ответ 401\u002F403 для неверного ключа и 429 при превышении лимита (с полем retry_after_seconds).\n\nСкоупы (права ключа): stats:read, offers:read, conversions:read. Ключ работает только в рамках выданных прав; запрос вне скоупа вернёт 403.\n\n═══ Эндпоинты (чтение) ═══\n\n1) Офферы — GET \u002Fapi\u002Fv1\u002Fpublic\u002Fv1\u002Foffers   (право offers:read)\n   Ответ: { \"items\": [ { \"id\", \"name\", \"vertical\", \"geos\": [\"RU\", ...], \"payoutModel\": \"cpa|cpl|cps|cpi|revshare|hybrid\" } ] }\n\n2) Сводная статистика — GET \u002Fapi\u002Fv1\u002Fpublic\u002Fv1\u002Fstats   (право stats:read)\n   Ответ: { \"reporting_currency\": \"RUB\", \"reporting_timezone\", \"today\", \"yesterday\", \"last_7_days, ... }\n   Каждый период: { \"clicks\", \"unique_visitors\", \"conversions\", \"cr\" (0..1), \"epc\", \"revenue_gross\", \"hold_amount\", \"approved_amount\", \"rejected_amount\" }. Денежные поля — строки.\n\n3) Последние конверсии — GET \u002Fapi\u002Fv1\u002Fpublic\u002Fv1\u002Fconversions?limit=50   (право conversions:read)\n   limit: 1..200 (по умолчанию 50).\n   Ответ: { \"items\": [ { \"conversion_id\", \"ts\" (ISO), \"offer_id\", \"transaction_id\", \"payout\", \"currency\", \"platform_status\": \"pending|approved|rejected|reversed\", \"country\" } ] }\n\n═══ Пример запроса ═══\n  curl -H \"Authorization: Bearer ak_live_ВАШ_КЛЮЧ\" \\\n       \"https:\u002F\u002Fapi.traffo.ru\u002Fapi\u002Fv1\u002Fpublic\u002Fv1\u002Fconversions?limit=20\"\n\n═══ Вебхуки (уведомления о конверсиях) ═══\nВместо периодического опроса конверсий можно получать их push-уведомлением. Эндпоинт вебхука (ваш URL + список событий) регистрирует администратор платформы; вам выдаётся СЕКРЕТ вебхука (тоже показывается один раз) — он нужен для проверки подписи.\n\nСобытия: conversion.approved, conversion.rejected, conversion.reversed.\n\nДоставка: POST на ваш URL (только HTTPS), заголовки:\n  Content-Type: application\u002Fjson\n  X-Webhook-Event: conversion.approved\n  X-Webhook-Signature: sha256=ПОДПИСЬ\n\nТело запроса:\n  {\n    \"event\": \"conversion.approved\",\n    \"delivered_at\": \"2026-06-04T10:00:00.000Z\",\n    \"data\": {\n      \"conversion_id\": \"...\",\n      \"offer_id\": \"...\",\n      \"affiliate_id\": \"...\",\n      \"payout\": \"100.0000\",\n      \"currency\": \"RUB\"\n    }\n  }\n\n═══ Проверка подписи (ОБЯЗАТЕЛЬНО) ═══\nПодпись = HMAC-SHA256 от СЫРОГО тела запроса (ровно те байты, что пришли — не пересобирайте JSON заново) с вашим секретом, в hex. Сравните со значением заголовка X-Webhook-Signature после префикса \"sha256=\".\n\nПример на Node.js:\n  import { createHmac } from \"crypto\";\n  const expected = createHmac(\"sha256\", WEBHOOK_SECRET).update(rawBody).digest(\"hex\");\n  const received = req.headers[\"x-webhook-signature\"].replace(\"sha256=\", \"\");\n  const ok = expected === received;   \u002F\u002F если false — отклоните запрос\n\nНикогда не доверяйте телу вебхука без проверки подписи.\n\n═══ Повторные доставки ═══\nЕсли ваш сервер не ответил 2xx, доставка повторяется до 6 раз с нарастающей задержкой. Отвечайте быстро (в пределах ~30 секунд) статусом 2xx; ошибки 4xx считаются окончательными (без повторов), 5xx и таймауты — повторяются. Обрабатывайте возможные дубли по conversion_id идемпотентно.\n\nВопросы по интеграции — через поддержку.","API",false,"2026-06-04T12:34:30.322Z",1781196005080]