mokeegateway/_backup_20260613/open-api-doc.md

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	是	系统编码，需在网关平台已注册且启用

请求示例

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

响应

{
  "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

请求示例

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

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

{
  "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	是	消费动作描述，如 发送邮件 / 上传文件 / 下载文件

请求示例

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

成功响应

{
  "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

请求示例

# 先获取 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"
  }'

成功响应

{
  "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）

请求示例

# 先获取 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"

成功响应

{
  "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 参数）

请求示例

# 先获取 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 示例：

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 依赖

<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 管理员。