接口文档

所有接口均需按接入指南中的规范签名。路径中的 /v1 为版本号，后续升级保持向后兼容。

通用响应

{
  "code": 0,
  "message": "success",
  "requestId": "req_20260929_8f3a",
  "data": {}
}

code = 0 表示成功；非 0 时 message 为可读的错误信息，data 为空对象。完整错误码见错误码表。反馈问题时请附上 requestId。

商品列表

GET /v1/goods

请求参数（query）

参数	必填	类型	说明
`category`	否	字符串	品类：`telecom` 话费流量 / `video` 视频音乐 / `food` 美食餐饮 / `travel` 出行加油 / `ecard` 电商卡券 / `life` 生活服务 / `reading` 阅读教育 / `health` 运动健康
`page`	否	整数	页码，默认 1
`pageSize`	否	整数	每页条数，默认 20，最大 100

响应字段（data）

字段	类型	说明
`total`	整数	商品总数
`items[].goodsId`	字符串	商品编号
`items[].name`	字符串	商品名称
`items[].category`	字符串	品类编码，取值同请求参数
`items[].faceValue`	字符串	面值（元）
`items[].price`	字符串	结算价（元）
`items[].type`	字符串	`recharge` 直充 / `card` 卡密
`items[].status`	字符串	`on` 在售 / `off` 下架
`items[].stock`	字符串	`sufficient` 充足 / `tight` 紧张 / `out` 缺货

示例

{
  "code": 0,
  "message": "success",
  "requestId": "req_20260929_1a2b",
  "data": {
    "total": 128,
    "items": [
      { "goodsId": "G100001", "name": "话费快充 50 元", "category": "telecom", "faceValue": "50.00", "price": "49.50", "type": "recharge", "status": "on", "stock": "sufficient" },
      { "goodsId": "G200013", "name": "视频平台会员月卡", "category": "video", "faceValue": "25.00", "price": "22.80", "type": "recharge", "status": "on", "stock": "tight" }
    ]
  }
}

商品详情

GET /v1/goods/{goodsId}

响应字段（data）

包含商品列表中的全部字段，另有：

字段	类型	说明
`description`	字符串	商品说明
`usageNotes`	字符串	使用须知（可直接展示给用户）
`validDays`	整数	卡密有效天数，直充类为 0
`accountRule`	字符串	直充账号规则：`mobile` 手机号 / `email` 邮箱 / `none` 无需账号

创建订单

POST /v1/orders

请求参数（body）

参数	必填	类型	说明
`outOrderNo`	是	字符串	您的唯一订单号，不超过 64 字符；重复提交返回原订单，不重复扣款
`goodsId`	是	字符串	商品编号
`quantity`	是	整数	卡密类 1–100；直充类固定为 1
`account`	直充类必填	字符串	充值账号，按商品的 `accountRule` 校验
`notifyUrl`	否	字符串	覆盖控制台配置的默认回调地址，必须为 HTTPS

响应字段（data）

字段	类型	说明
`orderId`	字符串	平台订单号
`outOrderNo`	字符串	您的订单号
`status`	字符串	创建后固定为 `processing`；沙箱环境 10 秒内变为终态
`cards[]`	数组	卡密类且同步出卡时返回；元素含 `cardNo`、`cardPwd`（AES 加密，解密方式见常见问题）、`expireAt`
`createdAt`	字符串	创建时间

示例

{
  "outOrderNo": "ORD20260929001",
  "goodsId": "G100001",
  "quantity": 1,
  "account": "13800000000",
  "notifyUrl": "https://your-domain.com/callback/tusi"
}

{
  "code": 0,
  "message": "success",
  "requestId": "req_20260929_9c4d",
  "data": {
    "orderId": "T2026092912345678",
    "outOrderNo": "ORD20260929001",
    "status": "processing",
    "cards": [],
    "createdAt": "2026-09-29T10:00:00+08:00"
  }
}

查询订单

GET /v1/orders/{outOrderNo}

响应字段（data）

字段	类型	说明
`orderId`	字符串	平台订单号
`outOrderNo`	字符串	您的订单号
`goodsId`	字符串	商品编号
`quantity`	整数	数量
`status`	字符串	`processing` 受理中 / `success` 成功 / `failed` 失败 / `refunded` 已退款
`cards[]`	数组	卡密类订单的卡密列表，字段同创建订单
`failReason`	字符串	失败原因，仅 `failed` / `refunded` 时返回
`finishedAt`	字符串	到达终态的时间

示例

{
  "code": 0,
  "message": "success",
  "requestId": "req_20260929_e5f6",
  "data": {
    "orderId": "T2026092912345678",
    "outOrderNo": "ORD20260929001",
    "goodsId": "G100001",
    "quantity": 1,
    "status": "success",
    "cards": [],
    "failReason": "",
    "finishedAt": "2026-09-29T10:00:08+08:00"
  }
}

账户余额

GET /v1/account/balance

响应字段（data）

字段	类型	说明
`balance`	字符串	可用余额（元）
`creditLimit`	字符串	授信额度（元），无授信为 `"0.00"`
`currency`	字符串	固定为 `CNY`

示例

{
  "code": 0,
  "message": "success",
  "requestId": "req_20260929_7a8b",
  "data": { "balance": "12580.00", "creditLimit": "0.00", "currency": "CNY" }
}

余额低于近 7 日日均消耗时，控制台会发送短信与邮件提醒；也可以定时调用本接口自行监控。