API для продажи Telegram Stars и Premium: кому это нужно

Продавать звёзды и Premium можно двумя путями: готовым ботом-магазином или через API в своём продукте. Выбор зависит от того, где уже есть аудитория и кто будет принимать у неё деньги.

#Готовый магазин или API

Оба варианта берут товар с одного склада. Различается то, кто строит витрину и принимает деньги покупателя.

Если ни сайта, ни своего бота у вас пока нет, API ничего не добавит: магазин в боте уже умеет витрину, оплату и выдачу. С чего начать в этом случае, написано в статье про магазин Stars в боте.

#Когда API оправдан

• У вас есть аудитория в своём боте или на сайте, и уводить её в чужой интерфейс не хочется.
• Продажа это часть большего процесса: игровой сервис, биржа, панель, CRM.
• Нужна своя логика цен: скидки по уровням клиента, пакеты, свои акции.
• Товар выдаётся внутри вашего продукта, а не в отдельном чате.

#Что есть в API

Все пути ниже идут после https://hexpay.live/api/reseller/v1. Каждый запрос несёт заголовок Authorization: Bearer <ключ>.

В API основные товары магазина: Telegram Stars, Premium на 3, 6 и 12 месяцев, подарки Telegram, игры, подписки на нейросети, подарочные карты и музыкальные подписки. У части товаров свой подкаталог: подарок выбирается из /gifts, игра из /games, нейросеть из /neural.

#Как проходит один заказ

После второго шага у вас на руках точная сумма. Её можно показать покупателю и списать депозит только после его согласия. Неоплаченный заказ живёт 30 минут и отменяется сам, депозит при этом не трогается.

Если доставка сорвалась, заказ переходит в failed, и депозит возвращается автоматически, без обращения в поддержку. Сумму возврата показывают поля refunded и refund_amount_nano.

#Депозит и розница

Оптовую цену API отдаёт в двух видах: wholesale_price_rub для показа и wholesale_price_nano для расчётов, где 1 ₽ = 1000 nano. Розницу назначаете вы и принимаете деньги покупателя своей кассой.

Депозит пополняется в кабинете или запросом POST /deposit/create, который вернёт ссылку на оплату. Способы пополнения и лимиты отдаёт GET /deposit/providers, а с параметром ?amount= ещё и комиссию и итог к оплате по каждому способу.

#Что останется на вашей стороне

• Витрина и розничные цены, построенные по ответу /products.
• Приём денег от покупателя.
• Хранение custom_id рядом с вашим заказом.
• Опрос статуса и запись результата в вашу базу.
• Экран для покупателя, пока заказ в доставке, и сценарий на случай failed.

Последние три пункта задают схему вашей базы. Решите их до первой строки кода: переделывать таблицу заказов после запуска дороже.

Если выбираете между несколькими поставщиками, сравните не только цену: список вопросов есть в статье как выбрать поставщика.

#Чек-лист

• решить, нужен ли API или хватит магазина в боте
• выпустить ключ и сохранить его в переменной окружения
• пополнить депозит на минимальную сумму
• построить витрину по ответу GET /products
• довести один заказ до delivered руками