# 充值系统 API 文档

## 概述

- **Base URL**: `https://hhh.ow818.com`
- **Content-Type**: `application/json`
- **跨域来源**: `https://ow800.com`

---

## 通用响应结构

所有API返回统一的响应格式：

| 字段 | 类型 | 说明 |
|------|------|------|
| code | number | 状态码，200表示成功 |
| message | string \| null | 消息描述 |
| data | object \| null | 响应数据 |
| timestamp | number | 时间戳（毫秒） |
| error | boolean | 是否发生错误 |
| success | boolean | 请求是否成功 |

---

## 1. 校验卡密

验证卡密是否有效。

### 请求

```
POST /api/cards/verify
```

### 请求头

| Header | 值 |
|--------|-----|
| Content-Type | application/json |
| Accept | application/json |

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cardKey | string | 是 | 卡密密钥 |

### 响应

#### 成功响应 (卡密有效)

```json
{
    "code": 200,
    "message": null,
    "data": {
        "success": true,
        "message": "CARD_VERIFICATION_SUCCESS",
        "errorCode": null,
        "cardId": 536,
        "productId": 3,
        "productName": "ChatGPT",
        "productDescription": "自动充值GPT",
        "productPrice": 10.00,
        "verifyTime": "2025-11-26 14:56:55"
    },
    "timestamp": 1764140215106,
    "error": false,
    "success": true
}
```

#### 失败响应 (卡密不存在)

```json
{
    "code": 200,
    "message": null,
    "data": {
        "success": false,
        "message": "CARD_NOT_FOUND",
        "errorCode": 3000,
        "cardId": null,
        "productId": null,
        "productName": null,
        "productDescription": null,
        "productPrice": null,
        "verifyTime": "2025-11-26 14:59:56"
    },
    "timestamp": 1764140396409,
    "error": false,
    "success": true
}
```

### data 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| success | boolean | 验证是否成功 |
| message | string | 验证结果消息 |
| errorCode | number \| null | 错误码（失败时返回） |
| cardId | number \| null | 卡密ID |
| productId | number \| null | 产品ID |
| productName | string \| null | 产品名称 |
| productDescription | string \| null | 产品描述 |
| productPrice | number \| null | 产品价格 |
| verifyTime | string | 验证时间 |

### 错误码

| 错误码 | 消息 | 说明 |
|--------|------|------|
| 3000 | CARD_NOT_FOUND | 卡密不存在 |

---

## 2. 查询仪表盘状态

获取各充值渠道和库存的可用性状态。

### 请求

```
GET /api/dashboard/stats?availabilityOnly=true
```

### 请求头

| Header | 值 |
|--------|-----|
| Accept | application/json |
| Origin | https://ow800.com |
| Referer | https://ow800.com/ |

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| availabilityOnly | boolean | 否 | 仅返回可用性信息 |

### 响应

```json
{
    "code": 200,
    "message": null,
    "data": {
        "channelOneAvailable": false,
        "channelTwoAvailable": true,
        "gptInventoryAvailable": false,
        "bankCardAvailable": true,
        "channelThreeAvailable": false,
        "googleInventoryAvailable": false
    },
    "timestamp": 1764140430161,
    "error": false,
    "success": true
}
```

### data 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| channelOneAvailable | boolean | 渠道一是否可用 |
| channelTwoAvailable | boolean | 渠道二是否可用 |
| channelThreeAvailable | boolean | 渠道三是否可用 |
| gptInventoryAvailable | boolean | GPT库存是否可用 |
| googleInventoryAvailable | boolean | Google库存是否可用 |
| bankCardAvailable | boolean | 银行卡支付是否可用 |

---

## 3. 提交充值任务

提交充值请求，创建充值任务。

### 请求

```
POST /api/recharge/perform
```

### 请求头

| Header | 值 |
|--------|-----|
| Content-Type | application/json |
| Accept | application/json |
| Origin | https://ow800.com |
| Referer | https://ow800.com/ |

### 请求体

```json
{
    "cardInfo": "SPZOQEZH65IPY2M4",
    "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
    "fullToken": "{\"user\":{\"id\":\"user-xxx\",...}",
    "userEmail": "example@qq.com",
    "confirmed": true,
    "account": {
        "id": "6bb82f4c-5c12-40dc-99b9-e0d2b20e0e4a"
    }
}
```

