450 lines
12 KiB
Markdown
450 lines
12 KiB
Markdown
# 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 管理员。
|