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 查询：

GET /v1/fragment/order/{order_id}

目前没有：

• 直接使用 client_order_id 查询订单的独立 API；

• Premium 订单完成或失败的专用 Webhook。

建议保存创建订单时返回的 order_id，并定时查询最终状态。

8. 请求 timeout 后，能否使用相同 client_order_id 重试？

可以，且强烈建议重试时使用完全相同的 client_order_id。

如果原订单已经创建，系统会直接返回原订单，不会重新创建或再次扣款。重复请求响应类似：

{
  "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，如何处理？

请先查询：

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 价格在哪里获取？

可通过以下接口查询：

GET /public/premium_price

示例响应：

{
  "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=

完整请求：

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 秒一次，并设置退避策略。