# Mokee Gateway 对外开放 API 文档

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

---

## 1. 概述

对外开放 API 用于外部业务系统接入 Mokee 网关平台，支持获取一次性 Token 并调用邮件发送等功能。

> ⚠️ **编码要求**：所有请求和响应均使用 **UTF-8** 编码。`Content-Type` 必须指定 `charset=UTF-8`，否则中文会出现乱码或解析错误。

### 认证流程

```
外部系统 ──POST /zgapi/v1/open/token──▶ 获取一次性 Token
外部系统 ──POST /zgapi/v1/open/token/validate──▶ 校验 Token（不消费）
外部系统 ──POST /zgapi/v1/open/token/consume──▶ 标记 Token 已消费
外部系统 ──POST /zgapi/v1/open/email/send──▶ 发送邮件（消费 Token）
外部系统 ──POST /zgapi/v1/open/file/upload──▶ 上传文件（消费 Token）
外部系统 ──GET  /zgapi/v1/open/file/{id}/download──▶ 下载文件（消费 Token）
```

### Token 规则

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

---

## 2. 获取 Token

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

**请求**

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

> **重要**：所有请求 Body 必须使用 **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 | 使用提示 |

**错误响应**

| code | 说明 |
|:----:|------|
| 400 | 缺少 `systemCode` 参数 |
| 401 | `systemCode` 无效或系统已停用 |

---

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

检查 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..."}'
```

**成功响应（Token 有效，未被消费）**

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

| 字段 | 类型 | 说明 |
|------|------|------|
| data.valid | bool | true = Token 有效可用 |
| data.systemCode | string | Token 所属的系统编码 |
| data.msg | string | 状态描述 |

**错误响应**

| code | 说明 |
|:----:|------|
| 400 | 缺少 `token` 参数 |
| 401 | Token 无效、已过期、已被消费、或类型错误 |

> **关键：此接口不会消费 Token。** 校验通过后 Token 仍可用于后续操作。

---

## 4. 标记 Token 已消费

外部系统在自己的业务逻辑中消费了 Token 后（如上传文件到自己的存储），调用此接口告知网关标记 Token 已消费，防止被重复使用。

**请求**

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

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

**请求示例**

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

**成功响应**

```json
{
  "code": 200,
  "data": {
    "tokenConsumed": true,
    "action": "上传文件",
    "msg": "Token 已标记为已消费"
  }
}
```

**错误响应**

| code | 说明 |
|:----:|------|
| 400 | 缺少 `token` 或 `action` 参数 |
| 401 | Token 无效、已过期、或已被消费 |

---

## 5. 发送邮件

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

**请求**

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

> **重要**：请求 Body 必须使用 **UTF-8** 编码。

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

**请求示例**

```bash
# 先获取 Token
TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
  -H "Content-Type: application/json" \
  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')

# 发送 HTML 邮件
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/email/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "to": "user@example.com",
    "subject": "通知标题",
    "content": "<h1>您好</h1><p>这是邮件内容</p>",
    "contentType": "html"
  }'
```

**成功响应**

```json
{
  "code": 200,
  "data": {
    "msg": "发送成功",
    "tokenConsumed": true
  }
}
```

**错误响应**

| code | 说明 |
|:----:|------|
| 400 | 缺少必填参数 `to` / `subject` / `content` |
| 401 | Token 无效、已过期或已消费 |
| 500 | 邮件发送失败（Token 未消费，可重试） |

---

## 6. 上传文件

使用 Token 认证后上传文件到文件对象存储。**调用此接口将消费当前 Token。**

> 上传成功后返回文件 ID，可用于后续下载。

**请求**

```
POST /zgapi/v1/open/file/upload
Content-Type: multipart/form-data
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| file | file | 是 | 上传的文件 |
| token | string | 是 | 开放 API Token（作为 form 字段传递） |
| fileType | string | 否 | 文件类型: `avatar`/`icon`/`doc`/`other`（默认 `other`） |

**请求示例**

