Как я связал Telegram-бота RefCash с партнёрскими сетями: ссылки, postback и начисления

TL;DR: Я собираю RefCash — Telegram-бота, который выдаёт пользователю персональную партнёрскую ссылку, принимает уведомление от рекламной сети и начисляет вознаграждение. Интерфейс здесь — самая простая часть. Главные сложности начинаются между кликом и выплатой: нужно не потерять Telegram ID, привести разные статусы партнёров к единому виду и не начислить деньги дважды.

Зачем вообще связывать Telegram-бота с партнёрскими сетями

Обычная партнёрская ссылка неудобна, если вокруг неё строится сервис. Пользователь переходит по ссылке, выполняет условие, рекламная сеть фиксирует действие — но сам пользователь не понимает, засчиталось оно или нет. Ему приходится ждать отчёт или писать в поддержку.

В RefCash я хочу сделать путь короче и понятнее:

1. Пользователь выбирает предложение в Telegram.
2. Бот создаёт персональную ссылку.
3. В ссылку добавляется Telegram ID пользователя.
4. Партнёрская сеть возвращает этот ID в postback-уведомлении.
5. Бот сохраняет конверсию, обновляет баланс и присылает сообщение.

В идеальном сценарии всё выглядит почти мгновенно: «действие подтверждено — начислено 1 500 ₽». Но за одной строкой в Telegram стоит несколько независимых систем, каждая со своими параметрами, статусами и правилами.

Как устроена схема RefCash

Этап	Что происходит	Что может сломаться
Выбор оффера	Бот показывает предложение, условия и размер вознаграждения	Устаревшее описание или неверная выплата
Создание ссылки	К адресу партнёра добавляется идентификатор пользователя	ID теряется при редиректе
Целевое действие	Клиент оформляет заявку, карту, счёт или другую услугу	Сеть не связывает действие с исходным кликом
Postback	Сеть вызывает специальный адрес RefCash и передаёт статус	Другие названия полей, повторный запрос, неверная подпись
Начисление	Система записывает конверсию и меняет баланс	Двойная выплата или начисление неподтверждённой заявки
Уведомление	Бот сообщает пользователю результат	Telegram временно недоступен, хотя начисление уже прошло

Персональная ссылка: простой принцип, много нюансов

Чтобы понять, кому начислять вознаграждение, RefCash передаёт Telegram ID в дополнительном параметре ссылки. У разных сетей он может называться sub1, clickid, custom или иначе.

Условный адрес выглядит так:

https://partner.example/offer?sub1=123456789

Число в конце — не сумма и не номер оффера, а идентификатор пользователя. Когда партнёр сообщает о результате, этот идентификатор должен вернуться обратно. Если он потеряется на одном из редиректов, конверсия останется без владельца.

Поэтому мало увидеть, что ссылка открывается. Нужен полный тест: открыть ссылку, пройти целевое действие, дождаться изменения статуса и проверить, какой набор полей реально пришёл на сервер.

Почему postback важнее красивого меню

Postback — это HTTP-запрос от партнёрской сети к RefCash. Он сообщает примерно следующее: пользователь с таким идентификатором выполнил действие по такому офферу, текущий статус — подтверждён, выплата — столько-то рублей.

Снаружи все сети решают одну задачу, но говорят на разных диалектах. Одна передаёт выплату в поле amount, другая — в profit. Где-то подтверждение называется approved, где-то confirmed, а где-то приходит русское значение «подтверждён».

Правильная архитектура не должна размазывать эти различия по всему боту. На входе значения приводятся к единому формату:

• pending — заявка получена, но ещё проверяется;
• approved — действие подтверждено и может быть оплачено;
• declined — действие отклонено;
• cancelled — ранее созданная конверсия отменена.

После такой нормализации Telegram-боту уже не нужно знать особенности каждой сети. Он работает с одной моделью данных.

Самая опасная ошибка — повторное начисление

Партнёрская сеть имеет право повторить postback, если не получила ответ вовремя. Запрос также могут отправить вручную при диагностике. Если обработчик устроен по принципу «пришёл статус approved — прибавить сумму к балансу», один и тот же лид способен пополнить баланс несколько раз.

Защита называется идемпотентностью: повторная обработка одного события не должна менять итог. Для этого у конверсии сохраняется внешний уникальный идентификатор, а в базе ставится ограничение уникальности по сети и номеру конверсии.

network + conversion_id = уникальное событие

Перед начислением система проверяет:

1. Есть ли такая конверсия в базе.
2. Какой статус был сохранён раньше.
3. Было ли уже выполнено начисление.
4. Совпадает ли новая сумма с ожидаемой.

Баланс и отметку о начислении лучше обновлять в одной транзакции. Тогда сбой между двумя запросами не оставит систему в состоянии «деньги добавили, а событие не отметили».

Postback нельзя оставлять открытым

Адрес обработчика доступен из интернета, поэтому доверять каждому входящему запросу нельзя. Минимальная защита — секретный токен в URL или заголовке. Лучше — проверка криптографической подписи, если партнёрская сеть её поддерживает.

Также нужны:

• проверка допустимых статусов и числовых значений;
• журнал входящих событий без публикации персональных данных;
• ограничение частоты запросов;
• оповещение при серии ошибок;
• секреты в переменных окружения, а не в исходном коде;
• отдельный тестовый режим без изменения реального баланса.

Что уже работает в RefCash

На текущем этапе Telegram-бот показывает каталог предложений, создаёт персональные ссылки и хранит их в базе. Отдельный сервис принимает postback-запросы нескольких партнёрских сетей. Реализованы сохранение конверсий, статистика пользователя, уведомления и сценарий подачи заявки на расчётный счёт.

Но я не считаю интеграцию завершённой только потому, что сервер отвечает «OK». До подключения реального денежного потока необходимо проверить цепочку на тестовых конверсиях и закрыть два критичных места: защиту от повторных начислений и проверку подлинности запросов.

Это важный урок build-in-public: работающий интерфейс — ещё не работающий финансовый продукт. Пока не проверены повторы, переходы статусов и восстановление после ошибок, система остаётся прототипом.

Чек-лист перед запуском реальных начислений

1. Получить точную документацию postback для каждой сети.
2. Настроить секрет или проверку подписи.
3. Передавать Telegram ID через рекомендованное sub-поле.
4. Сохранять внешний ID каждой конверсии.
5. Добавить уникальность и идемпотентную обработку.
6. Привести статусы всех сетей к общей модели.
7. Проверить переходы pending → approved и pending → declined.
8. Повторить один postback и убедиться, что баланс не изменился второй раз.
9. Проверить статистику и уведомление в Telegram.
10. Настроить резервное копирование базы и мониторинг ошибок.

Что дальше

Следующий этап — сделать обработку конверсий идемпотентной, вынести секреты из кода и провести сквозной тест для каждой подключённой сети. После этого можно подключать реальные postback-адреса и смотреть не только на технический ответ сервера, но и на весь путь пользователя: ссылка → заявка → подтверждение → баланс → уведомление.

Ранее я уже рассказывал, как автоматизировал Telegram-канал с помощью AI, и разбирал, почему автоматизация иногда останавливается. RefCash продолжает ту же линию: автоматизировать можно многое, но финансовые действия требуют проверок, журналов и понятной точки ручного контроля.

---

Автор: Denis | Дата: 2026-08-15
Build-in-public: практический дневник разработки RefCash и экосистемы DenisVK.