B2B API Telegram Stars: продажа Stars и Premium

Если у вашего продукта уже есть клиенты, собственная форма оплаты или аудитория в Telegram, вам не нужно строить отдельную систему фулфилмента, чтобы продавать цифровые продукты Telegram. MyStars Fulfilment API позволяет вашему бэкенду создавать и отслеживать заказы на Telegram Stars и Telegram Premium с доставкой на Telegram @username.

Это практичный вариант для реселлеров, Telegram-ботов и Mini Apps, платформ для авторов, сервисов подарков, программ лояльности, агентств, маркетплейсов и продуктов, которые хотят добавить покупку в Telegram, не направляя каждого клиента в ручной процесс поддержки.

Кому нужен API Telegram Stars?

Используйте API Telegram Stars, когда Stars или Premium — часть продаваемого вами продукта, а не разовая ручная покупка для своей команды.

Типичные B2B-сценарии включают:

• Витрины реселлеров, продающие пакеты Stars или периоды Premium вместе с другими цифровыми товарами;
• Telegram-боты и Mini Apps, которые получают username, показывают актуальную котировку и передают заказ на бэкенд;
• Платформы для авторов и сообществ, помогающие аудитории пополнить баланс перед платным постом, действием в боте или премиум-опытом;
• Продукты для подарков и лояльности, превращающие награду кампании в Telegram Stars или Premium для указанного получателя;
• Агентства и управляемые сервисы, которым нужен повторяемый процесс фулфилмента вместо ручной обработки каждого запроса клиента;
• Маркетплейсы, которым нужна проверяемая запись о заказе и событие о завершении доставки.

API — это слой фулфилмента, а не фронтенд-виджет. Ваш продукт отвечает за клиентский опыт, его checkout и коммерческие правила. Ваш сервер использует MyStars, чтобы получать котировки, проверять данные, создавать, оплачивать и сверять Telegram-заказы на фулфилмент.

Что можно продавать через MyStars API?

Текущий каталог поддерживает два типа продуктов:

• Telegram Stars — в заказе указывается количество Stars;
• Telegram Premium — в заказе указывается длительность Premium в месяцах.

Stars и Premium решают разные задачи покупателя, поэтому показывайте их в интерфейсе отдельно. Stars — расходуемый баланс Telegram для авторов, каналов, ботов и цифровых товаров. Premium — подарок в виде подписки для аккаунта Telegram. Если клиент сравнивает планы Premium, а не интегрирует API, направьте его на оформление Telegram Premium.

Не хардкодьте размеры пакетов, сроки планов, валюты или цены в клиентском приложении. В документации MyStars API доступны актуальные данные о продуктах, валютах и ценах, чтобы ваш каталог следовал текущим правилам API.

Как продавать Telegram Stars через API: B2B-процесс фулфилмента

Надёжная интеграция строится на короткой, но продуманной последовательности. Заказ создаётся на вашем бэкенде; клиент не должен видеть API-ключ или работать с ончейн-платёжными инструкциями, которые относятся к вашему сервису.

1. Загрузите актуальный каталог и платёжные валюты. Получайте доступные продукты и валюты при запуске интеграции и обновляйте их с разумной периодичностью. Это не позволит старой версии приложения предложить недоступный вариант.
2. Запросите актуальную котировку. Передайте в endpoint ценообразования выбранный продукт, количество или срок и платёжную валюту. Используйте возвращённую сумму для расчёта; не формируйте цену на основе предположений о кешированном курсе.
3. Проверьте получателя до списания средств или создания заказа. Отправьте Telegram @username получателя и выбранный продукт в endpoint проверки получателя. Проверка получателя Stars и проверка права на Premium не взаимозаменяемы.
4. Создайте один идемпотентный заказ. Передайте выбранный продукт, получателя, платёжную валюту, URL обратного вызова при использовании вебхуков и стабильный Idempotency-Key, сформированный из собственного внутреннего ID заказа.
5. Оплатите ровно по возвращённой платёжной инструкции. Ответ на заказ содержит адрес назначения, сумму, комментарий, сеть и срок действия. Ваш платёжный сервис должен использовать эти значения без изменений, а не адрес кошелька или комментарий, сохранённые в конфигурации приложения.
6. Сверьте финальный статус доставки. Используйте endpoint статуса заказа как резервный вариант либо получайте финальный статус через вебхук. Помечайте заказ клиента как выполненный только после того, как соблюдены ваши правила сверки.

Эта последовательность отличает B2B-интеграцию API Telegram Stars от простой ссылки на покупку: каждый этап можно сохранить, безопасно повторить, наблюдать и поддерживать силами вашей продуктовой команды.

Какие данные должен хранить ваш бэкенд

Ваша база данных — источник истины для клиентского заказа. Храните достаточно сведений, чтобы объяснить заказ поддержке, безопасно повторить операцию и сверить блокчейн-платёж, не раскрывая секреты.

Как минимум храните:

• внутренний ID заказа и ID заказа MyStars;
• ключ идемпотентности, использованный для создания заказа;
• тип продукта, количество Stars или срок Premium и username получателя;
• валюту котировки, сумму, сеть, срок действия и комментарий к платежу;
• хеш ончейн-транзакции после расчёта;
• состояние вашего платежа, состояние заказа MyStars, payload вебхука или время опроса и итоговый результат фулфилмента.

