# Team Card Web API 文档

本文档描述 Team Card Web 对外可用接口和主要页面表单。所有示例中的域名使用 `BASE_URL` 占位。

## 1. 通用说明

### 1.1 基础地址

```text
BASE_URL=https://7888.pw
```

### 1.2 内容类型

JSON 接口：

```http
Content-Type: application/json
Accept: application/json
```

下载接口返回：

```http
Content-Type: application/zip
Content-Disposition: attachment
```

### 1.3 授权方式

| 接口类型 | 授权方式 |
| --- | --- |
| `/api/health` | 无需授权 |
| `/api/mail` | 卡密授权 |
| `/api/mail/batch` | 卡密授权 |
| 前台兑换页面 | CSRF 表单 token |
| 后台页面 | 管理员 Cookie Session + CSRF 表单 token |

接码 API 不需要后台登录。只要卡密有效，就能查询该卡密绑定邮箱的验证码。

### 1.4 错误格式

JSON 接口通常返回：

```json
{
  "ok": false,
  "error": "invalid json"
}
```

或：

```json
{
  "ok": false,
  "result": {
    "code": "CARD_CODE",
    "error": "card code and email do not match"
  }
}
```

## 2. 健康检查

### GET `/api/health`

检查服务和数据库状态。

请求：

```bash
curl "$BASE_URL/api/health"
```

成功响应：

```json
{
  "status": "ok",
  "db": "team_card",
  "installed": true
}
```

数据库异常响应：

```json
{
  "status": "db_error",
  "db": "team_card",
  "installed": true,
  "error": "dial tcp ..."
}
```

状态码：

| 状态码 | 含义 |
| --- | --- |
| `200` | 服务正常 |
| `503` | 数据库连接异常 |

## 3. 单卡密接码

### GET `/api/mail`

通过卡密查询绑定邮箱邮件和验证码。

查询参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `code` | 是 | 卡密 |
| `email` | 否 | 指定要查询的邮箱；不填则查询该卡密绑定的所有邮箱 |
| `include_raw` | 否 | `1` 或 `true` 时返回邮箱站原始 JSON |

请求：

```bash
curl "$BASE_URL/api/mail?code=CARD_CODE&email=user@example.com"
```

成功响应：

```json
{
  "ok": true,
  "result": {
    "code": "CARD_CODE",
    "targets": [
      {
        "email": "user@example.com",
        "name": "user@example.com",
        "url": "/mail?code=CARD_CODE&email=user%40example.com",
        "latest_code": "202123",
        "records": [
          {
            "subject": "你的临时 ChatGPT 登录代码",
            "from": "ChatGPT <noreply@tm.openai.com>",
            "to": "user@example.com",
            "received_at": "2026-08-07 05:13:07",
            "code": "202123",
            "body": "..."
          }
        ]
      }
    ]
  }
}
```

错误响应：

```json
{
  "ok": false,
  "result": {
    "code": "CARD_CODE",
    "error": "card code and email do not match"
  }
}
```

### POST `/api/mail`

POST JSON 方式查询单卡密。

请求体：

```json
{
  "code": "CARD_CODE",
  "email": "user@example.com",
  "include_raw": true
}
```

请求：

```bash
curl -X POST "$BASE_URL/api/mail" \
  -H "Content-Type: application/json" \
  -d '{"code":"CARD_CODE","email":"user@example.com","include_raw":true}'
```

响应字段同 GET `/api/mail`。

## 4. 批量接码

### POST `/api/mail/batch`

批量查询多张卡密绑定邮箱的验证码。

限制：

- 最多 2000 张卡密。
- 重复卡密会自动去重。
- 卡密会自动去空格并转大写。
- 批量请求会复用一次邮箱列表，并按邮箱缓存查信结果。

请求体字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | string | 否 | 单张卡密，兼容单卡调用 |
| `codes` | string[] | 否 | 卡密数组 |
| `codes_text` | string | 否 | 多行卡密文本，也支持逗号、分号分隔 |
| `include_raw` | bool | 否 | 是否返回邮箱站原始 JSON |

`code`、`codes`、`codes_text` 至少提供一个。

请求示例：

```bash
curl -X POST "$BASE_URL/api/mail/batch" \
  -H "Content-Type: application/json" \
  -d '{"codes":["CARD1","CARD2"],"include_raw":false}'
```

