Как подключить Telegram-бота к Рефсейлс

Что настроим

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

Схема подходит для закрытых чатов, клубов, курсов и других продуктов, которые продаются через бота.

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

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

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

• Расширенный счёт PayAnyWay: номер счёта и код проверки целостности из кабинета PayAnyWay.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Код партнёра приходит боту в параметре start. Бот должен его сохранить, иначе заказ не засчитается партнёру.

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

При цене 2 000 ₽ и ставке 20% партнёр получит минимальные 500 ₽.

Шаг 3. Подключите PayAnyWay

1. Откройте «Настройки» → «Интеграции» → «PayAnyWay».

2. Заполните «Номер расширенного счёта» и «Код проверки целостности».

3. Для первой проверки оставьте включённым «Тестовый режим».

4. Нажмите «Сохранить».

5. Скопируйте адрес из поля «Pay URL для кабинета PayAnyWay».

6. В кабинете PayAnyWay вставьте этот адрес в настройки счёта в поле Pay URL. Check URL оставьте пустым.

Заказ становится оплаченным только после уведомления PayAnyWay с верной подписью. Страница успеха, чек или скриншот оплату не подтверждают.

Поле «Pay URL для кабинета PayAnyWay» появится под переключателем после сохранения.

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

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

2. Нажмите «Создать ключ» и задайте название, например «Telegram-бот».

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

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

5. Нажмите «Скопировать ключ» и передайте ключ разработчику. Рефсейлс показывает ключ один раз.

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

Шаг 5. Добавьте вебхук

Вебхук сообщает боту, что оплата прошла. Без него боту придётся опрашивать API по таймеру.

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

2. В поле «Адрес» укажите адрес сервера бота, например https://bot.example.ru/refsales/webhook.

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

4. Сохраните эндпоинт.

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

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

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

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

Покупатель открывает ссылку партнёра, и бот получает команду /start AB12CD34. Сохраните код за пользователем Telegram. Код состоит из 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-1790505600",
    "referralCode": "AB12CD34",
    "customer": { "name": "Анна", "phone": "+79990000000" },
    "items": [{ "sku": "SUB-MONTH", "quantity": 1 }]
  }'

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

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

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

Сохраните data.id из ответа: это номер заказа в Рефсейлс.

Получите ссылку на оплату

curl -X POST https://refsales.ru/api/v1/orders/<data.id>/payment-link \
  -H "Authorization: Bearer $REFSALES_KEY"

Отправьте покупателю data.url из ответа, например кнопкой в сообщении. Повторный запрос для того же заказа вернёт ту же ссылку. Если сумма заказа изменилась, запросите ссылку заново: старая перестанет открываться.

Выдайте доступ после оплаты

После оплаты Рефсейлс отправит на адрес вебхука POST с заголовком X-Refsales-Event: order.payment_status_changed:

{
  "id": "d1a8328d-114f-4787-8182-0d88148cafff",
  "type": "order.payment_status_changed",
  "data": { "orderId": "…", "externalId": "tg-123456789-1790505600" }
}

1. Проверьте подпись из заголовка X-Refsales-Signature: это HMAC-SHA256 от строки t.тело с секретом вебхука. Отклоняйте запросы старше 5 минут.

2. Запросите заказ: GET /api/v1/orders/<orderId>.

3. Если paymentStatus.code равен paid, отправьте покупателю доступ.

4. Ответьте кодом 200. Повтор события приходит с тем же id, поэтому храните обработанные id и не выдавайте доступ дважды.

Готовые примеры проверки подписи на PHP, Node.js и Python есть в руководстве по вебхукам.

Шаг 7. Закрывайте заказ после оплаты

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

Автоматизация, без кода:

1. Откройте раздел «Автоматизации» и нажмите «Создать».

2. В окне «Новая автоматизация» выберите триггер «Смена статуса оплаты».

3. В настройках триггера в поле «В статус оплаты (необязательно)» выберите оплаченный статус.

4. Добавьте действие «Сменить статус заказа» и в «Целевой статус» выберите «Выполнен».

5. Сохраните автоматизацию и включите её переключателем в списке.

Через бота: после выдачи доступа отправьте PATCH /api/v1/orders/<orderId> с телом {"status": "completed"}.

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

1. Оставьте в PayAnyWay «Тестовый режим» включённым. Форма оплаты откроется на demo.moneta.ru.

2. Пройдите путь покупателя по ссылке партнёра: /start, кнопка оплаты, оплата.

3. На странице PayAnyWay появится строка «Последнее уведомление» с временем платежа.

4. В «API-ключи» → «Вебхуки» в «Последние доставки» появится событие «Статус оплаты изменён» со статусом «Доставлено».

5. В разделе «Заказы» заказ отмечен оплаченным, привязан к партнёру и переведён в «Выполнен».

6. Партнёр видит заказ у себя в разделе «Заказы».

7. Выключите «Тестовый режим» и проведите один реальный платёж.

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

• API отвечает 402. Тариф магазина не включает API. Подключите тариф «Оптимальный».

• API отвечает 403. У ключа нет права на запись заказов. Откройте ключ и отметьте «Запись» в строке «Заказы».

• Ссылка на оплату не выдаётся, ответ 409 с причиной connection_not_found. PayAnyWay не подключён или выключен. Проверьте шаг 3.

• Ответ 409 с причиной order_already_paid. Заказ уже оплачен. Создайте новый заказ с другим externalId.

• На странице PayAnyWay написано «Уведомлений от PayAnyWay ещё не было». Pay URL не вставлен в кабинет PayAnyWay или вставлен с ошибкой. Скопируйте его заново.

• Эндпоинт в статусе «Отключён из-за ошибок». Сервер бота долго не отвечал кодом 2xx. Исправьте обработчик, включите эндпоинт и нажмите «Отправить тестовое событие».

• Заказ оплачен, но партнёру ничего не начислено. Заказ не переведён в «Выполнен» или бот не передал referralCode. Проверьте шаг 7 и сохранение кода из /start.

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

Подойдёт готовая ссылка на оплату с другой платформы?

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

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

Нет. Заказ становится оплаченным только после уведомления PayAnyWay с верной подписью. Чек и страница успеха оплату не подтверждают.

Что будет, если покупатель нажмёт кнопку оплаты дважды?

Если бот передаёт тот же externalId, Рефсейлс вернёт уже созданный заказ, а запрос ссылки вернёт ту же ссылку на оплату. Дубля не будет.

Как посчитается вознаграждение с минимальной суммой?

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