Back to Blog
FRAGMENT API

Telegram 应用和机器人的 Fragment API SDK 指南

MyStars.tg Team13 min read

大多数 Telegram 商业构想在原型完成后都会遇到同一堵墙：机器人或 Mini App 很容易搭建，但 Telegram Stars 和 Telegram Premium 的履约仍需要可靠的后端流程。这正是开发者会搜索 Fragment API 的原因。

MyStars FaaS 提供了这一缺失层。FaaS 即 Fragment 即服务（Fragment as a Service）：你的 Telegram 产品保留用户体验和订单数据库，而 MyStars 通过 API、官方 SDK 及已签名的状态更新提供履约工作流。

使用 MyStars FaaS 的 Telegram 应用和机器人 Fragment API SDK 指南，涵盖 TypeScript 与 Python SDK、Webhook 和履约
面向 Telegram 应用和机器人的实用 Fragment API SDK 架构，采用 MyStars FaaS。

当你需要接入真正的 Telegram 应用、机器人、市场平台、创作者工具或转售商流程，而不只是阅读另一篇 API 概览时，请使用本指南。

清晰的架构：前端是 Telegram API，后端是 Fragment API

保持边界清晰。

你的 Telegram API 层 负责用户可见的部分：机器人命令、内联键盘、Mini App 页面、订单卡片、消息和支持回复。

你的 服务器层 负责业务逻辑：本地订单、利润率、反欺诈规则、管理控制、数据库写入和支持凭证。

MyStars FaaS 层 负责 Fragment 即服务工作流：定价、收件人检查、订单创建、付款指引和履约状态。

这种分层对安全至关重要。不要把 MyStars API 密钥放在 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

这两个包均作为官方 MyStars FaaS SDK 发布，并将构建者引导回交互式 API 文档。当前包文档说明其兼容 FaaS API v1.9.0；在对照 API 参考检查 SDK 示例时，这一点很有用。

使用 TypeScript 构建第一个后端路由

第一个路由不应试图包办一切。先从一个仅在服务器端执行的操作开始：它会报价、检查收件人，并基于你自己的本地订单 ID 创建一笔履约订单。

在阅读代码前，先用通俗语言了解它的作用：

  • 使用 MYSTARS_API_KEY 在后端创建 MyStars 客户端；
  • 向 MyStars 查询所选 Telegram Stars 数量的当前价格；
  • 检查该 Telegram 用户名是否可以接收产品；
  • 如果收件人不符合资格，则及早停止，而不是创建无效订单；
  • 以你自己稳定的 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(...) 表示请求会发送到正式的 MyStars API；在准备好承接真实流量前，请先在自己的系统中使用测试订单或本地订单。
  • getPricing(...) 会为后端提供当前报价。不要在机器人 UI 中硬编码价格。
  • payment_currency: "ton" 是此 SDK 示例中原生付款路径的 API 枚举值/名称。在产品 UI 中，请将该路径标记为 Gram 或 Gram（原 TON）。TON 应保留为区块链/网络名称。
  • checkRecipient(...) 可避免买家为无法履约的用户名或产品付款。
  • callback_url 是 MyStars 在订单创建后发送订单状态更新的地址。
  • idempotencyKey 是防止重复订单的保护措施。它应来自数据库订单，而不是浏览器随机生成的值。

在异步 Python 中构建相同流程

Python 团队通常需要异步代码，因为其 Telegram 机器人框架已经是异步的。Python SDK 直接支持这一点。

本示例完成与 TypeScript 路由相同的工作，但采用 Python：

  • 在请求期间打开异步 MyStars 客户端；
  • 以 usdt_ton 查询 Telegram Premium 报价；
  • 在创建订单前检查收件人；
  • 如果收件人无法接收 Telegram Premium，则返回安全的错误消息；
  • 使用用于状态更新的回调 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 机器人仍需要围绕此函数自行提供处理器、按钮、数据库写入和用户消息。

上线前添加 Webhook 验证

