Как подключить Telegram-бота, если оплата идёт на другой платформе

Что настроим

Партнёр делится ссылкой на вашего Telegram-бота. Бот запоминает код партнёра и создаёт заказ в Рефсейлс, а оплату принимает ваша платформа: школа, конструктор курсов или любой другой сервис. Когда вы убедились, что оплата прошла, бот одним запросом закрывает заказ, и партнёр получает вознаграждение. Продления подписки тоже засчитываются партнёру, даже без его кода.

Если платежи идут на ваш собственный счёт PayAnyWay, подтверждать оплату вручную не нужно. Для этого случая есть статья «Как подключить Telegram-бота к Рефсейлс».

Что нужно заранее

• Тариф «Оптимальный». API и вебхуки работают только на нём.

• Доступ владельца магазина: API-ключи и вебхуки настраивает только владелец.

• Разработчик бота. Ему понадобятся два запроса к API, примеры ниже.

Шаг 1. Добавьте товар

1. Откройте раздел «Товары/Услуги» и нажмите «Добавить».

2. Заполните «Название» и «Цена», например «Подписка на месяц» и 2 500 ₽.

3. В поле «Артикул (SKU)» укажите короткий код, например CLUB-MONTH. По нему бот будет ссылаться на товар.

4. Сохраните товар.

Шаг 2. Создайте партнёрскую программу

1. Откройте раздел «Программы» и создайте программу.

2. В поле «Ссылка на сайт или Telegram-бота *» укажите адрес бота, например https://t.me/MyBot.

3. В «Тип вознаграждения *» выберите «Процент» и заполните «Размер вознаграждения *».

4. Если нужна гарантированная сумма, заполните «Не менее за заказ». Партнёр получит большее из двух значений.

5. В «Повторные заказы клиента» выберите «Все заказы». Если платите партнёру только первые месяцы, выберите «Ограничить сроком» и укажите число месяцев.

6. В блоке «Товары и услуги программы» отметьте товар из шага 1.

7. Нажмите «Создать программу».

Адрес бота вписывается в поле «Ссылка на сайт или Telegram-бота *».

При цене 2 500 ₽ и ставке 20% партнёр получит 500 ₽ с каждой оплаты, включая продления.

Каждый партнёр получит в кабинете, в разделе «Программа», личную ссылку вида:

https://t.me/MyBot?start=AB12CD34

Если оставить «Только с кодом», продления засчитаются партнёру, только когда бот передаст его код в каждом заказе.

Шаг 3. Выпустите API-ключ

1. Откройте «Настройки» → «Интеграции» → «API-ключи».

2. Нажмите «Создать ключ».

3. В «Права доступа» у заказов отметьте «Чтение» и «Запись».

4. Нажмите «Скопировать ключ» и передайте ключ разработчику бота.

Ключ показывается один раз. Храните его только на сервере бота и не вставляйте в код, который видит покупатель.

Шаг 4. Настройте бота

Этот раздел для разработчика. Все запросы идут на https://refsales.ru с заголовком Authorization: Bearer <ключ>.

Запомните код партнёра

Покупатель открывает ссылку партнёра, и бот получает команду /start AB12CD34. Сохраните код за Telegram ID пользователя. Код состоит из 6–8 латинских букв и цифр. Если покупатель пришёл без ссылки, кода не будет.

Создайте заказ

Когда покупатель нажимает кнопку оплаты, создайте заказ:

curl -X POST https://refsales.ru/api/v1/orders \
  -H "Authorization: Bearer $REFSALES_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "tg-123456789-2026-10",
    "referralCode": "AB12CD34",
    "customer": { "name": "Анна", "telegramId": "123456789" },
    "items": [{ "sku": "CLUB-MONTH", "quantity": 1 }]
  }'

• externalId задаёт номер покупки в вашей системе. Повторный запрос с тем же значением вернёт уже созданный заказ, дубля не будет.

• customer.telegramId передаёт ID пользователя Telegram строкой, это from.id из Bot API. Все заказы с одним ID попадают в одну карточку клиента.

• referralCode передаёт код из /start. С неизвестным кодом заказ всё равно создастся, но партнёру не засчитается.

• Без unitPrice Рефсейлс берёт цену товара из каталога.

Сохраните data.id из ответа: это номер заказа в Рефсейлс. Затем отправьте покупателю ссылку на оплату вашей платформы.

Подтвердите оплату

Когда вы убедились, что оплата прошла, переведите заказ в оплаченный и выполненный одним запросом:

