v1.1.2 更新说明

更新日期：2026-07-18

一句话概览

v1.1.2 新增 ChatGPT 账单查询能力，公开接口从 5 个增加到 6 个；同时补充兑换服务维护中、账单查询限流、账单查询请求大小和错误归因说明。

变化级别

级别	结论	说明
新增接口	是	新增 `POST /api/v1/sub/queryBilling`。
兑换接口路径	不变	`verifyCdk`、`precheckAccount`、`redeem`、`redeemResult`、`queryOrder` 路径不变。
账单查询请求字段	新增	`queryBilling` 请求体新增必填字段 `token`。
账单查询响应字段	新增	返回账号资料、订阅、支付方式、账单客户、账单列表、是否还有更多账单和补充提示。
兑换维护提示	明确	兑换服务维护中时，部分兑换链路接口会返回统一维护提示。
限流说明	扩展	`queryBilling` 也会进行公开限流，触发后返回 HTTP `429`。

新增接口

6-查询 ChatGPT 账单

路径：POST /api/v1/sub/queryBilling

用途：根据 ChatGPT 登录态查询账号账单信息，包括账号资料、当前订阅、支付方式、账单客户信息和最近账单列表。该接口是独立账单查询流程，不依赖 CDK 兑换流程。

请求参数

{
  "token": "zstd64:KLUv/QBY..."
}

字段	类型	必填	说明
`token`	string	是	调用方压缩后的 ChatGPT 登录态，格式为 `zstd64:<base64>`。压缩前内容可为完整 ChatGPT session JSON、原始 access token，或 `Bearer <access token>`。

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

成功响应

{
  "code": 200,
  "error": "",
  "profile": {
    "email": "user@example.com",
    "name": "YY",
    "plan_type": "plus"
  },
  "subscription": {
    "status": "active",
    "plan_name": "chatgptplusplan",
    "billing_period": "monthly",
    "amount_minor": 2000,
    "currency": "USD",
    "next_billing_at": "2026-08-05T12:00:00Z",
    "auto_renew": true
  },
  "payment_method": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2028
  },
  "customer": {
    "name": "YY",
    "email": "user@example.com",
    "address": {
      "line1": "30 N Gould St",
      "line2": "",
      "city": "Sheridan",
      "state": "WY",
      "postal_code": "82801",
      "country": "US"
    }
  },
  "invoices": [
    {
      "id": "in_xxx",
      "number": "INV-0001",
      "created_at": "2026-07-05T12:00:00Z",
      "period_start": "2026-07-05T12:00:00Z",
      "period_end": "2026-08-05T12:00:00Z",
      "amount_minor": 2000,
      "currency": "USD",
      "status": "paid",
      "description": "ChatGPT Plus",
      "invoice_pdf_url": "",
      "receipt_pdf_url": ""
    }
  ],
  "has_more": false,
  "notice": ""
}

响应字段说明

字段	类型	说明
`code`	integer	业务状态码。`200` 表示查询成功，`0` 表示业务失败。
`error`	string	失败原因。成功时为空字符串。
`profile.email`	string	账号邮箱。
`profile.name`	string	账号名称。
`profile.plan_type`	string	账号计划类型。
`subscription`	object/null	当前订阅信息；没有有效订阅或未查询到时可能为 `null`。
`subscription.status`	string	订阅状态，例如 `active`、`canceled`、`past_due`。
`subscription.plan_name`	string	订阅计划名称。
`subscription.billing_period`	string	订阅周期，例如 `monthly`。
`subscription.amount_minor`	integer	订阅金额，使用最小货币单位。
`subscription.currency`	string	订阅币种。
`subscription.next_billing_at`	string	下次扣费时间，ISO 8601 格式；无法确定时可能为空字符串。
`subscription.auto_renew`	boolean	是否自动续费。
`payment_method`	object/null	支付方式信息；没有绑定支付方式或未查询到时可能为 `null`。
`payment_method.brand`	string	支付卡品牌。
`payment_method.last4`	string	支付卡后四位。
`payment_method.exp_month`	integer	支付卡过期月份。
`payment_method.exp_year`	integer	支付卡过期年份。
`customer`	object/null	账单客户信息；没有客户资料或未查询到时可能为 `null`。
`customer.name`	string	账单客户名称。
`customer.email`	string	账单客户邮箱。
`customer.address`	object	账单地址信息。没有对应信息时字段值可能为空字符串。
`invoices`	array	最近账单列表。当前最多返回最近 4 条；没有账单时为空数组。
`invoices[].id`	string	账单记录 ID。
`invoices[].number`	string	账单编号。
`invoices[].created_at`	string	账单创建时间，ISO 8601 格式。
`invoices[].period_start`	string	账单周期开始时间，ISO 8601 格式。
`invoices[].period_end`	string	账单周期结束时间，ISO 8601 格式。
`invoices[].amount_minor`	integer	账单金额，使用最小货币单位。
`invoices[].currency`	string	账单币种。
`invoices[].status`	string	账单状态，例如 `paid`、`open`、`void`。
`invoices[].description`	string	账单说明。
`invoices[].invoice_pdf_url`	string	发票 PDF 地址。没有时为空字符串。
`invoices[].receipt_pdf_url`	string	收据 PDF 地址。没有时为空字符串。
`has_more`	boolean	是否还有更多账单记录未返回。
`notice`	string	补充提示。没有提示时为空字符串。

常见失败

场景	HTTP 状态码	响应示例	建议处理
登录态失效	`200`	`{ "code": 0, "error": "登录态已失效，请重新获取后查询", "invoices": [] }`	引导用户重新获取登录态后再查询。
ChatGPT 风控拦截	`200`	`{ "code": 0, "error": "账单查询被 ChatGPT 风控拦截，请稍后重试", "invoices": [] }`	提示用户稍后重试。
请求过于频繁	`429`	`{ "code": 0, "error": "请求过于频繁，请在 42 秒后重试" }`	读取 `Retry-After` 后等待再重试。
安全校验暂不可用	`503`	`{ "code": 0, "error": "请求安全校验暂不可用，请稍后重试" }`	稍后重试。

兑换链路补充

本版本补充兑换服务维护中的统一提示。以下接口可能返回该业务失败：

接口	HTTP 状态码	业务响应
`verifyCdk`	`200`	`{ "code": 0, "error": "当前兑换服务正在维护中，请稍后再试。如有疑问，请联系管理员。" }`
`precheckAccount`	`200`	`{ "code": 0, "error": "当前兑换服务正在维护中，请稍后再试。如有疑问，请联系管理员。" }`
`redeem`	`200`	`{ "code": 0, "error": "当前兑换服务正在维护中，请稍后再试。如有疑问，请联系管理员。" }`

调用方关注点

公开接口数量从 5 个增加到 6 个，新增的 queryBilling 不影响原兑换流程。

queryBilling 只用于 ChatGPT 账单查询，当前不用于 Claude 账单查询。

queryBilling 的 token 必须传压缩后的 zstd64:<base64> 字符串。

queryBilling 成功时 subscription、payment_method、customer 仍可能为 null，展示层需要做好空值处理。

invoices 没有记录时返回空数组，调用方应按空列表展示。

兑换服务维护中属于业务失败，调用方直接展示 error 即可。

v1.1.2 更新说明（2026-07-18）

v1.1.2 更新说明#

一句话概览#

变化级别#

新增接口#

6-查询 ChatGPT 账单#

请求参数#

成功响应#

响应字段说明#

常见失败#

兑换链路补充#

调用方关注点#