SingBox-Gopanel/docs/API.md

# API 文档

本文档覆盖当前 Go 重构版本中已经接入并可用于前台/后台重构联调的主要接口。

## 认证与通用约定

- 基础前缀：`/api`
- 用户接口：`/api/v1/user/*`
- 后台配置接口：`/api/v2/{secure_path}/*`
- plugin 后台接口：`/api/v1/{secure_path}/*`
- 鉴权方式：`Authorization: Bearer <jwt>`
- 标准成功响应：

```json
{
  "data": {}
}
```

## Supplementary Parity Endpoints

The current Go backend also exposes these Xboard-compatible endpoints:

- `POST /api/v1/passport/auth/getQuickLoginUrl`
- `POST /api/v1/passport/auth/loginWithMailLink`
- `POST /api/v1/passport/comm/pv`
- `GET /api/v1/user/comm/config`
- `POST /api/v1/user/transfer`
- `POST /api/v1/user/getQuickLoginUrl`
- `GET /api/v1/user/notice/fetch`
- `GET /api/v1/user/stat/getTrafficLog`
- `GET /api/v1/user/invite/save`
- `GET /api/v1/user/invite/fetch`
- `GET /api/v1/user/invite/details`
- `POST /api/v1/user/order/save`
- `POST /api/v1/user/order/checkout`
- `GET /api/v1/user/order/check`
- `GET /api/v1/user/order/detail`
- `GET /api/v1/user/order/fetch`
- `GET /api/v1/user/order/getPaymentMethod`
- `POST /api/v1/user/order/cancel`
- `POST /api/v1/user/coupon/check`
- `GET /api/v1/user/telegram/getBotInfo`
- `POST /api/v1/user/comm/getStripePublicKey`
- `POST /api/v1/user/gift-card/check`
- `POST /api/v1/user/gift-card/redeem`
- `GET /api/v1/user/gift-card/history`
- `GET /api/v1/user/gift-card/detail`
- `GET /api/v1/user/gift-card/types`
- `POST /api/v2/{secure_path}/config/save`

Notes:

- order APIs now cover create, query, cancel, payment-method lookup, and zero-amount completion
- invite APIs now read/write the existing `v2_*` tables directly
- gift card routes are no longer `501`, but full reward-application business logic still needs a later dedicated migration

- 标准失败响应：

```json
{
  "message": "error message"
}
```

## Passport

### POST `/api/v1/passport/auth/login`

登录。

请求：

```json
{
  "email": "admin@example.com",
  "password": "password123"
}
```

响应：

```json
{
  "data": {
    "token": "<jwt>",
    "auth_data": "<jwt>",
    "is_admin": true
  }
}
```

### POST `/api/v1/passport/auth/register`

注册并直接返回登录态。

### GET `/api/v1/passport/auth/token2Login?verify=<token>`

使用一次性 `verify` 令牌换取登录态。

### POST `/api/v1/passport/comm/sendEmailVerify`

生成邮箱验证码。

请求：

```json
{
  "email": "user@example.com"
}
```

响应中会返回 `debug_code`，便于当前开发阶段联调。

### POST `/api/v1/passport/auth/forget`

使用邮箱验证码重置密码。

请求：

```json
{
  "email": "user@example.com",
  "email_code": "123456",
  "password": "new-password"
}
```

## 用户前台接口

### GET `/api/v1/user/info`

返回当前用户信息。

### GET `/api/v1/user/getSubscribe`

返回订阅信息与订阅链接。

### GET `/api/v1/user/getStat`

返回 `[待支付订单数, 打开工单数, 邀请人数]`。

### GET `/api/v1/user/server/fetch`

返回当前用户可用节点列表。

### GET `/api/v1/user/checkLogin`

返回当前登录状态与管理员标记。

### GET `/api/v1/user/resetSecurity`

重置订阅令牌与 UUID。

### POST `/api/v1/user/changePassword`

修改密码。

### POST `/api/v1/user/update`

更新 `remind_expire` / `remind_traffic`。

## 知识库

### GET `/api/v1/user/knowledge/fetch`

返回知识库文章列表。

查询参数：

- `language`: 可选，默认 `zh-CN`

### GET `/api/v1/user/knowledge/getCategory`

返回知识库分类列表。

## 工单

### GET `/api/v1/user/ticket/fetch`

不带 `id` 时返回当前用户工单列表。

### GET `/api/v1/user/ticket/fetch?id=<ticketId>`

返回工单详情与消息列表。

### POST `/api/v1/user/ticket/save`

创建工单。

请求：

```json
{
  "subject": "节点异常",
  "level": 1,
  "message": "请帮我检查节点状态"
}
```

### POST `/api/v1/user/ticket/reply`

回复工单。

### POST `/api/v1/user/ticket/close`

关闭工单。

### POST `/api/v1/user/ticket/withdraw`

撤回工单，当前实现为将工单状态置为关闭。

## 活跃会话

### GET `/api/v1/user/getActiveSession`

返回当前用户活跃 JWT 会话列表。

### POST `/api/v1/user/removeActiveSession`

撤销指定会话。

请求：

```json
{
  "session_id": "uuid"
}
```

## Plugin: Real Name Verification

### GET `/api/v1/user/real-name-verification/status`

返回实名状态、是否可提交、实名信息掩码、审核结果等。

### POST `/api/v1/user/real-name-verification/submit`

提交实名信息。

请求：

```json
{
  "real_name": "张三",
  "identity_no": "110101199001011234"
}
```

管理端：

- `GET /api/v1/{secure_path}/realname/records`
- `POST /api/v1/{secure_path}/realname/review/{userId}`
- `POST /api/v1/{secure_path}/realname/reset/{userId}`
- `POST /api/v1/{secure_path}/realname/sync-all`
- `POST /api/v1/{secure_path}/realname/approve-all`
- `POST /api/v1/{secure_path}/realname/clear-cache`

## Plugin: User Online Devices

### GET `/api/v1/user/user-online-devices/get-ip`

返回：

- 在线 IP 列表
- `session_overview`
  - 在线设备数
  - 设备限制
  - 活跃会话列表

管理端：

- `GET /api/v1/{secure_path}/user-online-devices/users`

## Plugin: User Add IPv6 Subscription

### GET `/api/v1/user/user-add-ipv6-subscription/check`

检查当前用户是否允许启用 IPv6 子账号。

### POST `/api/v1/user/user-add-ipv6-subscription/enable`

启用或同步 IPv6 影子账号。

### POST `/api/v1/user/user-add-ipv6-subscription/sync-password`

将主账号密码同步到 IPv6 子账号。

## 后台统一接口

### GET `/api/v2/{secure_path}/config/fetch`

返回应用名称、站点 URL、后台路径、节点拉取/推送周期。

### GET `/api/v2/{secure_path}/system/getSystemStatus`

返回系统时间与站点基础信息。

### GET `/api/v2/{secure_path}/plugin/getPlugins`

返回 `v2_plugins` 列表。

### GET `/api/v2/{secure_path}/plugin/types`

返回插件类型。

### GET `/api/v2/{secure_path}/plugin/integration-status`

返回当前 plugin 在 Go 后端中的整合完成度说明。

示例字段：

```json
{
  "data": {
    "real_name_verification": {
      "enabled": true,
      "status": "complete"
    },
    "user_online_devices": {
      "enabled": true,
      "status": "complete"
    },
    "user_add_ipv6_subscription": {
      "enabled": true,
      "status": "integrated_with_runtime_sync"
    }
  }
}
```