API подарочных карт для Telegram-ботов
Краткий ответ
API подарочных карт работает в Telegram-боте точно так же, как в веб-магазине — разница только в канале доставки. Бот принимает выбор товара и оплату, вызывает эндпоинт создания заказа поставщика, получает код и отправляет его пользователю в чат. Веб-интерфейс не нужен. Ключевые шаги реализации: меню товаров, триггер оплаты, API-вызов, доставка кода через sendMessage и обработка ошибок.
Определение: API подарочных карт для Telegram-ботов — это REST API поставщика, который бэкенд бота вызывает для создания заказов подарочных карт и получения кодов, которые бот затем доставляет клиенту в рамках диалога в Telegram.
Главный вывод: API подарочных карт не зависит от канала. Вызываете ли вы его из бэкенда веб-магазина или из бэкенда Telegram-бота — для API никакой разницы нет. Единственная специфика для бота — замена доставки по email/странице заказа на вызов bot.sendMessage().
Для кого это руководство
- Разработчики Telegram-ботов, добавляющие продажу подарочных карт
- Операторы ботов, которые уже продают пополнения и хотят добавить коды подарочных карт
- Разработчики, оценивающие Telegram-бот как жизнеспособный магазин подарочных карт
Подарочная карта vs. Пополнение в Telegram-боте
| Фактор | Подарочная карта (код) | Пополнение (на аккаунт) |
|---|---|---|
| Нужен ввод от клиента | Нет | ID игрока (обязательно) |
| Доставка | Строка кода в сообщении | Подтверждение зачисления на аккаунт |
| Риск возврата | Код может быть использован не по назначению; умеренный риск | Необратимо; низкий риск |
| Сложность интеграции | Ниже | Выше (валидация ID игрока) |
| Примеры продуктов | Steam, PSN, Xbox, Google Play | PUBG UC, Robux, ML Diamonds |
Для первой реализации коды подарочных карт проще. Интеграция пополнений требует дополнительного шага валидации ID игрока.
Полный флоу бота для доставки подарочной карты
/start
→ Бот: «Выберите категорию товаров»
[Игры] [Ритейл] [Мобильные]
[Игры]
→ Бот: «Выберите товар»
[Steam $10] [Steam $20] [PSN $10] [Xbox $15]
[Steam $20]
→ Бот: «Steam $20 (US) — $21.99. Оплатить?»
[Оплатить Stars] [Оплатить крипто]
[Оплатить Stars — Telegram-платёж]
→ Нативный платёжный флоу Telegram
→ При событии successful_payment:
Бот вызывает API поставщика: POST /orders { sku: "steam-20-usd", qty: 1 }
Получает: { code: "XXXXX-YYYYY-ZZZZZ" }
Bot.sendMessage: «Ваш Steam-код: XXXXX-YYYYY-ZZZZZ
Активировать на: store.steampowered.com»
Платёжная интеграция для ботов подарочных карт
| Метод | Интеграция в Telegram | Диапазон комиссии | Трение |
|---|---|---|---|
| Telegram Stars | Нативная через Payments API | ~30% удержание | Очень низкое |
| Крипто (TON, USDT) | Ссылка на внешний кошелёк или @wallet бот | 1–2% | Низкое |
| Stripe payment link | Редирект в браузер | 2,5–3,5% | Среднее |
Примечание по Telegram Stars: Telegram удерживает около 30% Stars-платежей. За продукт $10 ваша эффективная выручка с Stars-платежа составит ~$7. Это требует более высокой розничной цены или более высокой оптовой скидки для сохранения маржи. Тщательно моделируйте перед включением Stars как единственного способа оплаты.
Формат сообщения с доставкой кода
При отправке кода пользователю всегда включайте:
✅ Заказ выполнен
Товар: Steam Gift Card $20 (Регион US)
Код: XXXXX-YYYYY-ZZZZZ
Активировать на: store.steampowered.com/account/redeemwalletcode
Регион: Только для US Steam-аккаунтов
Нужна помощь? /support
Форматируйте код в моноширинный блок для удобного копирования:
`XXXXX-YYYYY-ZZZZZ`
Telegram отображает текст между обратными кавычками моноширинным шрифтом, удобным для копирования на мобильных устройствах.
Обработка ошибок
| Ошибка | Причина | Ответ бота |
|---|---|---|
| API-вызов завершается ошибкой | Сетевая ошибка или ошибка поставщика | «Обработка заказа — пожалуйста, подождите. Если не доставлено в течение 2 минут, обратитесь в /support» |
API возвращает failed |
Нет в наличии или проблема поставщика | «Доставка не удалась. С вас не списано. Обратитесь в /support» |
| Поле кода пустое | Проблема на стороне поставщика | Считать ошибкой; не доставлять |
| Платёж подтверждён, но API завершился ошибкой | Гонка состояний | Залогировать заказ; повторить попытку; уведомить оператора при повторной ошибке |
Никогда не отправляйте пустой код или заглушку пользователю. Если API возвращает ошибку, обрабатывайте её корректно.
Логирование заказов
Для каждого выполненного заказа подарочной карты в боте логируйте:
- Telegram user ID (не имя пользователя — ID стабильны; имена могут меняться)
- SKU продукта
- ID заказа поставщика
- Код (хэшированный, не в открытом виде в базе данных)
- Временная метка
- ID подтверждения платежа
Этот лог необходим для разрешения споров: если пользователь утверждает, что не получил код, вы проверяете лог.
Чек-лист
- Каталог продуктов настроен в боте (с явным указанием региона)
- Способ оплаты интегрирован и протестирован
- Обработчик события платежа: API-вызов только при подтверждённом платеже
- Создание заказа через API поставщика с обработкой ошибок
- Доставка кода через sendMessage с полными инструкциями
- Код в моноширинном формате для удобного копирования
- Команда /support с контактной информацией
- Логирование транзакций для каждого заказа
- Мониторинг баланса с алертом
- Политика возврата сообщена (/terms или в сообщении /start)