AutoSub 公开兑换接口说明

1. 接口范围

本文档说明 AutoSub 前台兑换页使用的 4 个公开接口，接口统一位于 /api/v1/sub 前缀下。

基础域名：

环境	域名	说明
生产环境	`{你的服务域名}`	对外调用时请替换为实际部署域名，例如 `https://api.example.com`。
本地调试	`http://127.0.0.1:8088`	本地启动 `admin-server` 后可直接调用。
前端同域	当前站点域名	`client-web` 通过 `/api` 反向代理到 `admin-server` 时使用。

完整请求地址格式：{基础域名} + {接口路径}。例如本地调试 verifyCdk 的完整地址为 http://127.0.0.1:8088/api/v1/sub/verifyCdk。

顺序	接口	方法	路径	作用
1	校验并锁定 CDK	POST	`/api/v1/sub/verifyCdk`	校验 CDK 是否可用，并生成短期有效的 `activation_token`。
2	预检 ChatGPT 账号	POST	`/api/v1/sub/precheckAccount`	校验 ChatGPT 登录态是否有效，并确认账号是 Free 账号。
3	提交订阅兑换任务	POST	`/api/v1/sub/redeem`	使用 CDK、`activation_token` 和登录态提交异步兑换任务。
4	查询/轮询 CDK 订单	POST	`/api/v1/sub/queryOrder`	查询 CDK 当前状态和最近一笔兑换订单；也用于 `redeem` 后轮询异步任务结果。

2. 公共约定

请求体类型：所有接口均使用 application/json。

HTTP 状态码：正常业务响应均返回 HTTP 200。

业务状态码：响应体 code=200 表示业务成功，code=0 表示业务失败。

错误信息：业务失败时读取响应体 error 字段，前端会将该字段展示给用户。

登录态 token：precheckAccount 和 redeem 使用的 token 是前端把完整 ChatGPT session JSON 通过 zstd 压缩并 base64 编码后的字符串，格式为 zstd64:<base64>。

兑换执行方式：redeem 当前为异步提交任务。接口成功后通常返回 status=processing 和 order_no，最终成功或失败需要调用 queryOrder 查询。

3. 前端调用流程

用户输入 CDK，前端调用 verifyCdk。

verifyCdk 成功后，前端保存 activation_token、expires_in、expires_at、product_name 和 plan。

用户粘贴 ChatGPT session JSON，前端先在本地解析 accessToken 和邮箱，再压缩成 zstd64 token。

前端调用 precheckAccount 校验账号。只有 plan_type=free 且 eligible=true 时允许继续。

前端调用 redeem 提交兑换任务。

redeem 成功后，前端调用 queryOrder 轮询订单状态；如果订单仍是 processing，页面继续等待或提示用户稍后再查。

4. CDK 状态说明

状态	中文含义	备注
`unused`	可兑换	CDK 未被使用，可进入兑换流程。
`activating`	已锁定或处理中	`verifyCdk` 成功后进入该状态；提交兑换任务后也可能保持该状态直到订单完成。
`activated`	已兑换	订阅兑换成功后进入该状态。
`disabled`	已禁用	管理端禁用，不能兑换。
`expired`	已过期	CDK 或批次超过有效期，不能兑换。

5. 订单状态说明

状态	中文含义	前端映射	备注
`processing`	处理中	`PROCESSING`	后台任务还在执行，轮询时需要继续查询。
`success`	成功	`COMPLETED`	订阅已完成。
`failed`	失败	`CARD_RETURNED`	订阅失败，失败原因查看订单 `error`。

6. 轮询订单说明

redeem 是异步提交接口，返回 code=200 只表示兑换任务已经提交或已有处理中订单，不代表订阅已经最终成功。前端需要使用 queryOrder 轮询订单结果。

项目	建议	说明
轮询接口	`POST /api/v1/sub/queryOrder`	与手动查询订单共用同一个接口。
触发时机	`redeem` 返回 `code=200` 后开始	优先使用同一个 CDK 查询。
轮询间隔	3 秒	当前 `client-web` 使用 3 秒间隔。
继续条件	`order.status=processing`	订单仍在执行，继续等待。
停止条件	`order.status=success` 或 `order.status=failed`	成功或失败都属于最终状态，应停止轮询。
暂无订单	`order=null`	CDK 存在但暂未创建订单；如果刚提交兑换，可短暂重试。
失败处理	`code=0` 或 `order.error` 非空	展示 `error`，必要时允许用户稍后重新查询。