多行文本示例：

```bash
curl -X POST "$BASE_URL/api/mail/batch" \
  -H "Content-Type: application/json" \
  -d '{"codes_text":"CARD1\nCARD2\nCARD3"}'
```

成功响应：

```json
{
  "ok": true,
  "results": [
    {
      "code": "CARD1",
      "targets": [
        {
          "email": "user1@example.com",
          "latest_code": "202123",
          "records": []
        }
      ]
    },
    {
      "code": "CARD2",
      "error": "card code and email do not match"
    }
  ]
}
```

表单方式也支持：

```bash
curl -X POST "$BASE_URL/api/mail/batch" \
  --data-urlencode "codes=CARD1
CARD2" \
  --data-urlencode "include_raw=false"
```

状态码：

| 状态码 | 含义 |
| --- | --- |
| `200` | 批量请求已处理，单个卡密结果看 `results[].error` |
| `400` | JSON/Form 格式错误，或没有传入卡密 |

## 5. 接码响应对象

### `MailLookupResult`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 卡密 |
| `targets` | array | 该卡密可查询的邮箱 |
| `error` | string | 卡密级错误 |

### `MailTargetResult`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `email` | string | 绑定邮箱 |
| `name` | string | 账号名称 |
| `url` | string | 站内接码页面链接 |
| `latest_code` | string | 优先提取到的最新验证码 |
| `records` | array | 邮件记录 |
| `raw_json` | string | `include_raw=true` 时返回 |
| `error` | string | 邮箱级错误 |

### `MailRecordView`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `subject` | string | 邮件标题 |
| `from` | string | 发件人 |
| `to` | string | 收件人 |
| `received_at` | string | 接收时间 |
| `code` | string | 从本封邮件中提取的验证码 |
| `body` | string | 邮件正文预览 |
| `raw_json` | string | 单封邮件原始 JSON |

## 6. 前台页面接口

这些接口由页面表单调用，带 CSRF 校验。对接自动化时建议使用页面返回的隐藏 `_csrf` 字段。

### GET `/`

兑换首页。

### POST `/redeem`

校验卡密并展示可下载格式。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `code` | 是 | 卡密 |

### POST `/redeem/download`

下载单张卡密 ZIP。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `code` | 是 | 卡密 |
| `export_format` | 是 | 导出格式 |

下载成功返回 ZIP。每次下载都会记录 IP、格式、时间，并累加下载次数。

### POST `/redeem/batch`

批量下载卡密 ZIP。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `codes` | 是 | 多行卡密 |
| `format` | 否 | 导出格式，默认 `sub2api` |

批量下载结果会在 ZIP 内包含 `_result.txt`，记录成功和失败的卡密。

### GET `/mail`

站内单卡密接码页面。

查询参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `code` | 是 | 卡密 |
| `email` | 否 | 指定邮箱 |

### GET `/mail/batch`

批量接码页面。

### POST `/mail/batch`

批量接码页面提交。最多 2000 张卡密。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `codes` | 是 | 多行卡密 |

## 7. 后台页面接口

后台页面需要先登录 `/admin/login`。

### GET `/admin/login`

后台登录页。

### POST `/admin/login`

提交后台登录。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `username` | 是 | 管理员用户名 |
| `password` | 是 | 管理员密码 |

### POST `/admin/logout`

退出后台登录。

### GET `/admin`

后台首页。

查询参数：

| 参数 | 说明 |
| --- | --- |
| `cards_page` | 卡密列表页码 |
| `accounts_page` | 账号列表页码 |
| `redemptions_page` | 下载记录页码 |
| `card_q` | 卡密列表搜索：卡密、IP、备注、格式 |
| `download_q` | 下载记录搜索：卡密、IP、格式 |
| `generated_batch` | 查看刚生成批次的卡密 |
| `ok` | 成功提示 |
| `error` | 错误提示 |

### POST `/admin/upload`

上传单个账号 JSON 文件。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `file` | 是 | `.json` 文件 |

### POST `/admin/upload-multiple`

批量上传账号 JSON 文件。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `files[]` 或 `files` | 是 | 多个 `.json` 文件 |

### POST `/admin/cards`

