一单位一平台

主题

HzTech2026-01-05
2362
9.3m

消息发送接口文档 ​

概述 ​

消息发送模块提供了子应用向一单位一平台发送消息的能力，支持发送单条消息和批量发送消息。消息支持多种类型（通知、警告、错误、信息）和多种接收方式（用户、角色、全员）。所有接口遵循国密 SM2/SM4 数字信封加密方案，确保数据传输安全。

交互方向 ​

本模块包含以下交互方向:

交互方向接口类型子应用实现要求说明
子应用→一单位一平台(通知)发送单条消息、批量发送消息❌ 无需实现子应用主动发送消息,一单位一平台提供接收接口

重要说明:

  • 本模块所有接口均为"子应用→一单位一平台"通知接口,子应用直接调用一单位一平台提供的接口,无需额外实现
  • "通知"是"上报"的特殊形式,专用于消息发送场景

使用场景 ​

  • 子应用→一单位一平台(通知): 子应用向指定用户发送消息
  • 子应用→一单位一平台(通知): 子应用向多个用户批量发送消息
  • 业务通知: 子应用向一单位一平台用户发送业务通知、提醒等

接口设计原则 ​

所有接口均采用国密 SM2/SM4 数字信封加密方案：

  1. 统一 POST 方式：所有接口使用 POST 方法，业务参数在 encryptData 中加密传输
  2. 无路径参数：URL 路径中不包含任何业务参数，所有业务参数均在加密报文中
  3. 安全性：通过 SM2 混合加密和数字签名确保数据传输的机密性、完整性和不可抵赖性

适用范围 ​

适用于子应用向一单位一平台发送各类通知消息、系统公告等场景。

术语定义 ​

核心概念 ​

术语说明
一单位一平台核心管理平台,负责数据存储、权限管理、接口路由等核心功能
子应用接入一单位一平台的独立业务系统,通过一单位一平台网关与其他系统交互
网关一单位一平台的统一入口,负责路由转发、身份认证、权限控制、速率限制等

操作语义 ​

术语说明数据流向接口实现方
通知发送消息通知子应用→一单位一平台一单位一平台实现

重要提示:

  • "通知"是"上报"的特殊形式,专用于消息发送场景
  • "通知"表示子应用主动向一单位一平台发送消息,由一单位一平台提供接收接口

系统架构 ​

数据流向 ​

通知流程(子应用→一单位一平台) ​

子应用 → [加密通知] → 一单位一平台 → [加密响应] → 子应用

接口列表 ​

子应用→一单位一平台(通知接口) ​

接口名称请求地址交互方向说明
发送单条消息POST /hztech-message/send子→主(通知)向指定用户发送消息
批量发送消息POST /hztech-message/batch-send子→主(通知)向多个用户批量发送

注：所有业务参数均在 encryptData 中加密传输，URL 路径中不包含任何业务参数。

接口详情 ​

1.1 发送单条消息 ​

接口说明

向指定用户发送单条消息。支持多种消息类型和接收者类型。

请求方式

POST

请求地址

POST /hztech-message/send

交互方向

子应用 → 一单位一平台 (上报)

完整时序图

请求参数

参数名类型必填说明示例值
receiverString是接收者ID"1123598821738675203"
messageTypeString是消息类型系统消息/浙政钉消息
titleString是消息标题"系统通知"
contentString是消息内容"您有一条新的系统通知"
senderString否发送者ID(默认系统)"SYSTEM"

HTTP 请求示例

http
POST /hztech-message/send HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "receiver": "1123598821738675203",
  "messageType": "notification",
  "title": "系统通知",
  "content": "您有一条新的系统通知",
  "sender": "SYSTEM",
  "expireTime": "2026-01-05T00:00:00"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "messageId": "MSG_20260105_001",
    "sendTime": "2026-01-05T10:00:00"
  }
}

错误响应示例

json
{
  "code": 2403,
  "message": "接收者不存在",
  "timestamp": 1735516801000
}

1.2 批量发送消息 ​

接口说明

向多个用户批量发送消息。适用于群发通知、批量提醒等场景。

请求方式

POST

请求地址

POST /hztech-message/batch-send

交互方向

子应用 → 一单位一平台 (上报)

完整时序图

请求参数

参数名类型必填说明示例值
receiversArray是接收者ID列表["1123598821738675203", "1123598821738675204"]
messageTypeString是消息类型(系统消息/浙政钉消息)"系统消息"
titleString是消息标题"系统维护通知"
contentString是消息内容"系统将于今晚进行维护"
senderString否发送者ID"SYSTEM"

HTTP 请求示例

http
POST /hztech-message/batch-send HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "receivers": [
    "1123598821738675203",
    "1123598821738675204",
    "1123598821738675205"
  ],
  "messageType": "系统消息",
  "title": "系统维护通知",
  "content": "系统将于今晚22:00-24:00进行维护",
  "sender": "SYSTEM"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalCount": 3,
    "successCount": 3,
    "messageIds": [
      "MSG_20260105_001",
      "MSG_20260105_002",
      "MSG_20260105_003"
    ]
  }
}

数据模型 ​

消息对象 (Message) ​

完整的消息数据结构：

json
{
  "id": "string",              // 消息ID(系统生成)
  "messageType": "string",            // 消息类型
  "title": "string",                  // 消息标题
  "content": "string",                // 消息内容
  "sender": "string",                 // 发送者ID
  "senderName": "string",             // 发送者名称
  "receiver": "string",               // 接收者ID
  "receiverName": "string",           // 接收者名称
  "status": "unread",                 // 消息状态
  "createTime": "2026-01-05T00:00:00",  // 创建时间
  "sendTime": "2026-01-05T00:00:00",    // 发送时间
  "readTime": "2026-01-05T00:00:00"     // 阅读时间
}

字段说明 ​

字段类型必填说明约束
idString是消息唯一标识系统生成，不可修改
messageTypeString是消息类型系统消息/浙政钉消息
titleString是消息标题最多100个字符
contentString是消息内容最多5000个字符
senderString否发送者ID系统或用户ID，默认"SYSTEM"
senderNameString否发送者名称冗余字段
receiverString是接收者ID用户ID或角色ID
receiverNameString否接收者名称冗余字段
statusString是消息状态unread/read
createTimeString是创建时间ISO 8601格式
sendTimeString是发送时间ISO 8601格式
readTimeString否阅读时间ISO 8601格式

枚举值说明 ​

消息类型 (messageType)：

  • 1：通知消息
  • 2：浙政钉消息

消息状态 (status)：

  • unread：未读
  • read：已读

错误码 ​

业务错误码 ​

错误码说明处理建议
2401消息不存在检查messageId是否正确
2403接收者不存在检查receiver是否正确
2404消息标题不能为空检查title参数
2405消息内容不能为空检查content参数
2406消息类型错误检查messageType参数
2407消息已过期检查expireTime参数
2408接收者列表不能为空检查receivers参数
2409消息标题过长控制在100字符以内
2410消息内容过长控制在5000字符以内

系统错误码 ​

错误码说明处理建议
1001时间戳过期同步系统时间
1002重复请求检查nonce生成逻辑
1003签名验证失败检查密钥配置
1004解密失败检查密钥配置
1005appId不存在检查appId注册
1006业务逻辑错误根据具体错误处理

相关文档 ​

文档版本: v2.0.0 最后更新: 2026-01-05

最近更新