curl -X PATCH https://refsales.ru/api/v1/orders/<data.id> \
  -H "Authorization: Bearer $REFSALES_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paymentStatus": "paid", "status": "completed" }'

После ответа 200 откройте покупателю доступ. Вознаграждение партнёру начисляется в момент, когда заказ становится выполненным (completed). Одна отметка об оплате его не начисляет.

Как проверять оплату, решаете вы: по чеку, по выписке или по уведомлению вашей платформы. Рефсейлс чек не проверяет и принимает решение бота.

Продление подписки

На каждый новый месяц создайте новый заказ с тем же customer.telegramId и новым externalId. Код партнёра передавать не нужно: клиент закреплён за партнёром с первого заказа, и Рефсейлс подставит его сам. Дальше подтвердите оплату тем же запросом PATCH.

{
  "externalId": "tg-123456789-2026-11",
  "customer": { "telegramId": "123456789" },
  "items": [{ "sku": "CLUB-MONTH", "quantity": 1 }]
}

Если заказ пришёл с кодом другого партнёра, он засчитается этому партнёру. Клиент останется закреплён за первым.

Если оплату подтверждает менеджер

Бывает, что оплату проверяет человек в Рефсейлс, а не бот. Тогда бот узнаёт об оплате из вебхука:

1. Откройте «Настройки» → «Интеграции» → «Вебхуки» и нажмите «Добавить эндпоинт».

2. В поле «Адрес» укажите URL обработчика на сервере бота.

3. В «События» отметьте «Статус оплаты изменён».

4. Нажмите «Скопировать секрет» и передайте секрет разработчику.

Каждый запрос приходит с заголовком X-Refsales-Signature: t=…,v1=…. Подпись v1 равна HMAC-SHA256 от строки t.тело_запроса с вашим секретом. Отклоняйте запросы, у которых t старше 300 секунд.

В событии приходят только data.orderId и data.externalId. Запросите заказ через GET /api/v1/orders/{orderId}. Если paymentStatus.code равен paid, откройте доступ. На событие ответьте кодом 200. Для запроса заказа ключу нужно право «Чтение» у заказов.

Шаг 5. Подтверждайте оплату вручную, если бота нет

Без разработчика заказ можно закрыть в интерфейсе:

1. Откройте раздел «Заказы» и найдите заказ.

2. В «Статус оплаты» выберите «Оплачен».

3. Переведите заказ в статус «Выполнен».

Так статусы называются по умолчанию. Если вы их переименовали, выберите свои.

Как проверить, что работает

1. Откройте ссылку партнёра и нажмите «Запустить» в боте.

2. Нажмите кнопку оплаты. В разделе «Заказы» появится заказ, у него указан партнёр.

3. Подтвердите оплату запросом PATCH. Заказ станет выполненным, у партнёра появится начисление.

4. Создайте второй заказ с тем же Telegram ID без кода. У него тоже указан партнёр.

5. Откройте карточку клиента в разделе «Клиенты». В блоке «Партнёр» стоит тот, кто привёл клиента.

Если не работает

• Ответ 400 на PATCH. В теле есть лишнее поле или неизвестный код статуса. Передавайте только paymentStatus и status с системными кодами paid и completed.

• Заказ оплачен, но партнёру ничего не начислено. Заказ не переведён в «Выполнен». Передайте "status": "completed".

• Продление не засчиталось партнёру. В программе в «Повторные заказы клиента» стоит «Только с кодом» или истёк срок. Второй вариант: бот передал другой telegramId, и заказ попал в новую карточку клиента.

• Первый заказ без партнёра. Бот не сохранил код из /start или код с опечаткой.

• Ответ 429. Больше 20 запросов в секунду на все ключи магазина. Повторите запрос через секунду.

Частые вопросы

Можно подтверждать оплату по чеку, который прислал покупатель?

Да. Рефсейлс не проверяет чек и принимает решение бота или менеджера. Проверку чека вы настраиваете сами.

Что будет, если участница придёт по ссылке другого партнёра?

Заказ с кодом засчитается партнёру из этого кода. Клиент останется закреплён за партнёром, который привёл его первым, и следующие заказы без кода уйдут первому.

Когда вознаграждение можно выплатить?

После срока из поля «Срок заморозки вознаграждения» в программе. Отсчёт идёт от момента, когда заказ стал выполненным.

Как сменить партнёра у клиента?

Откройте карточку клиента в разделе «Клиенты» и выберите партнёра в блоке «Партнёр». Уже созданные заказы не изменятся.