INTEGRATION GUIDE

Один контракт.
Любая компания.

Подключите подтверждённые события вашего приложения к Online24. Банки, страховые и другие компании используют единый протокол.

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

1. Создайте карточку партнёра и ссылки приложений в кабинете.
2. В разделе «Интеграции» выпустите Sandbox-ключ. Сохраните секрет: он показывается один раз.
3. Настройте получение click_id через согласованный канал атрибуции.
4. Отправьте подписанное событие и проверьте журнал и отчёты в режиме Sandbox.
5. После проверки выпустите отдельный Production-ключ.

01 / Переходы и атрибуция

GET /go/{slug}?platform=android&campaign=telegram создаёт переход и перенаправляет на сохранённый адрес приложения. Параметр offer_id выбирает активное предложение этого партнёра.

В карточке партнёра можно задать URL атрибуции с {click_id}. Его точный домен должен быть включён оператором в REDIRECT_HOSTS. URL должен вести к согласованной системе атрибуции, которая сохраняет идентификатор и выбирает магазин приложения.

Событие подтверждается, если переход принадлежит партнёру, произошло после перехода в пределах окна события и не помечено как обращение бота. Неизвестный переход сохраняется со статусом review и не создаёт начисление.

02 / Подпись запроса

Секрет используется как строка в том виде, в котором вы получили его при создании. Подписывайте точные байты тела; изменение пробелов изменит подпись.

HMAC-SHA256(secret, timestamp + "." + raw_json_body)

X-Key-Id: key_example
X-Event-Timestamp: <Unix timestamp in seconds>
X-Signature: sha256=<lowercase hexadecimal digest>
Content-Type: application/json

Разница с серверным временем — не более 300 секунд. Максимальный размер тела — 64 КБ. Используйте HTTPS и синхронизацию часов.

Пример на PHP

03 / Отправка событий

{
  "event_id": "evt_unique_123",
  "click_id": "clk_received_from_attribution",
  "event_type": "registration_completed",
  "occurred_at": "2026-10-14T10:30:00Z",
  "external_customer_id": "opaque_customer_456",
  "external_reference": "opaque_application_789",
  "amount_minor": 0,
  "currency": "UZS"
}

event_id уникален в пределах партнёра. occurred_at — реальное время события, в ISO 8601 с часовым поясом. Суммы передаются целыми минимальными единицами (100 = 1 UZS / USD / EUR). Не передавайте ФИО, паспорт, телефон или кредитное досье. Непрозрачные внешние идентификаторы сохраняются как хеши с ключом.

Названия событий партнёра можно сопоставить с универсальными кодами. Суперадминистратор может добавить новое событие без изменения кода.

04 / Ответы и повторная отправка

{"accepted":true,"duplicate":false,"status":"confirmed","reason":"","event_id":"evt_unique_123"}

Повтор с тем же partner + event_id возвращает duplicate: true. Новое начисление не создаётся. Для повторов обновляйте timestamp и подпись, сохраняя event_id.

Отмена меняет статус исходного события и начисления на reversed. История сохраняется. Sandbox и Production используют общий namespace идентификаторов: не повторяйте тестовые event_id в боевых запросах.

05 / Mapping и собственные адаптеры

В настройках нового ключа укажите JSON-словарь внешних имён и внутренних кодов:

{"signed_up":"registration_completed","credit_paid":"loan_disbursed"}

Для нестандартных payload создайте PHP-класс, реализующий Online24\Integrations\Contracts\EventAdapter, и передайте его в Postback. Адаптер нормализует данные, а подпись, валидация, изоляция и начисления остаются в ядре. Произвольный PHP в кабинете не исполняется.

Получение событий по API

В кабинете суперадминистратор разрешает точный домен API в настройках и создаёт API-подключение: HTTPS endpoint, Bearer token, ключ своей компании и интервал. Ответ партнёра: {"events":[...],"next_cursor":"..."}, до 200 событий за страницу. Следующий запрос передаёт курсор в query-параметре cursor. Пустой next_cursor сохраняет прежний watermark.

Планировщик хостинга запускает php bankflow-private/bin/console.php integrations:sync. При ошибке курсор не продвигается; повторы проходят дедупликацию. Секрет Bearer шифруется. Частные, служебные и неглобальные IP запрещены; DNS фиксируется на запрос, HTTP-редиректы не разрешены.

CSV и ручная сверка

CSV-импорт доступен суперадминистратору в интеграциях: UTF-8, до 32 КБ, 200 событий. Есть предварительный просмотр и результат каждой строки. Обязательные колонки: event_id, event_type, occurred_at. Колонки остальных полей совпадают с Postback. Импорт использует выбранный ключ и ту же проверку атрибуции. В журнале конверсий событие review можно связать с реальным переходом компании или отклонить; решение и основание записываются в аудит.

06 / Безопасная проверка

Sandbox-ключ проходит те же проверки подписи и атрибуции. Тестовые конверсии видны только при выборе Sandbox и никогда не создают финансовые начисления. Секрет недоступен повторно; при утрате выпустите новый ключ и отзовите старый.

Журнал содержит результат проверки, время и key_id, без секрета и полного тела запроса. Активность каждого ключа видна в разделе интеграций.

07 / API Reference

Отчёты принимают from, to (YYYY-MM-DD), partner_id, mode, platform, source, campaign_id. Журнал конверсий также принимает status, event_code, page и per_page (1–200). Период задаётся в часовом поясе отчётности. Представитель партнёра всегда видит только свою компанию.

Административные изменения требуют сессию и X-CSRF-Token. Публичные API не используют сессионный доступ к данным партнёров. Новые несовместимые контракты получают новый путь версии.