```bash
# 先获取 Token
TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
  -H "Content-Type: application/json" \
  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')

# 上传文件
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/file/upload" \
  -F "file=@/path/to/avatar.png" \
  -F "token=$TOKEN" \
  -F "fileType=avatar"
```

**成功响应**

```json
{
  "code": 200,
  "data": {
    "fileId": "a1b2c3d4e5f6",
    "fileName": "avatar.png",
    "storageFileName": "a1b2c3d4e5f6.png",
    "fileSize": 51200,
    "tokenConsumed": true
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| data.fileId | string | 文件唯一 ID，用于下载 |
| data.fileName | string | 原始文件名 |
| data.storageFileName | string | 磁盘存储的实际文件名 |
| data.fileSize | long | 文件大小（字节） |
| data.tokenConsumed | bool | Token 已消费 |

**错误响应**

| code | 说明 |
|:----:|------|
| 400 | 缺少 `file` 或 `token` 参数 |
| 401 | Token 无效、已过期或已消费 |
| 500 | 文件上传失败（Token 未消费，可重试） |

---

## 7. 下载文件

使用 Token 认证后下载文件。**调用此接口将消费当前 Token。**
Token 通过 URL query 参数传递。

> **注意**: 每个下载链接的 Token 只能使用一次。如需多次下载，需每次获取新 Token。

**请求**

```
GET /zgapi/v1/open/file/{id}/download?token=<token>
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| id | string | 是 | 文件 ID（路径参数） |
| token | string | 是 | 开放 API Token（query 参数） |

**请求示例**

```bash
# 先获取 Token
TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
  -H "Content-Type: application/json" \
  -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')

# 下载文件（保存到本地）
curl -o downloaded.png \
  "https://gw.server.zgitm.com/zgapi/v1/open/file/a1b2c3d4e5f6/download?token=$TOKEN"
```

**成功响应**: 直接返回文件二进制流，`Content-Type: application/octet-stream`，`Content-Disposition: attachment`。

**错误响应**

| HTTP 状态码 | code | 说明 |
|:----------:|:----:|------|
| 401 | 401 | Token 无效、已过期或已消费 |
| 404 | 404 | 文件不存在或文件数据丢失 |

---

## 8. Java 调用示例

使用 Hutool 或 OkHttp 均可，以下为 Hutool 示例：

```java
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;

public class OpenApiDemo {

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

    public static void main(String[] args) {
        // 1. 获取 Token
        JSONObject tokenReq = JSONUtil.createObj().set("systemCode", "gateway");
        String tokenResp = HttpRequest.post(BASE + "/zgapi/v1/open/token")
                .header("Content-Type", "application/json; charset=UTF-8")
                .body(tokenReq.toString())
                .execute()
                .body();

        JSONObject tokenJson = JSONUtil.parseObj(tokenResp);
        String token = tokenJson.getJSONObject("data").getStr("token");
        System.out.println("Token: " + token.substring(0, 30) + "...");

        // 2. 上传文件
        JSONObject uploadResp = HttpRequest.post(BASE + "/zgapi/v1/open/file/upload")
                .form("file", new java.io.File("./avatar.png"))
                .form("token", token)
                .form("fileType", "avatar")
                .execute()
                .body();
        System.out.println("上传结果: " + uploadResp);

        // 3. 发送邮件
        JSONObject emailReq = JSONUtil.createObj()
                .set("to", "user@example.com")
                .set("subject", "测试邮件")
                .set("content", "<h1>Hello</h1><p>这是一封测试邮件</p>")
                .set("contentType", "html");

        String emailResp = HttpRequest.post(BASE + "/zgapi/v1/open/email/send")
                .header("Authorization", "Bearer " + token)
                .body(emailReq.toString())
                .execute()
                .body();

        System.out.println(emailResp);
    }
}
```

### Maven 依赖

```xml
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.28</version>
</dependency>
```

---

## 9. 附录

### 可用系统编码

请联系管理员获取已注册的系统编码，或登录网关管理平台查看。

### 错误码汇总

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

> **注意**：所有响应 HTTP 状态码均为 200，实际结果通过响应体中的 `code` 字段判断。

### 联系支持

如有问题请联系 Mokee Gateway 管理员。