# 接入概览
## 让退款申请，成为可追踪的任务
确认每账号的服务费，提交一个或多个账号，再按任务状态查询与处理。
1. [读取服务费](https://y.junlistudio.com/docs.md?page=chatgpt-refund-catalog#catalog)：获取费用与配置版本
2. [提交退款申请](https://y.junlistudio.com/docs.md?page=chatgpt-refund-submit#submit)：单个账号或批量提交
3. [查询任务进度](https://y.junlistudio.com/docs.md?page=chatgpt-refund-tasks#tasks)：详情、刷新与历史
4. [处理待办](https://y.junlistudio.com/docs.md?page=chatgpt-refund-actions#actions)：验证码与取消任务
[从读取服务费开始](https://y.junlistudio.com/docs.md?page=chatgpt-refund-catalog#catalog)7 个接口 · 与网页使用同一账户和任务记录
### 接口地址
`https://y.junlistudio.com/v1/apps/chatgpt-refund`
### 鉴权方式
`Authorization: Bearer YOUR_API_KEY`
使用本站 API Key。服务费目录公开读取，其他接口必须鉴权；登录 Cookie 不能代替密钥。
### 交给 Agent 阅读
先读取 [文档索引](/llms.txt)，再读取本模块的 [完整 Markdown](/docs.md?module=chatgpt-refund)，按目录 → 提交 → 查询 → 待办的顺序接入。
### 服务费与订阅退款
**平台服务费 本站积分** 按账号预留，任务成功后确认消费；失败、成功取消或未受理时退回对应服务费。
**订阅退款 以实际账单为准** 服务商任务完成不等于退款到账。退款资格、金额与到账时间需要查看订阅平台和银行卡账单。
# 服务费目录
## 读取服务费
获取费用与配置版本
### 服务费目录
GET `/v1/apps/chatgpt-refund/catalog` 公开接口
读取当前服务是否开放、单账号积分服务费、配置版本与批量上限。
#### 请求参数
无需请求参数，也不需要 API Key。
### 响应字段说明
**enabled / reason** · boolean / string
是否允许提交；未开放时 reason 返回原因。实际可用性以提交时的响应为准。
**fee** · decimal string | null
单账号平台服务费，单位为积分。null 表示尚未配置，不能当作免费。
**version** · integer
服务费配置版本，提交时原样传入，防止价格变更后静默扣费。
**max\_accounts** · integer
单批最多 200 个账号；同一本站账户最多同时处理 200 个未结算账号。
公开读取，无需 API Key。展示 fee × 去重后的账号数，让用户确认服务费再提交。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl 'https://y.junlistudio.com/v1/apps/chatgpt-refund/catalog'
```
### 响应 JSON
```json
{
"enabled": true,
"reason": "",
"fee": "7.12345678",
"version": 2,
"max_accounts": 200
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
# 创建退款批次
## 提交退款申请
单个账号或批量提交
### 创建退款批次
POST `/v1/apps/chatgpt-refund/batches` API Key
同一个接口支持单账号与批量退款申请，每个受理账号对应一个独立任务。
#### 请求字段
**Idempotency-Key** · header · string · 必填
必填。8–80 位字母、数字、下划线或短横线；一次逻辑提交使用一个唯一标识，重试保留原标识。
**version** · integer · 必填
用户确认服务费时读取的 catalog.version。版本已变更返回 409，重新读取并确认。
**consent** · boolean · 必填
用户已确认账号归属并授权本次退款处理时传 true。
**accounts** · array · 必填
1–200 项。每项包含 type 与 value，可混用支持的账号类型。单次 JSON 请求上限 16 MiB，单账号 value 上限 1 MiB。
**accounts\[\].type** · string · 必填
session、access\_token、microsoft 或 icloud。
**accounts\[\].value** · object | string · 必填
Session 推荐传完整 JSON 对象；其他类型传字符串。格式说明见下方。
### 四种账号输入格式
**session · 完整 Session JSON 对象**
用户登录 ChatGPT 后打开下方会话接口，复制全部返回内容，至少包含 user.email 与 accessToken。也兼容 JSON 字符串。
**access\_token · 字符串**
完整 Access Token，长度 10–65536 字节，不能包含空白字符。
**microsoft · 字符串**
邮箱----密码----client\_id----refresh\_token，四段均不能为空。
**icloud · 字符串**
邮箱----HTTPS 接码地址，地址不能包含用户名或密码段。
[获取完整 ChatGPT Session](https://chatgpt.com/api/auth/session)
### 响应字段说明
**batch** · object
id：批次编号；count：本地去重后的账号数；accepted：已受理数量，结果未确认时为 null；created\_at：创建时间。
**tasks** · array
本批次任务，字段与任务详情一致。HTTP 200 不代表退款成功，必须继续查询 status 和 settled。
相同本站账户、相同幂等标识、相同账号身份集合和版本返回原批次，不重复预留积分。改变身份集合或版本返回 409；重试仍应保留原请求。提交超时后先查任务历史，不要换标识重新提交。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl -X POST 'https://y.junlistudio.com/v1/apps/chatgpt-refund/batches' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: refund_UNIQUE_REQUEST_ID' \
--data-binary @refund.json
```
### 请求 JSON
```json
{
"version": 2,
"consent": true,
"accounts": [
{
"type": "session",
"value": {
"user": {
"email": "alice@example.com"
},
"accessToken": "REPLACE_WITH_COMPLETE_SESSION",
"expires": "REPLACE_WITH_ACTUAL_EXPIRY"
}
}
]
}
```
### 响应 JSON
```json
{
"batch": {
"id": "BATCH_ID",
"count": 1,
"accepted": 1,
"created_at": "2026-10-12T08:00:00Z"
},
"tasks": [
{
"id": "TASK_ID",
"batch_id": "BATCH_ID",
"key_id": "KEY_ID",
"account": "al***@example.com",
"fee": "7.12345678",
"status": "queued",
"progress": 0,
"requires_otp": false,
"failure_code": "",
"settled": false,
"created_at": "2026-10-12T08:00:00Z",
"updated_at": "2026-10-12T08:01:00Z"
}
]
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
将请求 JSON 保存为仅自己可读的 refund.json。Session 示例须替换成完整返回内容。请从自己的服务端提交，避免凭据和验证码进入日志。
# 查询与刷新任务
## 查询任务进度
详情、刷新与历史
### 任务详情
GET `/v1/apps/chatgpt-refund/tasks/{id}` API Key
读取本站已记录的任务状态和费用结算结果。需要最新进度时调用刷新接口。
#### 请求参数
**id** · path · string · 必填
提交批次返回的本站任务编号 tasks\[\].id。
### 响应字段说明
**id / batch\_id** · string
本站任务编号与批次编号。后续查询使用 id。
**key\_id** · string
创建任务时使用的本站 API Key 编号；网页创建的任务为空。
**account** · string
脱敏邮箱；尚未确认时为“正在确认账号”。任务顺序不保证与输入账号顺序相同，不要按数组位置匹配账号。
**fee** · decimal string
单个任务的平台服务费，单位为本站积分，最多八位小数。不是订阅退款金额。
**status** · string
submitting、queued、processing、awaiting\_otp、unknown、succeeded、failed、cancelled 或 skipped。
**progress / requires\_otp** · integer / boolean
进度 0–100；requires\_otp=true 或 status=awaiting\_otp 时可提交邮箱验证码。
**settled** · boolean
是否完成平台服务费结算。成功确认消费；失败、取消或未受理退回预留积分。
**failure\_code** · string
安全的错误分类，正常时为空；例如 UPSTREAM\_UNCERTAIN、PROCESSING\_FAILED、MANUAL\_RECONCILIATION。
**created\_at / updated\_at** · date-time
ISO 8601 格式的创建和最近更新时间。
只能访问当前本站账户的任务，包含网页与 API 创建的任务。不存在或属于其他账户的任务统一返回 404。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl 'https://y.junlistudio.com/v1/apps/chatgpt-refund/tasks/TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
### 响应 JSON
```json
{
"id": "TASK_ID",
"batch_id": "BATCH_ID",
"key_id": "KEY_ID",
"account": "al***@example.com",
"fee": "7.12345678",
"status": "processing",
"progress": 65,
"requires_otp": false,
"failure_code": "",
"settled": false,
"created_at": "2026-10-12T08:00:00Z",
"updated_at": "2026-10-12T08:01:00Z"
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
### 刷新任务
POST `/v1/apps/chatgpt-refund/tasks/{id}/refresh` API Key
查询任务的最新状态，结果明确后自动结算对应的平台服务费。无需请求体。
#### 请求字段
**id** · path · string · 必填
提交批次返回的本站任务编号 tasks\[\].id。
### 响应字段说明
**id / batch\_id** · string
本站任务编号与批次编号。后续查询使用 id。
**key\_id** · string
创建任务时使用的本站 API Key 编号；网页创建的任务为空。
**account** · string
脱敏邮箱；尚未确认时为“正在确认账号”。任务顺序不保证与输入账号顺序相同，不要按数组位置匹配账号。
**fee** · decimal string
单个任务的平台服务费，单位为本站积分，最多八位小数。不是订阅退款金额。
**status** · string
submitting、queued、processing、awaiting\_otp、unknown、succeeded、failed、cancelled 或 skipped。
**progress / requires\_otp** · integer / boolean
进度 0–100；requires\_otp=true 或 status=awaiting\_otp 时可提交邮箱验证码。
**settled** · boolean
是否完成平台服务费结算。成功确认消费；失败、取消或未受理退回预留积分。
**failure\_code** · string
安全的错误分类，正常时为空；例如 UPSTREAM\_UNCERTAIN、PROCESSING\_FAILED、MANUAL\_RECONCILIATION。
**created\_at / updated\_at** · date-time
ISO 8601 格式的创建和最近更新时间。
建议至少间隔 5 秒；服务端会合并短时间的查询。settled=true 后停止轮询；unknown 请联系管理员核实，不要重复创建批次。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl -X POST 'https://y.junlistudio.com/v1/apps/chatgpt-refund/tasks/TASK_ID/refresh' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
### 响应 JSON
```json
{
"id": "TASK_ID",
"batch_id": "BATCH_ID",
"key_id": "KEY_ID",
"account": "al***@example.com",
"fee": "7.12345678",
"status": "processing",
"progress": 65,
"requires_otp": false,
"failure_code": "",
"settled": false,
"created_at": "2026-10-12T08:00:00Z",
"updated_at": "2026-10-12T08:01:00Z"
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
### 任务历史
GET `/v1/apps/chatgpt-refund/tasks` API Key
按创建时间倒序分页读取当前账户的任务，可按状态筛选。
#### 请求参数
**page** · integer · 可选
默认 1，范围 1–100000，每页 20 条。
**status** · string · 可选
可选任务状态见任务详情 status；省略返回全部状态。
### 响应字段说明
**items / total / page** · array / integer / integer
当前页任务、总条数与当前页码。items 每项与任务详情一致。
根据 batch\_id 关联同批次任务；完整账号凭据、内部处理信息不会返回。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl 'https://y.junlistudio.com/v1/apps/chatgpt-refund/tasks?page=1&status=processing' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
### 响应 JSON
```json
{
"items": [
{
"id": "TASK_ID",
"batch_id": "BATCH_ID",
"key_id": "KEY_ID",
"account": "al***@example.com",
"fee": "7.12345678",
"status": "processing",
"progress": 65,
"requires_otp": false,
"failure_code": "",
"settled": false,
"created_at": "2026-10-12T08:00:00Z",
"updated_at": "2026-10-12T08:01:00Z"
}
],
"total": 1,
"page": 1
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
# 验证码与取消
## 处理待办
验证码与取消任务
### 提交邮箱验证码
POST `/v1/apps/chatgpt-refund/tasks/{id}/otp` API Key
任务要求验证码时，提交该账号邮箱收到的六位数字验证码。
#### 请求字段
**id** · path · string · 必填
提交批次返回的本站任务编号 tasks\[\].id。
**code** · string · 必填
六位数字字符串，保留可能的前导零。
### 响应字段说明
**accepted / message** · boolean / string
accepted=true 表示验证码进入验证队列，随后仍需刷新任务查看结果。
仅 awaiting\_otp 或 requires\_otp=true 的未结算任务可提交。任务正在更新时返回 409；收到不确定响应后先刷新任务。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl -X POST 'https://y.junlistudio.com/v1/apps/chatgpt-refund/tasks/TASK_ID/otp' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-binary @otp.json
```
### 请求 JSON
```json
{
"code": "012345"
}
```
### 响应 JSON
```json
{
"accepted": true,
"message": "验证码已进入验证队列，请等待任务结果"
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
将请求 JSON 保存为仅自己可读的 otp.json。请从自己的服务端提交，避免凭据和验证码进入日志。
### 取消排队任务
POST `/v1/apps/chatgpt-refund/tasks/{id}/cancel` API Key
尝试取消尚未开始的 queued 任务。无需请求体，按单任务取消。
#### 请求字段
**id** · path · string · 必填
提交批次返回的本站任务编号 tasks\[\].id。
### 响应字段说明
**id / batch\_id** · string
本站任务编号与批次编号。后续查询使用 id。
**key\_id** · string
创建任务时使用的本站 API Key 编号；网页创建的任务为空。
**account** · string
脱敏邮箱；尚未确认时为“正在确认账号”。任务顺序不保证与输入账号顺序相同，不要按数组位置匹配账号。
**fee** · decimal string
单个任务的平台服务费，单位为本站积分，最多八位小数。不是订阅退款金额。
**status** · string
submitting、queued、processing、awaiting\_otp、unknown、succeeded、failed、cancelled 或 skipped。
**progress / requires\_otp** · integer / boolean
进度 0–100；requires\_otp=true 或 status=awaiting\_otp 时可提交邮箱验证码。
**settled** · boolean
是否完成平台服务费结算。成功确认消费；失败、取消或未受理退回预留积分。
**failure\_code** · string
安全的错误分类，正常时为空；例如 UPSTREAM\_UNCERTAIN、PROCESSING\_FAILED、MANUAL\_RECONCILIATION。
**created\_at / updated\_at** · date-time
ISO 8601 格式的创建和最近更新时间。
以返回的 status 和 settled 为准，成功取消后退回平台服务费。任务已开始或暂未确认取消时返回 409，先刷新状态。已结算的任务返回现有结果。
调用示例请求与响应分开查看
### cURL 请求
```bash
curl -X POST 'https://y.junlistudio.com/v1/apps/chatgpt-refund/tasks/TASK_ID/cancel' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
### 响应 JSON
```json
{
"id": "TASK_ID",
"batch_id": "BATCH_ID",
"key_id": "KEY_ID",
"account": "al***@example.com",
"fee": "7.12345678",
"status": "cancelled",
"progress": 100,
"requires_otp": false,
"failure_code": "",
"settled": true,
"created_at": "2026-10-12T08:00:00Z",
"updated_at": "2026-10-12T08:01:00Z"
}
```
将占位值替换为你的数据 · 示例不发起真实请求
金额、时间与版本均为结构示例，以真实接口返回为准。
# 状态、费用与重试
## 接口说明
HTTP 200 表示本次请求已处理。先看 status，再看 settled，决定下一步。
状态 | 含义 | 下一步 |
| --- | --- | --- |
`submitting` | 正在提交 | 等待受理，服务费已预留。 |
`queued` | 等待处理 | 可尝试取消，取消结果以服务端为准。 |
`processing` | 正在处理 | 继续刷新状态。 |
`awaiting_otp` | 等待验证码 | 填写邮箱验证码，再查询结果。 |
`unknown` | 等待核实 | 受理结果不明，积分继续预留，联系管理员。 |
`succeeded` | 任务成功 | 确认平台服务费消费；订阅退款到账另查账单。 |
`failed` | 任务失败 | 退回该任务预留的服务费。 |
`cancelled` | 任务已取消 | 退回该任务预留的服务费。 |
`skipped` | 未受理 | 合并或未受理的任务，释放多预留的服务费。 |
### 常见错误
业务错误返回 `{"detail":"可读错误说明"}`，网关鉴权错误还可能包含 error 对象。
HTTP 状态 | 含义 | 建议处理 |
| --- | --- | --- |
`400` | 请求格式、账号或验证码无效 | 修正参数；检查账号数、体积与幂等请求头。 |
`401` | API Key 不可用 | 使用有效的本站 API Key；Cookie 不能代替密钥。 |
`402` | 积分或额度不足 | 检查账户积分、团队成员额度和 API Key 剩余额度。 |
`403` | 账户或团队不可用 | 联系管理员确认账户状态。 |
`404` | 任务不存在或无权访问 | 确认本站任务编号与账户归属。 |
`409` | 版本、重复账号或当前状态冲突 | 先查看任务；费用版本变更时重新获取目录并确认。 |
`500 / 502 / 503` | 处理异常或服务暂时不可用 | 创建结果可能不确定，先查历史；保留原请求及幂等标识。 |
### 积分与 API Key 额度
每个任务的服务费同时预留账户积分与 API Key 累计额度；批次额度不足时整批不提交。任务成功才计入 Key 已用额度，失败、取消或 skipped 时释放预留。撤销 Key 不影响已有任务结算。积分流水记录 Key 信息，可按 Key 筛选，保留 30 天。
团队成员沿用团队钱包与成员额度。目录、查询、刷新、验证码和取消接口不另收平台服务费。本应用不参与代理分佣；模型单价保护不用于应用服务费。
### 去重、幂等与不确定结果
本地按可识别的账号身份合并重复输入，受理时也可能继续去重，未受理的任务标为 skipped 并释放费用。同一本站账户内有未结算任务的已知账号不能再次提交。不保证不同格式的所有凭据都能识别为同一账号。
提交前保存 Idempotency-Key。超时或 unknown 后先查询历史，保留原请求及原幂等标识；不要用新标识盲目重试。unknown 持续预留服务费，需要管理员核实后处理。
### 账号凭据与验证码
完整 Session、Access Token、邮箱凭据和验证码不写入本站任务记录或日志，只用于本次处理。任务返回脱敏邮箱；不要按返回数组位置推断账号对应关系。从服务端调用，避免把本站 API Key 暴露在客户端。