API指南

1. 接口范围

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

基础域名：

环境	域名	说明
生产环境	`https://autosub.site`	对外调用使用正式域名。

顺序	接口	方法	路径	作用
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	轮询兑换结果	POST	`/api/v1/sub/redeemResult`	使用 `redeem` 返回的 `order_query_token` 轮询兑换任务结果。
5	按 CDK 查询订单	POST	`/api/v1/sub/queryOrder`	根据 CDK 查询当前状态、产品信息和最近一笔订单，用于手动查询或售后查询。

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 和 order_query_token，最终成功或失败需要调用 redeemResult 轮询查询。

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 成功后，前端保存 order_query_token，并调用 redeemResult 轮询订单状态；如果订单仍是 processing，页面继续等待或提示用户稍后再查。

用户后续手动查询订单时，前端调用 queryOrder 按 CDK 查询最近一笔订单。

4. CDK 状态说明

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

5. 订单状态说明

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

6. 轮询订单说明

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

项目	建议	说明
轮询接口	`POST /api/v1/sub/redeemResult`	使用 `order_query_token` 查询兑换任务结果。
触发时机	`redeem` 返回 `code=200` 后开始	使用 `redeem` 响应里的 `order_query_token`。
继续条件	`order.status=processing`	订单仍在执行，继续等待。
停止条件	`order.status=success` 或 `order.status=failed`	成功或失败都属于最终状态，应停止轮询。
凭证缺失或过期	`code=0`	提示用户通过 CDK 手动查询，或重新提交兑换流程。
失败处理	`code=0` 或 `order.error` 非空	展示 `error`，必要时允许用户稍后重新查询。

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

7. 接口详情

7.1 校验并锁定 CDK

方法：POST

路径：/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

说明：校验 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

说明：提交订阅兑换任务。后端会再次校验登录态、账号套餐、CDK 锁定关系，然后创建订单并异步执行订阅。成功响应会返回 order_query_token，用于 redeemResult 轮询兑换结果。

请求参数

字段	类型	必填	说明	示例
`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	订单号。提交成功后返回。
`order_query_token`	string	订单查询凭证。`redeemResult` 轮询时必须原样提交，有效期 30 分钟。
`status`	string	订单当前状态。新提交任务通常为 `processing`。

成功示例

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

失败示例

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

7.4 轮询兑换结果

方法：POST

路径：/api/v1/sub/redeemResult

说明：使用 redeem 返回的 order_query_token 查询兑换任务结果。该接口用于兑换提交后的轮询，不需要再次提交 CDK 或 ChatGPT 登录态。

请求参数

字段	类型	必填	说明	示例
`order_query_token`	string	是	`redeem` 返回的订单查询凭证，有效期 30 分钟。	`eyJvcmRlcl9ubyI6IlNPMjAyNjA2MjIwMDAxIiwiZXhwIjoxNzg...signature`

响应字段

字段	类型	说明
`code`	integer	业务状态码。`200` 表示查询成功，`0` 表示查询失败。
`error`	string	失败原因；成功时为空字符串。
`product_name`	string	订单关联的产品展示名称。
`plan`	string	订单关联的订阅计划标识。
`order`	object	订单信息。凭证有效且订单存在时返回对象。

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": "",
  "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": 0,
  "error": "订单查询凭证无效或已过期"
}

7.5 按 CDK 查询订单

方法：POST

路径：/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": "activated",
  "product_name": "ChatGPT Plus",
  "plan": "chatgptplusplan",
  "order": {
    "order_no": "SO202606220001",
    "account": "user@example.com",
    "status": "success",
    "plan": "chatgptplusplan",
    "product_name": "ChatGPT Plus",
    "country": "PH",
    "currency": "PHP",
    "amount_minor": 98214,
    "error": "",
    "started_at": "2026-06-22T12:05:00Z",
    "finished_at": "2026-06-22T12:06:00Z",
    "duration_ms": 60000,
    "payment_card": ""
  }
}

暂无订单示例

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

查询失败示例

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

1. 接口范围#

2. 公共约定#

3. 前端调用流程#

4. CDK 状态说明#

5. 订单状态说明#

6. 轮询订单说明#

7. 接口详情#

7.1 校验并锁定 CDK#

请求参数#

响应字段#

成功示例#

失败示例#

7.2 预检 ChatGPT 账号#

请求参数#

响应字段#

成功示例#

失败示例#

7.3 提交订阅兑换任务#

请求参数#

响应字段#

成功示例#

失败示例#

7.4 轮询兑换结果#

请求参数#

响应字段#

order 字段#

处理中示例#

查询失败示例#

7.5 按 CDK 查询订单#

请求参数#

响应字段#

order 字段#

有订单示例#

暂无订单示例#

查询失败示例#

1. 接口范围

2. 公共约定

3. 前端调用流程

4. CDK 状态说明

5. 订单状态说明

6. 轮询订单说明

7. 接口详情

7.1 校验并锁定 CDK

请求参数

响应字段

成功示例

失败示例

7.2 预检 ChatGPT 账号

请求参数

响应字段

成功示例

失败示例

7.3 提交订阅兑换任务

请求参数

响应字段

成功示例

失败示例

7.4 轮询兑换结果

请求参数

响应字段

order 字段

处理中示例

查询失败示例

7.5 按 CDK 查询订单

请求参数

响应字段

order 字段

有订单示例

暂无订单示例

查询失败示例