Магазин подарочных карт в Telegram Mini App: руководство

У Telegram более 900 миллионов активных пользователей в месяц, и всё больше из них покупают внутриигровые товары, пополняют балансы и торгуют цифровыми продуктами, не покидая приложение. Telegram Mini Apps — это полноценные веб-приложения, которые работают прямо внутри чата: без внешнего браузера, без редиректов, без лишнего шага. Для реселлеров подарочных карт, которые уже ведут Telegram-каналы или сообщества, Mini App — это витрина, открытая для покупателя каждый день.

В этом руководстве мы построим рабочий магазин подарочных карт на базе FazerCards API — от создания бота до живой выдачи кодов, используя лёгкий Node.js-бэкенд, который разворачивается на любом HTTPS-хостинге.

Что понадобится

Перед началом подготовьте следующее:

• Аккаунт FazerCards с API-ключом — 5-дневный Gold-триал открывает полный доступ к API без привязки карты
• Токен Telegram-бота (создаётся через @BotFather прямо в Telegram)
• Node.js-хостинг с HTTPS-доменом — подойдут Vercel, Railway, Render; Telegram требует HTTPS для Mini Apps
• Базовые знания HTML/JavaScript и REST API; опыт работы с мобильными SDK не нужен

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

Шаг 1. Создайте бота и зарегистрируйте Mini App

Откройте Telegram и напишите @BotFather. Отправьте /newbot, следуйте подсказкам и сохраните токен бота. Затем отправьте /newapp: BotFather спросит название, описание, обложку, URL, по которому будет доступен ваш Mini App, и короткое имя. Укажите домен деплоя — в ответ получите прямую ссылку вида t.me/yourbotname/shortname, которая открывает магазин на любой платформе.

Используйте /setmenubutton, чтобы поставить кнопку магазина рядом с полем ввода в каждом чате с ботом. Пользователь, написавший вам однажды, будет видеть кнопку при каждом открытии чата — постоянная точка входа без дополнительных затрат.

Шаг 2. Настройте бэкенд для проксирования запросов к API

Сервер выполняет две задачи: отдаёт HTML-страницу Mini App по HTTPS и проксирует запросы к FazerCards, не раскрывая API-ключ клиенту.

Создайте Node-проект и установите SDK fazercards (npm install fazercards). Храните API-ключ в переменной окружения. Откройте два маршрута:

1. GET /api/catalog — вызывает FazerCards GET /giftcards для получения категорий, затем GET /giftcards/cards?category_id=… для каждой, возвращая урезанный список офферов с card_id, price_usd и наличием на складе.
2. POST /api/order — проверяет личность пользователя Telegram, полученную от фронтенда, затем вызывает POST /giftcards/order с выбранными category_id, card_id и quantity.

Держите ответы каталога лаконичными. Двадцать-тридцать продуктов на категорию загружаются быстро на мобильном и не перегружают покупателя.

Шаг 3. Постройте фронтенд с Telegram Web App SDK

Mini App — это обычная HTML-страница, отображаемая во встроенном браузере Telegram. Подключите Telegram Web App SDK из официального CDN Telegram в head вашей страницы. Это открывает доступ к window.Telegram.WebApp с тремя ключевыми инструментами:

• initData — подписанная строка, подтверждающая личность пользователя; всегда проверяйте на сервере перед созданием заказа
• MainButton — большая нижняя кнопка; задайте её текст и вызовите .show() при выборе продукта
• themeParams — цветовые токены, позволяющие странице автоматически соответствовать теме Telegram пользователя

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

Шаг 4. Проверка личности и создание заказов

Когда пользователь нажимает MainButton, фронтенд отправляет выбранные category_id и card_id и строку initData на ваш бэкенд в /api/order.

На сервере проверьте initData через HMAC-SHA256 с ключом, производным от токена бота — алгоритм описан в документации для разработчиков Telegram. Отклоняйте любые запросы с невалидной подписью: это защищает от создания заказов вне настоящей Telegram-сессии.

