mokeegateway/docs/open-api-doc.md

# Mokee Gateway 对外开放 API 文档

**网关地址**: `https://gw.server.zgitm.com`  
**版本**: v1  
**更新时间**: 2026-06-13  

---

## 1. 概述

对外开放 API 用于外部业务系统接入 Mokee 网关平台，支持获取一次性 Token、校验 Token、标记 Token 已消费、发送邮件等功能。

> 📦 **文件上传/下载** 已迁移至独立的文件对象存储服务 `file.wg.zgitm.com`，详见 [文件对象存储服务 API 文档](#10-文件对象存储服务)。

> ⚠️ **编码要求**：所有请求和响应均使用 **UTF-8** 编码。

### 认证流程

```
外部系统 ──POST /zgapi/v1/open/token──▶ 获取一次性 Token
外部系统 ──POST /zgapi/v1/open/token/validate──▶ 校验 Token（不消费）
外部系统 ──GET  /zgapi/v1/open/token/info──▶ 查询系统信息（不消费）
外部系统 ──POST /zgapi/v1/open/token/consume──▶ 标记 Token 已消费
外部系统 ──POST /zgapi/v1/open/email/send──▶ 发送邮件（消费 Token）
```

### Token 规则

| 规则 | 说明 |
|------|------|
| 获取方式 | 传入 `systemCode` 即可获取，无需密钥 |
| 有效期 | 获取后 **12 小时**内有效 |
| 消费限制 | 每个 Token **只能使用一次**，调用任意接口即消费 |
| 消费失败 | 接口调用失败（如邮件发送失败）**不消费** Token，可重试 |

---

## 2. 获取 Token

传入系统编码，获取一次性 JWT Token。

**请求**

```
POST /zgapi/v1/open/token
Content-Type: application/json; charset=UTF-8
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| systemCode | string | 是 | 系统编码，需在网关平台已注册且启用 |

**请求示例**

```bash
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
  -H "Content-Type: application/json" \
  -d '{"systemCode": "gateway"}'
```

**响应**

```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOi...",
    "expiresIn": 43200,
    "systemName": "网关管理平台",
    "usageNote": "此 Token 只能消费一次，消费后立即失效"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 200=成功 |
| data.token | string | JWT Token，后续请求放入 Authorization 头 |
| data.expiresIn | int | 有效时间（秒），43200 = 12小时 |
| data.systemName | string | 系统名称 |
| data.usageNote | string | 使用提示 |

---

## 3. 校验 Token（不消费）

检查 Token 是否有效。**不会消费 Token**。

```
POST /zgapi/v1/open/token/validate
Content-Type: application/json; charset=UTF-8
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| token | string | 是 | 需要校验的 JWT Token |

```bash
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/validate" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJIUzM4NCJ9..."}'
```

**成功响应**

```json
{ "code": 200, "data": { "valid": true, "systemCode": "gateway", "msg": "Token 有效，未被消费" } }
```

---

## 4. 查询 Token 系统信息（不消费）

根据 Token 查询所属系统信息。**不消费 Token**，不检查已消费状态，仅从 JWT 解析。

```
GET /zgapi/v1/open/token/info?token=<token>
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| token | string | 是 | query 参数传递 JWT Token |

```bash
curl "https://gw.server.zgitm.com/zgapi/v1/open/token/info?token=eyJhbGciOiJIUzM4NCJ9..."
```

**成功响应**

```json
{
  "code": 200,
  "data": {
    "systemId": "30957c6264d511f18b7900e04c896f92",
    "systemCode": "gateway",
    "systemName": "网关管理平台"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| data.systemId | string | 系统唯一 ID |
| data.systemCode | string | 系统编码 |
| data.systemName | string | 系统名称 |

---

## 5. 标记 Token 已消费

外部系统在自己的业务中消费了 Token 后，调用此接口告知网关。

```
POST /zgapi/v1/open/token/consume
Content-Type: application/json; charset=UTF-8
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| token | string | 是 | 需要标记的 Token |
| action | string | 是 | 消费动作，如 `发送邮件` / `上传文件` |

```bash
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/consume" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ...", "action": "上传文件"}'
```

---

## 6. 发送邮件

使用 Token 认证后发送邮件。**调用此接口将消费当前 Token。**

```
POST /zgapi/v1/open/email/send
Content-Type: application/json; charset=UTF-8
Authorization: Bearer <token>
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| to | string | 是 | 收件人邮箱 |
| subject | string | 是 | 邮件主题 |
| content | string | 是 | 邮件内容 |
| contentType | string | 否 | `html`（默认）或 `text` |

---

## 7. Java 调用示例

```java
import cn.hutool.http.HttpRequest;

public class OpenApiDemo {
    private static final String BASE = "https://gw.server.zgitm.com";

    public static void main(String[] args) {
        // 1. 获取 Token
        String tokenResp = HttpRequest.post(BASE + "/zgapi/v1/open/token")
                .body("{\"systemCode\":\"gateway\"}").execute().body();
        String token = JSONUtil.parseObj(tokenResp).getJSONObject("data").getStr("token");

        // 2. 校验 Token
        String validResp = HttpRequest.post(BASE + "/zgapi/v1/open/token/validate")
                .body("{\"token\":\"" + token + "\"}").execute().body();
        System.out.println(validResp);

        // 3. 发送邮件
        String emailResp = HttpRequest.post(BASE + "/zgapi/v1/open/email/send")
                .header("Authorization", "Bearer " + token)
                .body("{\"to\":\"user@example.com\",\"subject\":\"测试\",\"content\":\"<h1>Hello</h1>\"}")
                .execute().body();
        System.out.println(emailResp);
    }
}
```

---

## 8. 文件对象存储服务

文件上传/下载/删除功能由独立的文件对象存储服务提供。

| 项目 | 说明 |
|------|------|
| 服务地址 | `https://file.wg.zgitm.com` |
| 认证方式 | Bearer Token（一次一密） |
| 最大文件 | 100MB |
| 文档 | 详见文件服务 API 文档 |

**快速示例**：

```bash
# 获取 Token
TOKEN=$(curl -s -X POST https://file.wg.zgitm.com/api/token \
  -H "Content-Type: application/json" \
  -d '{"systemCode":"gateway"}' | jq -r '.data.token')

# 上传
curl -X POST https://file.wg.zgitm.com/api/upload \
  -H "Authorization: Bearer $TOKEN" -F "file=@/path/to/file.pdf"

# 下载（两种方式等效）
# 方式1: Header 传 Token
curl -H "Authorization: Bearer $TOKEN" -o output.pdf \
  https://file.wg.zgitm.com/api/download/{fileId}
# 方式2: URL Query 参数传 Token（浏览器直链时使用）
curl -o output.pdf \
  "https://file.wg.zgitm.com/api/download/{fileId}?token=$TOKEN"

# 删除
curl -H "Authorization: Bearer $TOKEN" \
  https://file.wg.zgitm.com/api/delete/{fileId}
```

---

## 9. 附录

### 错误码汇总

| HTTP | code | 说明 |
|:----:|:----:|------|
| 200 | 200 | 成功 |
| 200 | 400 | 参数错误 |
| 200 | 401 | 认证失败 |
| 200 | 500 | 服务内部错误 |