API指南

1. 接口范围

本文档说明 AutoSub 兑换页和账单查询页使用的 6 个公开接口，接口统一位于 /api/v1/sub 前缀下。

基础域名：

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

顺序	接口	方法	路径	作用
1	校验并锁定 CDK	POST	`/api/v1/sub/verifyCdk`	校验 CDK 是否可用，并生成短期有效的 `activation_token`；Credits 商品同时返回商品类型和充值数量。
2	预检 ChatGPT/Claude 账号	POST	`/api/v1/sub/precheckAccount`	校验账号登录态及商品兑换资格；Credits 商品会校验个人付费订阅和购买资格。
3	提交兑换任务	POST	`/api/v1/sub/redeem`	使用 CDK、`activation_token` 和登录态提交订阅或 Codex Credits 异步兑换任务。
4	轮询兑换结果	POST	`/api/v1/sub/redeemResult`	使用 `redeem` 返回的 `order_query_token` 轮询兑换任务结果。
5	按 CDK 查询订单	POST	`/api/v1/sub/queryOrder`	根据一个或多个 CDK 查询最近一笔兑换订单，用于手动查询或售后查询；空结果不代表 CDK 一定存在。
6	查询 ChatGPT 账单	POST	`/api/v1/sub/queryBilling`	根据 ChatGPT 登录态查询账号资料、订阅、支付方式、账单客户信息和最近账单列表。

2. 公共约定

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

HTTP 状态码：正常业务响应均返回 HTTP 200；限流返回 HTTP 429；安全校验暂不可用返回 HTTP 503。

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

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

商品类型：Codex Credits 商品在相关响应中返回 product_type=codex_credits 和大于 0 的 credit_quantity；普通订阅商品省略这两个字段，调用方可按订阅商品处理。

Credits 账号资格：Codex Credits 仅支持 OpenAI 个人付费账号。账号需存在有效订阅，套餐类型为 Plus、Go、Pro 5x 或 Pro 20x，并且 credit_purchase_eligible=true。

Credits 重复提交：同一账号已有 Credits 订单处于 processing 时，redeem 返回业务失败；调用方应等待原订单结束后再提交。

Credits 支付金额：Credits 成功订单中的 amount_minor 和 currency 表示支付确认后的实际支付金额与币种。

兑换流程请求标识：verifyCdk 支持可选的 request_nonce。建议每次新兑换流程生成一个随机 Base64URL 字符串，并在该流程的页面刷新、网络重试和重复提交期间复用；解码后长度必须为 16～64 字节。相同 CDK 与相同 request_nonce 在锁定有效期内会恢复原锁定和原 activation_token，不会延长原过期时间。

兑换登录态 token：precheckAccount 和 redeem 使用的 token 是调用方把订阅账号登录态通过 zstd 压缩并 base64 编码后的字符串，格式为 zstd64:<base64>。

ChatGPT Token 自动刷新：precheckAccount 检测到 Access Token 过期时，会尝试使用完整 Session JSON 中的 sessionToken 自动刷新。刷新并预检成功时响应包含 refreshed_token，调用方必须用它替换原 token 后再调用 redeem。仅提交原始 access token、缺少 sessionToken、Claude 场景或未触发刷新时不返回该字段。

预检响应缓存：precheckAccount 返回 Cache-Control: no-store 和 Pragma: no-cache，调用方也不应记录或长期保存 token、refreshed_token。

ChatGPT 账单查询 token：queryBilling 使用的 token 也是 zstd64:<base64>；压缩前内容可为完整 ChatGPT session JSON、原始 access token，或 Bearer <access token>。

账单查询请求大小：queryBilling 请求体最大 3MB。超出限制或 JSON 解析失败时，按业务失败处理，错误信息以响应体 error 为准。

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

兑换维护提示：当兑换服务维护中时，verifyCdk、precheckAccount、redeem 可能返回 code=0，error=当前兑换服务正在维护中，请稍后再试。如有疑问，请联系管理员。。

公开限流：verifyCdk、queryOrder 和 queryBilling 会按访问频率进行保护。触发限流时返回 HTTP 429，响应头包含 Retry-After，调用方应等待指定秒数后再重试。

安全校验暂不可用：当安全校验暂时不可用时，相关接口返回 HTTP 503，调用方应稍后重试。

批量查询建议：queryOrder 推荐使用 cdks 数组批量查询，单次最多 50 个有效 CDK；cdk 单个查询字段仅为兼容旧调用保留，后续会取消。

2.1 限流和安全校验响应

以下响应可能出现在启用公开限流或安全校验的接口，发生时业务逻辑不会继续处理。

请求过于频繁

HTTP 状态码：429

响应头：

Header	说明	示例
`Retry-After`	建议等待多少秒后再重试。	`42`

响应体：

{
  "code": 0,
  "error": "请求过于频繁，请在 42 秒后重试"
}

安全校验暂不可用

HTTP 状态码：503

{
  "code": 0,
  "error": "请求安全校验暂不可用，请稍后重试"
}

3. 前台调用流程

每次开始新的兑换流程时，调用方生成一个随机 request_nonce；同一流程内必须持续复用该值。

用户输入 CDK，调用方携带 CDK、期望服务商和 request_nonce 调用 verifyCdk。

verifyCdk 成功后，调用方保存 activation_token、expires_in、expires_at、resumed、provider、product_name 和 plan。如果响应包含 product_type=codex_credits，还需保存 credit_quantity 并按 Credits 兑换流程展示。

用户提供订阅账号登录态后，调用方将登录态压缩成 zstd64 token。

调用方调用 precheckAccount 校验账号。只有 eligible=true 时允许继续；Credits 商品还应检查 credit_purchase_eligible=true。如果响应包含 refreshed_token，立即用它替换当前 token。

调用方使用预检后的有效 token 调用 redeem 提交订阅或 Credits 兑换任务；收到过 refreshed_token 时必须提交刷新后的值。

redeem 成功后，调用方保存 order_query_token，并调用 redeemResult 轮询订单状态；如果订单仍是 processing，页面继续等待或提示用户稍后再查。

用户后续手动查询订单时，调用方调用 queryOrder，推荐使用 cdks 数组查询一个或多个 CDK 的最近订单。

ChatGPT 账单查询是独立流程，调用方可直接使用 queryBilling 查询账号账单信息，不需要先调用 CDK 兑换相关接口。

4. CDK 状态说明

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

5. 订单状态说明

状态	中文含义	前台映射	备注
`processing`	处理中	`PROCESSING`	任务还在执行，轮询时需要继续查询；如果 `retrying=true`，表示系统正在自动重试。
`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.retrying=true` 时可展示“正在自动重试”。
停止条件	`order.status=success` 或 `order.status=failed`	成功或最终失败都属于最终状态，应停止轮询。
凭证缺失或过期	`code=0`	提示用户通过 CDK 手动查询，或重新提交兑换流程。
失败处理	`code=0` 或最终 `order.status=failed`	展示 `error`；如果订单仍为 `processing`，即使有自动重试提示也应继续轮询。

推荐调用方在轮询超过 3 分钟仍为 processing 时，提示用户订单仍在处理中，可稍后通过订单查询页面使用 CDK 继续查询。自动重试次数和状态以订单对象里的 attempt_current、attempt_max、retrying 为准。

1. 接口范围#

2. 公共约定#

2.1 限流和安全校验响应#

请求过于频繁#

安全校验暂不可用#

3. 前台调用流程#

4. CDK 状态说明#

5. 订单状态说明#

6. 轮询订单说明#