Idempotency-Key важен, потому что реальные системы выполняют повторы. Тайм-аут сети после POST /v1/orders не доказывает, что ничего не произошло. Повтор с тем же стабильным ключом позволяет бэкенду восстановиться, не создавая второй заказ на фулфилмент для той же покупки клиента.

Вебхуки, опрос и жизненный цикл заказа

Клиент может сначала оплатить ваш продукт, а затем ваш сервис рассчитаться по инструкции MyStars. Это создаёт три операционных состояния, которые нельзя путать:

1. клиент оплатил ваш продукт;
2. ваш сервис отправил ончейн-платёж для заказа MyStars;
3. MyStars доставил Stars или Premium получателю в Telegram.

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

Используйте callback вебхука для обычных обновлений доставки и сохраняйте опрос статуса как путь восстановления. Убедитесь, что входящие запросы вебхука обрабатываются вашим бэкендом, сопоставляются с ID заказа MyStars, а сама обработка вебхуков тоже идемпотентна. Дублирующий callback не должен выдавать повторную награду, выпускать вторую квитанцию или запускать второй процесс возврата.

Расчёты: GRAM (TON) и USDT в TON

Заказы MyStars API можно оплачивать в GRAM (TON) или USDT (TON). Это бэкенд-платёжные операции, а не поля, которые следует бездумно копировать в клиентский checkout.

Для каждого заказа читайте из ответа API возвращённые валюту, сеть, адрес, сумму, комментарий и срок действия. Не используйте платёжные реквизиты предыдущего заказа повторно. Платёж с неверной суммой, комментарием, сетью или просроченной инструкцией может не пройти сверку.

Храните подпись кошелька и API-вызовы на стороне сервера. Никогда не включайте X-Api-Key, seed-фразу кошелька или учётные данные для автоматических расчётов в браузерный bundle, Telegram Mini App, публичный репозиторий или клиентский лог.

Отсутствие KYC для покупателя: точный смысл для B2B

«Отсутствие KYC для покупателя» — поисковый запрос, но здесь важна точность. В этом сценарии checkout фулфилмента MyStars не требует от покупателя загрузки документов, удостоверяющих личность. Это может снизить трение в пользовательском опыте.

Чек-лист запуска интеграции API Telegram Stars для реселлера

Перед тем как сделать функцию доступной клиентам, проверьте следующее:

• API-ключ хранится только в серверном менеджере секретов и может быть отозван или заменён;
• выбор продуктов и валют поступает из актуального API, а не из хардкода;
• проверка получателя выполняется до создания заказа и до финального списания средств с клиента;
• у каждого заказа есть стабильный внутренний ID и ключ идемпотентности;
• для оплаты используются точные адрес, сумма, комментарий, сеть и срок действия, возвращённые для этого заказа;
• USDT везде обозначен как только TON;
• обработка вебхуков проверяет, сопоставляет, логирует события и безопасно устраняет дубликаты;
• опрос покрывает пропущенный или задержавшийся вебхук;
• команда поддержки может найти заказ по вашему ID, ID заказа MyStars, получателю и хешу транзакции;
• до запуска определены правила возвратов, противодействия мошенничеству, compliance и коммуникации с клиентами.

Для форматов запросов, полей ответов, вариантов SDK и актуального API-контракта используйте документацию MyStars API как главный источник для реализации.

FAQ

Могу ли я продавать Telegram Stars через собственный сайт, бота или Mini App?

Да. Ваш продукт может получить выбор клиента и username получателя, а бэкенд будет использовать MyStars Fulfilment API для создания и отслеживания заказа Stars. Храните API-ключ и операции расчёта на стороне сервера.

Могу ли я продавать Telegram Premium через тот же API?

Да. API поддерживает фулфилмент Telegram Premium как отдельный тип продукта со сроком Premium в месяцах. Перед созданием заказа проверяйте право получателя, поскольку ограничения для подарка Premium могут отличаться от проверки получателя Stars.

Предоставляет ли API фиксированный прайс-лист для Stars и Premium?

Используйте endpoint ценообразования для актуальной котировки, а не фиксированный список. Ответ API — подходящий источник текущей суммы и валюты расчёта для выбранного заказа.

Как избежать дублирующихся заказов Telegram Stars?

Создавайте каждый заказ со стабильным Idempotency-Key, привязанным к вашему внутреннему ID заказа. Если серверный worker повторяет операцию из-за тайм-аута, используйте тот же ключ вместо генерации нового.

Какая сеть USDT поддерживается?

Только USDT в TON / The Open Network. Не отправляйте и не предлагайте USDT в другой сети как совместимый способ расчёта.

Означает ли отсутствие KYC для покупателя, что у моего бизнеса нет обязательств по compliance?

Нет. Это описывает опыт покупателя при оформлении в MyStars, а не юридические, финансовые, антифродовые, налоговые, санкционные, потребительские обязательства или обязательства по возвратам вашей компании.

Начните B2B-интеграцию Telegram-фулфилмента

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

Откройте документацию MyStars API и начните интеграцию →

Источники и подтверждения

• MyStars FaaS — документация Fulfilment API: каталог продуктов, актуальные цены, проверки получателей, создание заказов, аутентификация API, платёжные инструкции, отслеживание статуса и вебхуки.