推荐前端在轮询超过 3 分钟仍为 processing 时，提示用户订单仍在处理中，可稍后通过订单查询页面继续查询。

7. 接口详情

7.1 校验并锁定 CDK

方法：POST

路径：/api/v1/sub/verifyCdk

完整地址：{你的服务域名}/api/v1/sub/verifyCdk；本地调试为 http://127.0.0.1:8088/api/v1/sub/verifyCdk

说明：校验 CDK 是否存在且可用。成功后后端会创建 CDK 锁定记录，并返回短期有效的 activation_token。后续提交兑换任务时必须携带该令牌。

请求参数

字段	类型	必填	说明	示例
`cdk`	string	是	CDK 兑换码。前端会去除首尾空白后提交。	`AUTO-SUB-ABCDEFGH`

响应字段

字段	类型	说明
`code`	integer	业务状态码。`200` 表示锁定成功，`0` 表示失败。
`error`	string	失败原因；成功时为空字符串。
`activation_token`	string	激活令牌。`redeem` 时必须原样提交。
`expires_in`	integer	激活令牌有效期，单位秒。默认 180 秒，可通过运行配置调整，范围 60-1800 秒。
`expires_at`	string	激活令牌过期时间，ISO 8601 格式。
`product_name`	string	面向用户展示的产品名称。
`plan`	string	后端订阅计划标识。

成功示例

{
  "code": 200,
  "error": "",
  "activation_token": "7f2b4c6d8e...",
  "expires_in": 180,
  "expires_at": "2026-06-22T12:10:00Z",
  "product_name": "ChatGPT Plus",
  "plan": "chatgptplusplan"
}

失败示例

{
  "code": 0,
  "error": "CDK 不存在"
}

7.2 预检 ChatGPT 账号

方法：POST

路径：/api/v1/sub/precheckAccount

完整地址：{你的服务域名}/api/v1/sub/precheckAccount；本地调试为 http://127.0.0.1:8088/api/v1/sub/precheckAccount

说明：校验 ChatGPT 登录态是否有效，并确认账号套餐类型。只有 Free 账号允许继续兑换。

请求参数

字段	类型	必填	说明	示例
`token`	string	是	完整 ChatGPT session JSON 压缩后的 token，格式为 `zstd64:<base64>`。	`zstd64:KLUv/QBY...`

响应字段

字段	类型	说明
`code`	integer	业务状态码。`200` 表示账号可兑换，`0` 表示失败。
`error`	string	失败原因；成功时为空字符串。
`email`	string	从登录态解析出的账号邮箱。
`name`	string	从登录态解析出的账号名称，可能为空。
`plan_type`	string	账号套餐类型。常见值：`free`、`plus`、`pro`、`team`、`enterprise`。
`expires_at`	string	当前订阅过期时间。Free 账号通常为空。
`eligible`	boolean	是否满足兑换条件。成功时为 `true`。

成功示例

{
  "code": 200,
  "error": "",
  "email": "user@example.com",
  "name": "YY",
  "plan_type": "free",
  "eligible": true
}

失败示例

{
  "code": 0,
  "error": "当前账号是 Plus，仅支持 Free 账号兑换",
  "email": "user@example.com",
  "name": "YY",
  "plan_type": "plus",
  "eligible": false
}

7.3 提交订阅兑换任务

方法：POST

路径：/api/v1/sub/redeem

完整地址：{你的服务域名}/api/v1/sub/redeem；本地调试为 http://127.0.0.1:8088/api/v1/sub/redeem

说明：提交订阅兑换任务。后端会再次校验登录态、账号套餐、CDK 锁定关系，然后创建订单并异步执行订阅。

请求参数

字段	类型	必填	说明	示例
`token`	string	是	与 `precheckAccount` 相同的 `zstd64` 登录态 token。	`zstd64:KLUv/QBY...`
`cdk`	string	是	已通过 `verifyCdk` 锁定的 CDK。	`AUTO-SUB-ABCDEFGH`
`activation_token`	string	是	`verifyCdk` 返回的激活令牌。	`7f2b4c6d8e...`

响应字段

字段	类型	说明
`code`	integer	业务状态码。`200` 表示任务已提交或已有处理中的订单，`0` 表示提交失败。
`error`	string	失败原因；成功时为空字符串。
`plan`	string	订阅计划标识。
`product_name`	string	面向用户展示的产品名称。
`order_no`	string	订单号。提交成功后返回。
`status`	string	订单当前状态。新提交任务通常为 `processing`。

