Тип бота
Витрина, которая открывается прямо в чате и рассчитывается в TON
Витрина на TON Mini App — это веб-приложение внутри Telegram с каталогом, корзиной и оплатой в TON или Telegram Stars. Это самый короткий путь от аудитории в Telegram до оплаченной сделки. Веб-магазин она не заменяет и наследует все ограничения телеграмного вебвью.
Торговые витрины на TON Mini App: цена, сроки и ограничения
- Фиксированная цена
- $9,200 USD
- Срок
- 35 календарных дней с момента старта
- Авторизация Mini App
- Проверка initData по HMAC-SHA256 ключом от токена бота
- Что именно разрешают Telegram Stars
- Только цифровые товары и услуги
- Финальность TON
- После подтверждения необратимо — ни чарджбэка, ни арбитра
- Область просмотра
- Сообщает свою высоту, разворачивается по жесту, а не сразу
As of 2025-10-01, Telegram Bot API 13.4
Какую задачу это решает
Если сообщество проекта уже живёт в Telegram, отправлять людей во внешний магазин — измеримая потеря. Выход из приложения, подключение кошелька на незнакомой странице, дорога обратно: на каждом шаге часть людей отваливается, и суммарный отвал настолько велик, что меняет сам ответ на вопрос, что вообще имеет смысл продавать. Mini App убирает уход целиком: витрина открывается поверх чата, а кошелёк, которым покупатель и так пользуется, — в одно касание.
Типичная ошибка команд — считать Mini App обычным веб-проектом в телеграмной обёртке. Это не так. У вебвью своя логика области просмотра, воюющая с привычной вёрсткой, свои параметры темы, которые вы обязаны уважать, своя семантика кнопки «назад» и жёсткое требование подтверждать личность пользователя на сервере, а не верить клиенту. Проигнорируйте последнее — и вы построили не витрину, а неаутентифицированную ручку записи с каталогом перед ней.
Решение про оплату важнее каталога. Stars и TON — разные продукты с разными правилами: Stars это собственная валюта Telegram, разрешённая для цифровых товаров и услуг и рассчитываемая самим Telegram; TON — публичная сеть, где платит кошелёк покупателя и посредника нет. Ошибка в выборе даёт либо нарушение правил площадки, либо оплату, которую ваша аудитория не доведёт до конца, и определяется этот выбор тем, что вы продаёте, а не личными предпочтениями.
Как идёт разработка
Mini App открывается поверх чата, а не рядом с ним
Запуск идёт с кнопки бота или по прямой ссылке. Пользователь не выходит из Telegram, а это снимает самую крупную причину отвала в торговле внутри Telegram.
mini-appЛичность подтверждается раньше, чем чему-либо начинают верить
Вебвью получает строку initData, подписанную вашим токеном бота. Каждый запрос, который читает или пишет пользовательские данные, проверяет эту подпись на сервере. Пропустите проверку — и корзину сможет править любой, кто знает адрес.
web-app-initdataКаталог рисуется по теме Telegram
Telegram отдаёт параметры темы, которые меняются вместе с настройками приложения у пользователя. Витрина, которая их не учитывает, читаема в одной теме и нечитаема в другой — а аудитория делится между ними примерно пополам.
mini-appОплата уходит либо в TON Connect, либо в Stars
Физические товары и большинство услуг идут через обычного провайдера или через TON. Цифровые товары можно продавать за Stars, которые Telegram рассчитывает напрямую. Это граница правил площадки, а не вопрос вкуса.
starsПлатёж подтверждается сетью или Telegram, и только потом идёт выдача
Платёж в TON проверяется наблюдением за транзакцией, а не доверием к словам клиента о том, что он её отправил. Выдачу запускает подтверждение — единственный сигнал, который нельзя подделать.
payments-apiЗаказ возвращается в чат
Подтверждение, смена статусов и сама выдача уходят в переписку. Mini App закрывается, чат остаётся — и завтра покупатель пойдёт искать заказ именно туда.
webhook
Что Telegram разрешает, а что нет
Строку `initData` нужно проверять по HMAC-SHA256 ключом, производным от токена бота, и отдельно проверять свежесть поля `auth_date`.
Проверить подпись и не проверить возраст — значит оставить окно для повтора запроса. Обе проверки занимают десяток строк, и именно их отсутствие остаётся самой частой уязвимостью Mini App.
Telegram Stars разрешены только для цифровых товаров и услуг, но не для физических.
Продажа мерча за Stars — нарушение правил, которое ставит под удар самого бота. Физическая отгрузка уходит на TON или на обычного платёжного провайдера.
Область просмотра Mini App сообщает собственную высоту и разворачивается по жесту пользователя, а не занимает экран сразу.
Вёрстка, построенная на `100vh`, обрезается при открытии. Телеграмный API области просмотра нужно обрабатывать явно, и как раз здесь заметно ломается большинство чужих Mini App.
Транзакция в TON после подтверждения окончательна и необратима.
Ни чарджбэка, ни арбитра здесь нет. Возврат — это бизнес-процесс, который вы выполняете руками, и тексты витрины не должны намекать на обратное.
Платежи в Telegram Stars можно вернуть через Bot API в течение ограниченного срока.
Stars дают путь возврата, которого у TON нет. Для проекта, выбирающего между двумя вариантами, эта разница обычно весит больше, чем механика расчётов.
Mini App работает в вебвью, где объём доступного хранилища и поведение куки различаются на iOS и Android.
Состояние сессии живёт на сервере под ключом проверенного initData, а не в локальном хранилище. Опора на клиентское сохранение даёт корзину, которая на iOS пустеет, а на Android нет.
Когда это не нужно строить
- Вашей аудитории нет в Telegram. Mini App работает с теми, кто уже в приложении; это не канал привлечения и никого к вам не приведёт.
- Нужны полноценные товарные страницы в индексе поисковиков. Mini App не индексируется, и витрине, которая обязана ранжироваться, нужен веб-сайт рядом.
- В каталоге тысячи позиций со сложной фасетной фильтрацией. Вебвью справится плохо, и покупатели уйдут на сайт.
- Вы продаёте физические товары и рассчитывали закрыть это через Stars. Такое сочетание не разрешено, и проект придётся считать заново, с настоящим платёжным провайдером.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| grammY | 1.45 | Фреймворк бота и точка запуска Mini App. |
| Telegram Mini Apps | Bot API 9.x | Среда витрины, с честной обработкой API темы и области просмотра. |
| TON Connect | 2.x | Подключение кошелька и запросы транзакций. |
| Cloudflare Workers | current | Серверный слой, проверка initData и наблюдение за подтверждениями в сети. |
| Cloudflare D1 | current | Каталог, корзины, заказы и состояние платежей. |
О чём спрашивают перед стартом
В чём лучше принимать оплату — в TON или в Stars?
Решает то, что вы продаёте. Stars разрешены только для цифровых товаров и услуг и дают путь возврата через Bot API. TON принимает что угодно, но после подтверждения окончателен и чарджбэка не знает. Физические товары исключают Stars полностью.
Что такое initData и почему о нём столько разговоров?
Это подписанная строка, которую Telegram передаёт вебвью и по которой опознаётся пользователь. Запрос становится доверенным только после проверки её подписи вашим токеном бота и проверки её возраста. Без обеих проверок ручка заказов принимает что угодно, и это с огромным отрывом самая частая уязвимость Mini App.
Смогут ли покупатели платить в USDT?
Да, джеттоном в сети TON, и для многих аудиторий он конвертируется лучше нативного TON, потому что сумма не уезжает между расчётом цены и оплатой. Это вопрос настройки, а не другой разработки.
Будет ли витрина ранжироваться в Google?
Нет. Mini App не индексируется и для этого не предназначен. Если поисковая видимость важна, Mini App остаётся поверхностью конверсии, а ранжируется обычный сайт — при общем каталоге на двоих.
Как устроены возвраты денег покупателю?
Для Stars — через Bot API в отведённое Telegram окно. Для TON — руками: транзакция необратима, поэтому возврат представляет собой новый платёж, который отправляете вы. Тексты витрины обязаны честно называть эту разницу, а не изображать единую политику.
Одинаково ли всё работает на iOS и на Android?
В основном да, но есть реальные различия в хранилище вебвью и в поведении области просмотра. Состояние держится на сервере под ключом проверенного initData именно потому, что клиентское сохранение на двух платформах ведёт себя по-разному.
Можно ли переиспользовать фронтенд нашего действующего интернет-магазина?
Редко когда окупается. Область просмотра, тема, кнопка «назад» и модель идентификации отличаются настолько, что переделка существующего фронтенда обычно дороже аккуратной разработки Mini App — и на выходе получается нечто чужеродное внутри Telegram.