仅仅能够创建订单，并不意味着 Fragment API 风格的集成已经完成。应用还需要一条可信的状态路径。

最低限度的 Webhook 处理器：

  1. 接收原始请求正文。
  2. 读取 X-Faas-Signature 请求头。
  3. 使用 Webhook 密钥验证签名。
  4. 按 MyStars 订单 ID 和状态去重。
  5. 仅在状态转换有效时更新本地订单。
  6. 通过 Telegram 机器人或 Mini App 通知用户。

TypeScript SDK 文档列出了 constructEvent、Express 中间件和 Fastify 支持等 Webhook 辅助工具。Python SDK 包含 WebhookVerifier 以及常见 Python Web 框架的集成。

保留一个轮询或对账任务作为备份。Webhook 是快速路径；当凌晨 3 点出现网络边缘情况时，对账机制能帮你兜底。

将蓝图机器人作为可运行的参考

当你想同时了解所有组成部分时，MyStars Python 蓝图机器人是最佳参考。它使用 mystars-faas==0.1.3 进行履约，使用 aiohttp 服务器提供健康检查和 MyStars Webhook，使用 Postgres 和 Redis 管理状态，使用 TON Center 监控链上付款，并通过管理命令处理利润率和对账。

不要把蓝图当作品牌模板，而应将其视为工程地图：

  • 在何处创建本地订单；
  • 在何处调用收件人检查；
  • 在何处应用利润率；
  • 在何处监控付款；
  • 在何处调用履约；
  • 在终态后于何处编辑 Telegram 订单卡片。

MyStars GitHub 账户也发布 SDK 仓库；当你需要比 README 更深入地调试时，可以检查源代码、示例和包结构。

在自己的应用中创建后端端点

一个小型、达到生产级别的集成通常从以下路由开始：

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 on TON。其他 USDT 网络不可互换。对于原生路径，当前 API 示例仍可能使用 payment_currency: "ton"；面向买家的文案应将代币称为 Gram / GRAM（原 TON），并将 TON 用作网络名称。

请读取订单的 expires_at 字段，而不要硬编码付款超时时间。文档指出付款窗口已延长至 1 小时，而 expires_at 仍是唯一可信来源。

面向真实流量前的测试项

在将用户引入该流程前，请完成以下检查：

  • 一笔 Telegram Stars 订单和一笔 Telegram Premium 订单；
  • 一条不符合资格的收件人路径；
  • 使用同一幂等性密钥重试创建订单；
  • 有效和无效的 Webhook 签名；
  • 重复投递的 Webhook 事件；
  • 过期订单的处理；
  • 支持凭证：用户名、本地订单 ID、MyStars 订单 ID、付款哈希、memo/comment 和状态；
  • 仅限管理员访问的利润率、对账、退款、广播和手动履约命令。

这部分并不炫目，但它能让 Telegram Stars 机器人给人可靠而非试验性的感受。

FAQ

这是直接公开的 Fragment API 吗？

MyStars FaaS 是一个 Fragment 即服务层。你的应用会集成 MyStars API 和 SDK，而 MyStars 负责该接口背后的履约工作流。

可以从 Telegram Mini App 中使用它吗？

可以。请将 API 密钥保留在后端。Mini App 应调用你的服务器，而你的服务器应调用 MyStars FaaS。

应从哪个包开始？

Node.js 和 TypeScript 请使用 @mystars-tg/faas-sdk。Python 和异步 Telegram 机器人请使用 mystars-faas。

是否需要蓝图机器人？

不一定，但如果你正在构建带有付款、管理命令、对账和状态更新功能的转售商式机器人，它会很有帮助。

最安全的第一个里程碑是什么？

构建一个端到端测试：报价 → 收件人检查 → 本地订单 → MyStars 订单 → 已验证的 Webhook 或轮询更新。完成后，再添加利润率、退款政策、管理工具和支持工作流。

如需 API 参考、SDK 链接和当前契约说明，请从 MyStars 文档 开始。

Back to Blog