生成卡密。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `account_count` | 是 | 每张卡密绑定账号数量 |
| `card_quantity` | 是 | 生成卡密数量 |
| `note` | 否 | 备注 |

成功后重定向到 `/admin?generated_batch=批次号`。

### POST `/admin/quota`

刷新指定账号的 OpenAI/Codex 额度。此接口仅供后台账号列表中的“刷新额度”操作使用。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `account_id` | 是 | 后台账号 ID |

### POST `/admin/quota-proxies`

保存额度查询使用的 SOCKS5 代理池。此接口仅供管理员后台使用。

表单字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `_csrf` | 是 | 页面隐藏 CSRF |
| `quota_socks5_proxies` | 否 | 多行 SOCKS5 代理；系统会规范化为 `socks5h://` 并自动去重 |

## 8. 导出格式参数

下载接口的格式字段支持以下值和别名：

| 推荐值 | 别名 | 内部格式 |
| --- | --- | --- |
| `sub2_json` | `sub2api`、`sub2` | `sub2api` |
| `cpa_json` | `cpa` | `cpa` |
| `codexManager_json` | `codexmanager`、`codex_manager`、`codexmanager_json` | `codexmanager` |
| `cockpit_tools_json` | `cockpit`、`cockpit_json` | `cockpit` |
| `batch_oauth_json` | `batchoauth`、`batch_oauth` | `batchoauth` |
| `9router` | `nine_router`、`ninerouter` | `9router` |
| `codex` | `codex_json`、`auth_json` | `codex` |
| `axonhub` | `axonhub_json` | `axonhub` |

## 9. 导入 JSON 字段兼容

系统会从多个路径识别账号字段，常用兼容字段如下。

令牌：

| 含义 | 支持字段 |
| --- | --- |
| access token | `accessToken`、`access_token`、`tokens.accessToken`、`tokens.access_token`、`token.accessToken`、`token.access_token`、`credentials.accessToken`、`credentials.access_token` |
| refresh token | `refreshToken`、`refresh_token`、`tokens.refreshToken`、`tokens.refresh_token`、`token.refreshToken`、`token.refresh_token`、`credentials.refresh_token` |
| id token | `idToken`、`id_token`、`tokens.idToken`、`tokens.id_token`、`token.idToken`、`token.id_token`、`credentials.id_token` |
| session token | `sessionToken`、`session_token`、`tokens.sessionToken`、`tokens.session_token`、`credentials.session_token` |

账号信息：

| 含义 | 支持字段 |
| --- | --- |
| 邮箱 | `email`、`user.email`、`credentials.email`、`providerSpecificData.email` |
| 账号 ID | `chatgpt_account_id`、`chatgptAccountId`、`account_id`、`account.id`、JWT payload 中的 OpenAI auth 字段 |
| 用户 ID | `user_id`、`user.id`、`chatgptUserId`、JWT payload 中的 OpenAI auth 字段 |
| 套餐 | `plan_type`、`planType`、`account.plan_type`、`providerSpecificData.chatgpt_plan_type` |
| 组织 ID | `organization_id`、`organizationId`、`org_id`、`orgId` |
| GPT 密码 | `password`、`gptPassword`、`gpt_password`、`gpt.password` |

接码邮箱：

| 含义 | 支持字段 |
| --- | --- |
| 邮箱地址 | `mailbox.email`、`email_account.email`、`extra.email_account.email`、`email` |
| 邮箱密码 | `emailPassword`、`email_password`、`mailbox.emailPassword`、`mailbox.email_password` |
| 邮箱 client ID | `email_client_id`、`emailClientId`、`mailbox.clientId`、`mailbox.client_id` |
| 邮箱 refresh token | `graphRefreshToken`、`graph_refresh_token`、`oauth2_refresh_token`、`mailbox.graphRefreshToken`、`mailbox.oauth2_refresh_token` |

## 10. 调用建议

- 对接下载建议走页面表单流程，因为下载接口有 CSRF 校验。
- 对接接码建议直接走 `/api/mail` 或 `/api/mail/batch`。
- 大客户批量接码优先使用 `/api/mail/batch`，不要并发打大量 `/api/mail`。
- `include_raw=true` 只建议排查问题时使用，正常业务保持 `false`，响应更小。
- 同一张卡密重复下载会正常记录，不影响再次接码。