物联卡订单管理

Telegram 用户

Bot 首次收到 /start 时自动创建

用户	Telegram ID	余额	状态	创建时间	操作

按卡计费

订单创建时保存价格快照，后续改价不会影响历史订单

API 对接文档

供 Telegram Bot、业务系统和运维工具调用。所有请求与响应均使用 JSON。

v1

接口鉴权

外部系统调用管理接口时，在请求头传入独立管理 API 密钥。Telegram Bot 调用 Bot 接口时使用独立 Bot 密钥。密钥由服务端环境变量配置，不使用后台登录账号和密码。

X-Admin-Key: your-admin-api-key
X-Bot-Key: your-bot-api-key
Content-Type: application/json

管理后台网页使用安全会话 Cookie 登录。外部程序不要调用登录接口，也不要保存管理员账号密码。

通用规则

基础地址	`http://127.0.0.1:18080`，生产环境替换为实际 HTTPS 域名
数据格式	`application/json; charset=utf-8`
ICCID	18 至 22 位数字；单次最多 500 张；全局不可重复提交
移动接入号	移动订单每个 ICCID 必须对应一个 `144` 开头的纯数字接入号，接入号全局不可重复
运营商	`移动`、`联通`、`电信`、`广电`
订单状态	`未处理`、`处理中`、`已完成`、`异常`；新订单默认为未处理

管理接口

以下接口统一携带 X-Admin-Key。

方法	路径	用途
GET	`/api/admin/dashboard`	订单、卡量、金额、用户统计
GET	`/api/admin/orders?status=&carrier=&keyword=`	查询和筛选订单
POST	`/api/admin/orders`	管理员代用户提交订单
PATCH	`/api/admin/orders/{id}`	修改状态与备注
GET	`/api/admin/users`	查询 Telegram 用户
PATCH	`/api/admin/users/{id}`	启用或停用用户
POST	`/api/admin/users/{id}/balance`	充值或扣减余额
GET / PUT	`/api/admin/rates`	查询或保存四类单价
GET / PUT	`/api/admin/config`	查询或保存 Bot 与群组配置、群计数
POST	`/api/admin/group-counters/reset`	清零指定运营商群的订单数和卡量

Bot 接口

以下接口统一携带 X-Bot-Key。

方法	路径	用途
POST	`/api/bot/users/sync`	按 Telegram 资料创建或更新用户
GET	`/api/bot/config`	读取按钮、价格、开关和目标群映射
GET	`/api/bot/runtime-config`	Bot 进程读取运行凭据，不向管理页面返回明文
POST	`/api/bot/orders`	按 Telegram ID 提交订单并扣款
POST	`/api/bot/orders/{id}/forwarded`	确认成功转发并累计目标群订单数、卡量
POST	`/api/bot/orders/{id}/status`	校验接收群并回写群内按钮选择的状态
GET	`/api/bot/me?telegram_id={id}`	查询用户余额与最近 5 个订单

Bot 下单示例

POST/api/bot/orders

请求

{
  "telegram_id": 123456789,
  "carrier": "移动",
  "items": [
    {"iccid": "8986001234567890123", "access_number": "1441234567890"},
    {"iccid": "8986001234567890124", "access_number": "1441234567891"}
  ]
}

成功响应 · 201

{
  "order": {
    "id": 1,
    "order_no": "WL20260719000001",
    "carrier": "移动",
    "item_count": 2,
    "status": "未处理",
    "unit_price": 1.0,
    "total": 2.0
  },
  "balance": 8.0,
  "group": {
    "chat_id": "-1001234567890",
    "chat_name": "移动订单群"
  }
}

错误处理

失败响应统一返回 {"error":"错误说明"}。余额不足、ICCID 重复或格式错误时，订单和扣款都会回滚。

400	字段缺失、格式错误或不支持的值
401	API 密钥缺失或无效
403	用户停用或 Bot 下单功能关闭
404	用户、订单或接口不存在
409	余额不足、ICCID 重复或业务状态冲突
500	服务端内部错误

业务总览

最近订单