成功示例

{
  "code": 200,
  "error": "",
  "plan": "chatgptplusplan",
  "product_name": "ChatGPT Plus",
  "order_no": "SO202606220001",
  "status": "processing"
}

失败示例

{
  "code": 0,
  "error": "CDK 未验证或已失效",
  "plan": "chatgptplusplan",
  "product_name": "ChatGPT Plus"
}

7.4 查询/轮询 CDK 订单

方法：POST

路径：/api/v1/sub/queryOrder

完整地址：{你的服务域名}/api/v1/sub/queryOrder；本地调试为 http://127.0.0.1:8088/api/v1/sub/queryOrder

说明：根据 CDK 查询 CDK 状态、产品信息和最近一笔兑换订单。提交兑换任务后，前端用该接口轮询异步执行结果。

请求参数

字段	类型	必填	说明	示例
`cdk`	string	是	要查询的 CDK。	`AUTO-SUB-ABCDEFGH`

响应字段

字段	类型	说明
`code`	integer	业务状态码。`200` 表示查询成功，`0` 表示查询失败。
`error`	string	失败原因；成功时为空字符串。
`cdk_status`	string	CDK 当前状态。
`product_name`	string	CDK 关联的产品展示名称。即使暂无订单，也会尽量返回。
`plan`	string	CDK 关联的订阅计划标识。即使暂无订单，也会尽量返回。
`order`	object 或 null	最近一笔订单。CDK 存在但尚未提交兑换任务时为 `null`。

order 字段

字段	类型	说明
`order_no`	string	订单号。
`account`	string	兑换的 ChatGPT 账号邮箱。
`status`	string	订单状态：`processing`、`success`、`failed`。
`plan`	string	订阅计划标识。
`product_name`	string	产品展示名称。
`country`	string	下单国家/地区，两位代码。
`currency`	string	支付币种。
`amount_minor`	integer	订单金额，使用最小货币单位。
`error`	string	订单失败原因。订单成功或处理中时通常为空字符串。
`started_at`	string 或 null	订单开始执行时间。
`finished_at`	string 或 null	订单完成时间；处理中时为空。
`duration_ms`	integer	订单执行耗时，单位毫秒。处理中时通常为 0。
`payment_card`	string	支付卡掩码，仅显示后四位；无支付卡或尚未使用时为空。

有订单示例

{
  "code": 200,
  "error": "",
  "cdk_status": "activating",
  "product_name": "ChatGPT Plus",
  "plan": "chatgptplusplan",
  "order": {
    "order_no": "SO202606220001",
    "account": "user@example.com",
    "status": "processing",
    "plan": "chatgptplusplan",
    "product_name": "ChatGPT Plus",
    "country": "PH",
    "currency": "PHP",
    "amount_minor": 98214,
    "error": "",
    "started_at": "2026-06-22T12:05:00Z",
    "finished_at": null,
    "duration_ms": 0,
    "payment_card": ""
  }
}

暂无订单示例

{
  "code": 200,
  "error": "",
  "cdk_status": "unused",
  "product_name": "ChatGPT Plus",
  "plan": "chatgptplusplan",
  "order": null
}

查询失败示例

{
  "code": 0,
  "error": "CDK 不存在或不可查询"
}

AutoSub 公开兑换接口说明

1. 接口范围#

2. 公共约定#

3. 前端调用流程#

4. CDK 状态说明#

5. 订单状态说明#

6. 轮询订单说明#

7. 接口详情#

7.1 校验并锁定 CDK#

请求参数#

响应字段#

成功示例#

失败示例#

7.2 预检 ChatGPT 账号#

请求参数#

响应字段#

成功示例#

失败示例#

7.3 提交订阅兑换任务#

请求参数#

响应字段#

成功示例#

失败示例#

7.4 查询/轮询 CDK 订单#

请求参数#

响应字段#

order 字段#

有订单示例#

暂无订单示例#

查询失败示例#

1. 接口范围

2. 公共约定

3. 前端调用流程

4. CDK 状态说明

5. 订单状态说明

6. 轮询订单说明

7. 接口详情

7.1 校验并锁定 CDK

请求参数

响应字段

成功示例

失败示例

7.2 预检 ChatGPT 账号

请求参数

响应字段

成功示例

失败示例

7.3 提交订阅兑换任务

请求参数

响应字段

成功示例

失败示例

7.4 查询/轮询 CDK 订单

请求参数

响应字段

order 字段

有订单示例

暂无订单示例

查询失败示例