Back to Blog
FRAGMENT API

Fragment API SDK для приложений и ботов Telegram

MyStars.tg Team8 min read

Большинство идей для коммерции в Telegram упирается в одну и ту же стену после прототипа: бота или Mini App построить легко, но для исполнения заказов на Stars и Premium всё ещё нужен надёжный серверный процесс. Поэтому разработчики ищут Fragment API.

MyStars FaaS даёт этот недостающий уровень. FaaS означает Fragment as a Service: ваш продукт Telegram сохраняет пользовательский опыт и базу заказов, а MyStars предоставляет процесс исполнения через API, официальные SDK и подписанные обновления статуса.

Руководство по Fragment API SDK для приложений и ботов Telegram с MyStars FaaS, SDK TypeScript и Python, вебхуками и исполнением заказов
Практическая архитектура Fragment API SDK для приложений и ботов Telegram с использованием MyStars FaaS.

Используйте это руководство, если хотите подключить настоящее приложение Telegram, бота, маркетплейс, инструмент для авторов или сценарий реселлера, а не просто прочитать очередной обзор API.

Чистая архитектура: Telegram API спереди, Fragment API сзади

Сохраняйте границу простой.

Ваш уровень Telegram API обрабатывает то, что видит пользователь: команды бота, inline-клавиатуры, экраны Mini App, карточки заказов, сообщения и ответы поддержки.

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

Уровень MyStars FaaS обрабатывает процесс Fragment as a Service: ценообразование, проверку получателя, создание заказа, инструкции оплаты и статус исполнения.

Это разделение важно для безопасности. Не помещайте API-ключ MyStars во фронтенд Telegram Mini App. Клиент должен обращаться к вашему бэкенду, а бэкенд — к MyStars.

Установите SDK для своего стека

Для бэкендов Node.js и TypeScript используйте официальный @mystars-tg/faas-sdk:

npm install @mystars-tg/faas-sdk

Для бэкендов Python используйте официальный пакет mystars-faas:

pip install mystars-faas

Оба пакета опубликованы как официальные SDK MyStars FaaS и направляют разработчиков к интерактивной документации API. Текущая документация пакетов описывает совместимость с FaaS API v1.9.0, что полезно при сравнении примеров SDK со справочником API.

Создайте первый серверный маршрут на TypeScript

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

До кода — простое объяснение того, что он делает:

  • создаёт клиент MyStars на бэкенде, используя MYSTARS_API_KEY;
  • запрашивает у MyStars текущую цену выбранного количества Stars;
  • проверяет, может ли Telegram username получить продукт;
  • останавливается раньше, если получатель не подходит, вместо создания некорректного заказа;
  • создаёт заказ на исполнение, используя ваш стабильный localOrderId как основу для идемпотентности;
  • возвращает котировку и объект заказа MyStars, чтобы приложение могло сохранить их и показать инструкцию оплаты.
import { MyStarsClient } from "@mystars-tg/faas-sdk";

const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);

export async function createStarsOrder(input: {
  username: string;
  quantity: number;
  localOrderId: string;
}) {
  const quote = await client.getPricing({
    type: "stars",
    quantity: input.quantity,
    payment_currency: "ton",
  });

  const recipient = await client.checkRecipient({
    type: "stars",
    recipient: { username: input.username },
  });

  if (!recipient.eligible) {
    return { ok: false, message: recipient.telegram_message };
  }

  const order = await client.createOrder(
    {
      type: "stars",
      recipient: { username: input.username },
      quantity: input.quantity,
      payment_currency: "ton",
      callback_url: "https://your-app.example.com/webhooks/mystars",
    },
    { idempotencyKey: `local-${input.localOrderId}` },
  );

  return { ok: true, quote, order };
}

Ключевая часть — ключ идемпотентности. Используйте стабильное значение из собственной системы. Если HTTP-запрос прервётся по тайм-ауту после того, как заказ был создан на сервере, повторите его с тем же ключом, а не создавайте дубликат.

Несколько строк требуют особого внимания:

  • MyStarsClient.production(...) означает, что запрос идёт к рабочему API MyStars, поэтому используйте тестовый или локальный заказ в своей системе, пока не будете готовы к реальному трафику.
  • getPricing(...) даёт вашему бэкенду актуальную котировку. Не зашивайте цены в интерфейс бота.
  • payment_currency: "ton" — это enum/название API для нативного платёжного маршрута в этом примере SDK. В интерфейсе продукта обозначайте этот маршрут как Gram или Gram (ex. TON). TON оставьте названием блокчейна/сети.
  • checkRecipient(...) защищает покупателя от оплаты username или продукта, который невозможно исполнить.
  • callback_url — адрес, куда MyStars может отправлять обновления статуса заказа после его создания.
  • idempotencyKey — защита от дублирования заказов. Он должен браться из заказа в вашей базе данных, а не из случайного значения, созданного в браузере.

Соберите тот же процесс на асинхронном Python

Командам Python обычно нужен асинхронный код, поскольку их фреймворк Telegram-бота уже асинхронный. Python SDK поддерживает это напрямую.

Этот пример выполняет ту же задачу, что и маршрут на TypeScript, но на Python:

  • открывает асинхронный клиент MyStars на время запроса;
  • запрашивает котировку Premium в usdt_ton;
  • проверяет получателя до создания заказа;
  • возвращает безопасное сообщение об ошибке, если получатель не может получить Premium;
  • создаёт заказ с callback URL для обновлений статуса;
  • возвращает котировку и заказ, чтобы бот мог сохранить их и показать пользователю следующий шаг.