После проверки сначала примите оплату: внутри Mini App цифровые товары оплачиваются в Telegram Stars через инвойс (см. FAQ ниже), а заказ в FazerCards создаётся только после того, как Telegram подтвердит платёж. Затем вызовите POST /giftcards/order с заголовками X-Api-Key и Idempotency-Key. Ключ генерируйте один раз на покупку — например, из ID пользователя Telegram и ID платежа — и используйте его при каждом повторе этой же покупки. Если пользователь нажал дважды или соединение прервалось, FazerCards вернёт исходный заказ вместо повторного списания. Подробнее об идемпотентности и паттернах повторных запросов — в нашем гайде по отказоустойчивым заказам через API; основы — в руководстве по интеграции с gift card API.

Шаг 5. Выдача кодов и подтверждение заказов

Многие подарочные карты возвращаются со status: completed сразу, с кодами в поле cards ответа; пополнения и часть карт начинаются со статуса processing и завершаются чуть позже. Отобразите код в UI Mini App — и продублируйте его в чат Telegram через sendMessage Bot API. Покупатели ждут коды в истории чата, а не на экране веб-приложения, которое можно случайно закрыть.

Для продуктов, которые начинаются со статуса processing, настройте вебхук FazerCards на маршрут вашего сервера. Когда придёт событие order.status_changed со статусом completed, получите коды через GET /orders/:orderId и отправьте их через sendMessage. FazerCards повторяет неудавшиеся доставки через 1, 5 и 30 минут — достаточный запас прочности для коротких перезапусков сервера.

Если код не активируется, обратитесь в поддержку FazerCards с ID заказа; подтверждённые неработающие коды получают замену или возврат на баланс.

Шаг 6. Запуск и дистрибуция Mini App

Деплойте на HTTPS-хостинг и обновите URL в BotFather. Проверьте весь флоу на нескольких небольших реальных заказах — песочницы нет, поэтому пополните небольшой баланс для теста на боевом API. Когда всё работает стабильно, запускайте дистрибуцию:

• Кнопка канала — прикрепите кнопку Mini App к своему Telegram-каналу, чтобы каждый пост вёл к покупке
• Inline-кнопки — отправляйте анонсы продуктов с кнопкой, открывающей Mini App прямо на нужном товаре
• Прямая ссылка — делитесь ссылкой t.me/yourbotname/shortname в группах, в описании профиля, у партнёров

Начните с двух-трёх категорий подарочных карт с высоким спросом и расширяйте ассортимент по результатам продаж. Весь каталог FazerCards — более 10 000 продуктов по 700+ играм — доступен через единый API. На странице тарифов выберите план с нужной вам маржой.

Что получается в итоге

Рабочий Telegram Mini App: каталог подарочных карт, заказы через FazerCards и выдача кодов прямо в чат — и всё это без выхода из Telegram. В связке с готовой аудиторией канала или сообщества это одна из наименее затратных торговых точек, которую можно запустить за вечер.

Изучите полный каталог, ознакомьтесь с документацией по API и вебхукам и начните с 5-дневного Gold-триала — без карты, без KYC, с полным API-доступом.

FAQ

Как покупатели платят внутри Mini App?

В Telegram Stars. По правилам Telegram цифровые товары и услуги внутри ботов и Mini Apps оплачиваются в Stars через Bot Payments API, а сторонние платёжные провайдеры предназначены для физических товаров. Перед запуском сверьтесь с актуальными условиями Telegram для Mini Apps и заложите конвертацию Stars в розничные цены. Ваша закупка — отдельная история: баланс FazerCards пополняется через Binance Pay или USDT (TRC20, BEP20, TON, Aptos), и на этой стороне нет риска чарджбэков по картам.

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

Да. API FazerCards включает отдельные эндпоинты для пополнений игр (GET /topups, POST /topups/order) и game keys (GET /gamekeys). Добавьте вкладку «Пополнения» в интерфейс Mini App и подключите её к соответствующим эндпоинтам. Весь ассортимент — на странице пополнений платформ.

Как обрабатывать заказы, которые выполняются не сразу?

Зарегистрируйте вебхук FazerCards на маршрут вашего сервера. Когда придёт событие order.status_changed со статусом completed, получите коды через GET /orders/:orderId и отправьте их покупателю через sendMessage. Полное описание событий, структуры payload и расписания повторов — в документации по вебхукам.

Что делать, если покупатель говорит, что код не работает?

Попросите ID заказа — он отображается в Mini App сразу после покупки — и создайте обращение в поддержку FazerCards. Подтверждённые неработающие коды получают замену или возврат средств на баланс. Стандарты отбора поставщиков FazerCards опубликованы на странице /suppliers.