API для Telegram Premium и Stars

Отправляйте подарки Telegram Premium и Stars Telegram из своего приложения, бота или магазина. Простое REST API с JSON, один API-ключ и заказы, оплачиваемые с вашего баланса по тем же ценам, что и на сайте.

Начало работы

Создайте аккаунт и пополните баланс на странице «Баланс».
Откройте «Мой аккаунт», затем «API» и создайте API-ключ. Он показывается только один раз, поэтому сохраните его на своём сервере.
Отправляйте ключ в заголовке X-Api-Key с каждым запросом.

Создать API-ключ

Базовый URL и формат

Все запросы используют HTTPS и JSON. Успешный ответ: { "ok": true, "data": ... }. Ошибка: { "ok": false, "error": { "code", "message" } } с устойчивым кодом.

https://buytgpremium.com/api/v1

curl https://buytgpremium.com/api/v1/balance \
  -H "X-Api-Key: btk_YOUR_KEY"

{ "ok": true, "data": { "credit": "120.00", "currency": "USD" } }

Эндпоинты

Способ	Путь	Функция
GET	/balance	Ваш баланс в USD
GET	/products	Сроки и цены Premium, диапазон и пакеты Stars
GET	/recipient?username=	Проверяет username: человек, канал, группа, бот или не найдено
POST	/quote	Стоимость заказа и достаточно ли средств на балансе
POST	/orders	Оформляет заказ подарка с оплатой с баланса
GET	/orders?limit=&batch=	Ваши последние заказы (до 100)
GET	/orders/{code}	Один заказ по его коду

Оформление заказа

Premium: продукт "premium", месяцы 3, 6 или 12, до 10 username в получателях. Stars: продукт "stars", звёзды от 3,500 до 550,000, один username в получателе. Сумма списывается с вашего баланса сразу, и для каждого получателя создаётся отдельный заказ.

curl -X POST https://buytgpremium.com/api/v1/orders \
  -H "X-Api-Key: btk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"premium","months":12,"recipients":["alice","bob"]}'

{ "ok": true, "data": { "batch": "B-7KQ2-...", "total": "34.00", "currency": "USD",
  "orders": [ { "code": "G-4MZ8-...", "product": "premium", "recipient": "alice", "months": 12,
    "price": "17.00", "status": "completed" }, ... ] } }

curl -X POST https://buytgpremium.com/api/v1/orders \
  -H "X-Api-Key: btk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"stars","stars":5000,"recipient":"alice"}'

Коды ошибок

Код	Значение
отсутствует_api_key / недействительный_api_key	Ключ отсутствует, неверен или был заменён (401)
неверный_ввод / неверный_получатель	Проверьте продукт, месяцы, звёзды или имя пользователя (400)
recipient_not_user	Это имя пользователя принадлежит каналу, группе или боту, либо не существует
insufficient_credit	Баланс меньше суммы заказа; пополните баланс
network_error	Временная ошибка сети; ваш баланс не изменился, попробуйте снова
rate_limited	Более 120 запросов в минуту на ключ (429, см. Retry-After)

Лимиты и безопасность

120 запросов в минуту на ключ; 60 проверок получателя за 10 минут.
Один ключ на аккаунт. Замена ключа немедленно отключает старый.
Храните ключ на своём сервере. Никогда не размещайте его на веб-странице или в мобильном приложении.