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 文档。

⚠️ 编码要求：所有请求和响应均使用 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	是	系统编码，需在网关平台已注册且启用

请求示例

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	使用提示

---

3. 校验 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..."}'

成功响应

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

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

成功响应

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

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 调用示例

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 文档

快速示例：

# 获取 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	服务内部错误