### 请求参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cardInfo | string | 是 | 卡密信息 |
| accessToken | string | 是 | OpenAI访问令牌（JWT格式） |
| fullToken | string | 是 | 完整令牌信息（JSON字符串） |
| userEmail | string | 是 | 用户邮箱 |
| confirmed | boolean | 是 | 是否已确认 |
| account | object | 是 | 账户信息 |
| account.id | string | 是 | 账户ID |

### fullToken 结构说明

`fullToken` 是一个JSON字符串，包含以下结构：

```json
{
    "user": {
        "id": "user-xxx",
        "email": "example@qq.com",
        "idp": "auth0",
        "iat": 1759998592,
        "mfa": true
    },
    "expires": "2026-02-24T01:07:13.367Z",
    "account": {
        "id": "6bb82f4c-5c12-40dc-99b9-e0d2b20e0e4a",
        "planType": "free",
        "structure": "personal",
        "workspaceType": null,
        "organizationId": null,
        "isDelinquent": true,
        "gracePeriodId": null
    },
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "authProvider": "openai",
    "rumViewTags": {
        "light_account": {
            "fetched": false
        }
    }
}
```

### 响应

#### 成功响应

```json
{
    "code": 200,
    "message": null,
    "data": {
        "usageId": 2814,
        "success": true,
        "processing": true,
        "rechargeUrl": "https://pay.openai.com/c/pay/cs_live_xxx...",
        "message": "任务已创建，等待充值结果",
        "rechargeType": 1,
        "bankCardId": 2025
    },
    "timestamp": 1764141428873,
    "error": false,
    "success": true
}
```

#### 失败响应

```json
{
    "code": 4000,
    "message": "充值失败，请重新提交token",
    "data": null,
    "timestamp": 1764140594006,
    "error": true,
    "success": false
}
```

### 成功响应 data 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| usageId | number | 使用记录ID，用于后续查询状态 |
| success | boolean | 任务创建是否成功 |
| processing | boolean | 是否正在处理中 |
| rechargeUrl | string | OpenAI支付链接 |
| message | string | 状态消息 |
| rechargeType | number | 充值类型 |
| bankCardId | number | 银行卡ID |

### 错误码

| 错误码 | 消息 | 说明 |
|--------|------|------|
| 4000 | 充值失败，请重新提交token | Token无效或已过期 |

---

## 4. 查询任务状态

根据 usageId 查询充值任务的当前状态。

### 请求

```
GET /api/recharge/status?usageId={usageId}
```

### 请求头

| Header | 值 |
|--------|-----|
| Accept | application/json |
| Origin | https://ow800.com |
| Referer | https://ow800.com/ |

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| usageId | number | 是 | 使用记录ID（从提交任务接口获取） |

### 响应

#### 进行中状态

```json
{
    "code": 200,
    "message": null,
    "data": {
        "usageId": 2814,
        "status": 0,
        "cardKey": "SPZOQEZH65IPY2M4",
        "rechargeUrl": "https://pay.openai.com/c/pay/cs_live_xxx...",
        "userEmail": "example@gmail.com",
        "updatedAt": "2025-11-26 15:17:10",
        "errorMessage": null,
        "fullToken": "{...}",
        "account": {
            "id": "094a43f5-9cad-43e7-80f3-76d354b4bce5"
        }
    },
    "timestamp": 1764141430164,
    "error": false,
    "success": true
}
```

#### 成功状态

```json
{
    "code": 200,
    "message": null,
    "data": {
        "usageId": 2814,
        "status": 2,
        "cardKey": "SPZOQEZH65IPY2M4",
        "rechargeUrl": "https://pay.openai.com/c/pay/cs_live_xxx...",
        "userEmail": "example@gmail.com",
        "updatedAt": "2025-11-26 15:18:49",
        "errorMessage": null,
        "fullToken": "{...}",
        "account": {
            "id": "094a43f5-9cad-43e7-80f3-76d354b4bce5"
        }
    },
    "timestamp": 1764141531348,
    "error": false,
    "success": true
}
```

