> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/api-reference/fragment/telegram-premium-api-faq-zh.md). # Telegram 会员常见问题 CatFee Telegram Premium API 购买资格、订单状态、幂等机制、错误处理、价格及签名规则。 本文根据当前系统实现，说明 Telegram Premium 的购买资格、订单状态、幂等机制、错误处理、价格及 API 签名规则。 ## 一、账号与订阅资格 ### 1. 当前已有 Premium，能否继续购买 3/6/12 个月？ CatFee 会正常提交购买请求，但是否可以叠加时长取决于 Telegram/Fragment 对该账号当前订阅状态的判断，不能保证一定叠加成功。 此外，同一 CatFee 账户针对相同 Telegram username 和相同月份套餐，6 小时内不能重复创建订单。 ### 2. 通过其他渠道开通过 Premium，能否再次通过 CatFee 购买？ 对于 App Store、Google Play、@PremiumBot、Gift/Fragment 或 CatFee 等历史渠道，CatFee 本地不会永久限制账号。 * Premium 当前仍有效：可以提交，但最终能否成功由 Telegram/Fragment 判断。 * Premium 已到期：可以再次通过 CatFee 购买。 * 以前通过 CatFee 开通过：到期后可以再次购买。 ### 3. “曾在其他渠道订阅过 Premium 则无法开通”是否为永久限制？ 不是 CatFee 系统层面的永久限制。 CatFee 不保存用户过去通过何种渠道订阅 Premium 的记录。实际能否购买以 Telegram/Fragment 在下单时返回的资格判断为准。 ### 4. 以前通过 CatFee 开通过，过期后能否续开？ 可以。CatFee 没有“开通过一次后永久不能再购买”的限制。 ## 二、订单开通方式与处理状态 ### 5. Premium API 是直接开通，还是返回 Gift Link？ API 不会向调用方返回 Gift Link，也不需要用户手动领取。 系统会通过 Fragment Gift 流程为指定账号购买，并由 CatFee 后台钱包完成支付。API 返回的是 CatFee 订单信息。 ### 6. API 返回成功是否代表已经实际开通？ 不一定。API 成功通常代表订单已经受理或余额扣款完成，还需要检查返回的 `data.status`： | 状态 | 含义 | | ---------------- | -------------------- | | `UNPAID` | 尚未完成余额扣款 | | `PAID` | 已扣款，等待后台购买 | | `CREATED` | Fragment 订单已创建，支付处理中 | | `FINISHED` | 后台确认支付交易已上链 | | `PAY_FAILED` | CatFee 余额支付失败 | | `CREATED_FAILED` | 接收账号或订单创建失败 | | `BUY_FAILED` | 后台购买失败 | 请不要只检查 `code=0`，还应继续查询订单状态，直至进入 `FINISHED` 或失败状态。 系统未提供承诺的平均或最大处理时间。正常订单通常需要数分钟完成；遇到排队或 Fragment、TON 网络异常时可能更久。 ## 三、订单查询与幂等 ### 7. 是否有订单查询 API 或 Webhook？ 支持使用 CatFee `order_id` 查询： ```http GET /v1/fragment/order/{order_id} ``` 目前没有： * 直接使用 `client_order_id` 查询订单的独立 API； * Premium 订单完成或失败的专用 Webhook。 建议保存创建订单时返回的 `order_id`，并定时查询最终状态。 ### 8. 请求 timeout 后，能否使用相同 client\_order\_id 重试？ 可以，且强烈建议重试时使用完全相同的 `client_order_id`。 如果原订单已经创建，系统会直接返回原订单，不会重新创建或再次扣款。重复请求响应类似： ```json { "code": 0, "sub_code": "SUCCESS", "sub_msg": "Duplicate order request, returning existing order", "data": { "order_id": "原订单ID", "client_order_id": "原client_order_id", "status": "PAID" } } ``` 当前系统没有设置明确的幂等记录过期时间；只要订单记录仍然存在，该 `client_order_id` 就会继续生效。 极端并发情况下，两个首次请求同时到达时，其中一个请求可能返回数据库冲突错误。因此建议同一 `client_order_id` 不要并发提交；timeout 后采用串行重试。 ### 9. 相同 client\_order\_id，但 username 或 months 不同会怎样？ 如果两次请求都是 Premium，系统会返回第一次创建的原订单，不会按照新的 username 或 months 创建订单。 因此必须保证： ``` 一个 client_order_id 永远只对应一组固定的 username 和 months ``` 如果同一个 `client_order_id` 已被 Stars 订单使用，则 Premium 请求会返回参数冲突错误。 ## 四、错误码与资金处理 ### 10. Premium API 有哪些错误码？ 目前使用通用错误码，并没有单独的 Premium 完整业务错误码体系。 | 场景 | code | 说明 | | ------------------------ | -----: | ------------------ | | 请求成功或订单受理 | `0` | 仍需检查 `data.status` | | username 格式错误 | `1` | 参数不合法 | | months 不是 3/6/12 | `1` | 不支持该套餐 | | client\_order\_id 不合法或冲突 | `1` | 参数错误 | | Telegram 账号不存在 | `3` | 未找到用户 | | USDT 余额不足 | `4` | 无法完成余额支付 | | 6 小时内重复提交相同套餐 | `4` | 重复订单限制 | | Fragment 返回异常 | `5` | 下游服务拒绝或返回异常 | | 未分类系统异常 | `9999` | 请联系客服处理 | “已有 Premium”“历史订阅渠道不支持”“地区限制”等目前没有独立 `sub_code`。如果这些问题发生在后台异步购买阶段，订单通常会变成 `BUY_FAILED`。 ### 11. Premium 开通失败是否扣余额？ 需要按失败阶段区分： * 参数错误、账号不存在、余额不足：发生在扣款前，不扣余额。 * `PAY_FAILED`：通常表示余额支付没有成功。 * 已进入 `PAID` 后发生 `CREATED_FAILED` 或 `BUY_FAILED`：余额可能已经扣除。 目前没有可对外承诺的自动退款流程或退款时限。对于扣款后购买失败的订单，需要提交订单信息，由客服人工核查或重新处理。 ## 五、未到账处理 ### 12. API 成功但用户未收到 Premium，如何处理？ 请先查询： ```http GET /v1/fragment/order/{order_id} ``` 如果订单仍为 `PAID` 或 `CREATED`，请继续等待并查询。 如果订单已经是 `BUY_FAILED`、`CREATED_FAILED`，或者显示 `FINISHED` 但用户仍未收到，请联系客服，并提供： * `order_id` * `client_order_id` * Telegram username * 购买月份 * 订单创建时间 * 当前订单状态 * 创建订单时的完整响应 * 用户未到账截图 * CatFee 会员 ID 或 API Key 标识 请勿提供 API Secret。 客服 Telegram：`@CatFee_James` ## 六、username 要求 ### 13. 必须有公开 username 吗？支持 numeric user ID 吗？ 当前 API 必须提交有效 Telegram username，支持以下格式： ``` username @username https://t.me/username ``` username 长度必须为 5～32 位，只能包含字母、数字和下划线。 目前不支持 Telegram numeric user ID。因此用户需要设置可被 Fragment 查询到的公开 username。 ### 14. 提交后用户修改 username，会影响订单吗？ 通常不会。 创建订单时，系统会根据原 username 查询并保存 Telegram/Fragment 接收人标识，后续购买优先使用该标识。但为避免异常，建议用户在订单完成前不要修改或删除 username。 ## 七、价格说明 ### 15. Premium API 价格在哪里获取？ 可通过以下接口查询： ```http GET /public/premium_price ``` 示例响应： ```json { "code": 0, "data": { "months3_usdt_sun": 12500000, "months6_usdt_sun": 16500000, "months12_usdt_sun": 29500000 } } ``` 金额单位为 USDT Sun： ``` 1 USDT = 1,000,000 Sun ``` 即上述示例分别为： * 3 个月：12.5 USDT * 6 个月：16.5 USDT * 12 个月：29.5 USDT API 价格由 CatFee 系统配置。系统目前没有价格变更 Webhook，建议在展示价格或下单前查询最新价格。 ## 八、API 签名 ### 16. `/v1/premium` 完整签名示例 假设使用以下参数： ``` API Secret: demo_api_secret Timestamp: 2026-08-25T08:08:08.888Z Method: POST ``` 最终 URL： ``` https://api.catfee.io/v1/premium?client_order_id=demo-20260825-001&months=3&username=alice_123 ``` 原始待签字符串： ``` 2026-08-25T08:08:08.888ZPOST/v1/premium?client_order_id=demo-20260825-001&months=3&username=alice_123 ``` 计算方式： ``` Base64(HMAC-SHA256(原始待签字符串, API Secret)) ``` 示例签名结果： ``` rYghhRU7GfvBX5zhdc8Kv5+jmy4GcvNBmh/CBQHa2S0= ``` 完整请求： ```bash curl -X POST \ 'https://api.catfee.io/v1/premium?client_order_id=demo-20260825-001&months=3&username=alice_123' \ -H 'CF-ACCESS-KEY: YOUR_API_KEY' \ -H 'CF-ACCESS-TIMESTAMP: 2026-08-25T08:08:08.888Z' \ -H 'CF-ACCESS-SIGN: rYghhRU7GfvBX5zhdc8Kv5+jmy4GcvNBmh/CBQHa2S0=' ``` 注意事项： * query string 参与签名； * 参数顺序必须与最终发送 URL 完全一致； * HTTP 方法必须使用大写 `POST`； * 签名字符串之间没有换行或分隔符； * 时间戳使用 UTC ISO-8601 格式； * 客户端与服务器时间偏差应控制在 30 秒以内。 ## 九、测试环境与安全限制 ### 17. 是否有 sandbox/test 环境？ 系统内部存在 Nile 测试模式，但当前公开文档没有提供正式的 Premium Sandbox 服务协议。 Nile 模式不会真实为 Telegram 账号开通 Premium，只用于验证鉴权、参数、扣款及订单流程，不能用于验证真实到账。 如需进行生产环境真实测试，当前最小套餐为 3 个月。建议使用专门的测试账号、唯一 `client_order_id`，并在测试前确认账户余额及最新价格。 ### 18. 是否建议设置 IP whitelist？Rate Limit 是多少？ Premium API 当前使用： * API Key； * API Secret； * HMAC-SHA256 签名； * UTC 时间戳防重放。 建议在账户或网关支持的情况下启用固定出口 IP 白名单，并妥善保管 API Secret。 目前没有公开的 Premium 专属 Rate Limit 数值。调用方应： * 避免并发重复提交相同订单； * 为每笔业务生成唯一 `client_order_id`； * timeout 后使用相同参数和相同 `client_order_id` 串行重试； * 查询订单时采用合理轮询间隔，例如 5～10 秒一次，并设置退避策略。