from mystars_faas import AsyncMyStarsClient

async def create_premium_order(username: str, months: int, local_order_id: str):
    async with AsyncMyStarsClient.production(MYSTARS_API_KEY) as client:
        quote = await client.get_pricing(
            type="premium",
            months=months,
            payment_currency="usdt_ton",
        )

        recipient = await client.check_recipient(username, type="premium")
        if not recipient.eligible:
            return {"ok": False, "message": recipient.telegram_message}

        order = await client.create_order(
            type="premium",
            recipient=username,
            months=months,
            payment_currency="usdt_ton",
            callback_url="https://your-app.example.com/webhooks/mystars",
            idempotency_key=f"local-{local_order_id}",
        )

        return {"ok": True, "quote": quote, "order": order}

При переносе решения в боевую среду используйте точную обработку денежных значений, храните API-ключ в переменной окружения и сохраняйте инструкцию по оплате ровно в полученном виде. Если инструкция содержит memo/comment, считайте его данными, а не текстом, который можно переписать.

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

Добавьте проверку вебхука до запуска

Интеграция в стиле Fragment API не завершена, когда заработало создание заказа. Приложению также нужен надёжный путь получения статуса.

Минимальный обработчик вебхука:

  1. Получите необработанное тело запроса.
  2. Прочитайте заголовок X-Faas-Signature.
  3. Проверьте подпись секретом вебхука.
  4. Дедуплицируйте по ID и статусу заказа MyStars.
  5. Обновляйте локальный заказ только при допустимом переходе.
  6. Уведомляйте пользователя через Telegram-бота или Mini App.

SDK TypeScript документирует такие помощники для вебхуков, как constructEvent, middleware для Express и поддержку Fastify. Python SDK включает WebhookVerifier и интеграции с распространёнными веб-фреймворками Python.

Сохраните задачу опроса или сверки как резервный вариант. Вебхуки — быстрый путь; сверка спасает, когда в 3 часа ночи возникает пограничный сетевой случай.

Используйте blueprint-бот как рабочий ориентир

Python blueprint-бот MyStars — лучший источник, если вы хотите увидеть все движущиеся части вместе. Для исполнения он использует mystars-faas==0.1.3, сервер aiohttp для health checks и вебхуков MyStars, Postgres и Redis для состояния, мониторинг TON Center для платежей в сети и админ-команды для маржи и сверки.

Не считайте blueprint шаблоном бренда. Относитесь к нему как к инженерной карте:

  • где создавать локальный заказ;
  • где вызывать проверки получателя;
  • где применять маржу;
  • где отслеживать платёж;
  • где вызывать исполнение;
  • где редактировать карточку заказа Telegram после финального статуса.

Аккаунт MyStars на GitHub также публикует репозитории SDK, поэтому при более глубокой отладке, чем позволяет README, можно изучить исходный код, примеры и структуру пакетов.

Серверные эндпоинты для вашего приложения

Небольшая production-готовая интеграция обычно начинается с таких маршрутов:

POST /api/faas/quote
POST /api/faas/recipient-check
POST /api/orders
POST /webhooks/mystars
GET  /api/orders/:id
POST /api/admin/reconcile

Telegram-бот или Mini App должны вызывать ваш собственный маршрут /api/orders, а не MyStars напрямую. Затем ваш маршрут сможет проверить пользователя, создать локальный заказ, вызвать SDK, сохранить возвращённый заказ на исполнение и отдать только безопасные поля, которые нужны клиенту.

Платёжные реквизиты, которые пользователи не должны угадывать

Если продукт показывает экран оплаты, будьте точны. В сценариях MyStars USDT означает USDT в TON. Другие сети USDT не взаимозаменяемы. Для нативного маршрута текущие примеры API по-прежнему могут использовать payment_currency: "ton"; в тексте для покупателя используйте Gram / GRAM (ex. TON) для токена и TON для сети.

Читайте поле expires_at заказа, а не зашивайте тайм-аут платежа. В документации указано, что окно оплаты было продлено до 1 часа, а expires_at остаётся источником истины.

Что протестировать до реального трафика

Проведите эти проверки, прежде чем отправлять пользователей в этот сценарий:

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

Это не самая эффектная часть работы, но именно она делает бота Telegram Stars надёжным, а не экспериментальным.

FAQ

Это прямой публичный Fragment API?

MyStars FaaS — это уровень Fragment as a Service. Ваше приложение интегрируется с API и SDK MyStars, а MyStars обрабатывает процесс исполнения за этим интерфейсом.

Можно использовать это из Telegram Mini App?

Да. Храните API-ключ на бэкенде. Mini App должна обращаться к вашему серверу, а сервер — к MyStars FaaS.

С какого пакета начать?

Для Node.js и TypeScript используйте @mystars-tg/faas-sdk. Для Python и асинхронных Telegram-ботов используйте mystars-faas.

Нужен ли blueprint-бот?

Нет, но он полезен, если вы создаёте бота в стиле реселлера с платежами, админ-командами, сверкой и обновлениями статуса.

Какой первый этап наиболее безопасен?

Соберите один сквозной тест: котировка → проверка получателя → локальный заказ → заказ MyStars → проверенный вебхук или обновление через опрос. После его успешной работы добавьте маржу, политику возвратов, админ-инструменты и процессы поддержки.

Для справочника API, ссылок на SDK и заметок о текущем контракте начните с документации MyStars.

Back to Blog