### data 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| usageId | number | 使用记录ID |
| status | number | 任务状态（见状态码表） |
| cardKey | string | 卡密密钥 |
| rechargeUrl | string | OpenAI支付链接 |
| userEmail | string | 用户邮箱 |
| updatedAt | string | 最后更新时间 |
| errorMessage | string \| null | 错误消息（失败时返回） |
| fullToken | string | 完整令牌信息 |
| account | object | 账户信息 |
| account.id | string | 账户ID |

### 任务状态码

| 状态码 | 说明 |
|--------|------|
| 0 | 处理中 |
| 2 | 充值成功 |

---

## 5. 查看任务日志

获取指定充值任务的执行日志。

### 请求

```
GET /api/bank-card-usage/{usageId}/logs
```

### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| usageId | number | 是 | 使用记录ID |

### 请求头

| Header | 值 |
|--------|-----|
| Accept | application/json |
| Origin | https://ow800.com |
| Referer | https://ow800.com/ |

### 响应

```json
{
    "code": 200,
    "message": null,
    "data": [
        {
            "code": "pageLoaded",
            "en": "API loading...",
            "detail": "任务 321 (k16x2o0o): 页面加载完成",
            "zh": "api加载中...",
            "timestamp": "2025-11-26T15:17:21.665248049"
        },
        {
            "code": "submitClicked",
            "en": "Submitting payment request...",
            "detail": "已点击订阅按钮（鼠标点击）",
            "zh": "提交支付请求...",
            "timestamp": "2025-11-26T15:17:48.107304263"
        },
        {
            "code": "checkingPayment",
            "en": "Verifying payment...",
            "detail": "status=already_paid, elapsed=3.28s",
            "zh": "支付核验中...",
            "timestamp": "2025-11-26T15:18:36.515406555"
        }
    ],
    "timestamp": 1764141531171,
    "error": false,
    "success": true
}
```

### data 数组元素说明

| 字段 | 类型 | 说明 |
|------|------|------|
| code | string | 日志事件代码 |
| en | string | 英文描述 |
| zh | string | 中文描述 |
| detail | string | 详细信息 |
| timestamp | string | 事件时间戳（ISO 8601格式） |

### 日志事件代码

| 代码 | 英文说明 | 中文说明 |
|------|----------|----------|
| pageLoaded | API loading... | api加载中... |
| submitClicked | Submitting payment request... | 提交支付请求... |
| checkingPayment | Verifying payment... | 支付核验中... |

---

## 完整调用流程

```
┌─────────────────┐
│  1. 校验卡密    │
│  POST /api/     │
│  cards/verify   │
└────────┬────────┘
         │ 卡密有效
         ▼
┌─────────────────┐
│ 2. 查询渠道状态  │
│ GET /api/       │
│ dashboard/stats │
└────────┬────────┘
         │ 渠道可用
         ▼
┌─────────────────┐
│ 3. 提交充值任务  │
│ POST /api/      │
│ recharge/perform│
└────────┬────────┘
         │ 获取 usageId
         ▼
┌─────────────────┐
│ 4. 轮询任务状态  │◄────┐
│ GET /api/       │     │
│ recharge/status │     │ status=0
└────────┬────────┘     │ (处理中)
         │              │
         ├──────────────┘
         │ status=2 (成功)
         ▼
┌─────────────────┐
│ 5. 查看任务日志  │
│ GET /api/bank-  │
│ card-usage/logs │
└─────────────────┘
```

---

## 通用请求头

所有请求建议携带以下请求头：

```http
Accept: application/json, text/plain, */*
Accept-Language: zh-CN,zh;q=0.9,en;q=0.8
Origin: https://ow800.com
Referer: https://ow800.com/
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36
```

---

## 注意事项

1. **Token有效期**: `accessToken` 和 `fullToken` 中的令牌有有效期限制，过期后需要重新获取
2. **轮询间隔**: 查询任务状态时建议设置合理的轮询间隔（如3-5秒），避免频繁请求
3. **跨域请求**: API支持来自 `https://ow800.com` 的跨域请求
4. **错误处理**: 即使HTTP状态码为200，也需要检查响应体中的 `success` 和 `error` 字段判断实际结果