# UMS **Repository Path**: SCUTNC/ums ## Basic Information - **Project Name**: UMS - **Description**: UMS-API - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-04-01 - **Last Updated**: 2026-04-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 华工信使第三方应用API **"华工信使"是由华南理工大学建设的统一消息推送平台，面向校内用户和校内应用系统提供消息推送服务。校内第三方应用系统可通过该平台向校内外用户进行包括企业微信、短信、电子邮件等形式的消息推送。** ## V2.0 ### 接口列表 调用url为“https://ums.scut.edu.cn/api/message/open/api”+“下表路径” | **说明** | **路径** | **方式** | | -------------------------- | ----------------- | -------- | | 获取应用权限信息 | /getAuth | POST | | 发送消息 | /sendMessage | POST | | 获取消息发送结果 | /getMessageResult | POST | ### 开发步骤 1. 调用获取应用权限信息接口，可获取应用下的渠道信息。 2. 调用发送消息接口进行消息发送并获得消息发送的messageId。 3. 根据messageId调用获取消息发送结果接口查询消息发送情况。 ### 接口详细说明 #### 1、获取应用权限信息 **接口地址**:`https://ums.scut.edu.cn/api/message/open/api/getAuth` **请求方式**:`POST` **请求数据类型**:`application/json` **请求示例**: ```javascript { "appid": "", "secret": "" } ``` **请求参数**: | 参数名称 | 数据类型 | 是否必须 | 参数说明 | | :----------: | :------: | :------: | :----------: | |  appid | string | true | 应用系统账号 | |  secret | string | true | 应用系统密钥 | **响应参数**: | 参数名称 | 类型 | 参数说明 | | ------------------------------------ | -------------- | ------------ | | code | integer(int32) | 响应码 | | msg | string | 响应信息 | | data | json | 响应数据 | |   cpWxList | array | 企业微信 | |     providerId | integer(int64) | 发送通道ID | |     providerName | string | 通道名称 | |   emailList | array | 邮箱 | |     providerId | integer(int64) | 发送通道ID | |     providerName | string | 通道名称 | |   innerMessageList | array | 门户站内信 | |     providerId | integer(int64) | 发送通道ID | |     providerName | string | 通道名称 | |   smsList | array | 短信 | |     cost | number | 单价(元) | |     balance | number | 剩余短信条数 | |     providerId | integer(int64) | 发送通道ID | |     providerName | string | 通道名称 | |     sign | string | 短信通道签名 | |   labelList | array | 标签 | |     labelId | integer(int64) | 标签ID | |     labelName | string | 标签名称 | **响应示例**: ```javascript { "code": 0, "data": { "cpWxList": [ { "providerId": 0, "providerName": "" } ], "emailList": [ { "providerId": 0, "providerName": "" } ], "innerMessageList": [ { "providerId": 0, "providerName": "" } ], "smsList": [ { "cost": 0, "balance": 0, "providerId": 0, "providerName": "", "sign": "" } ], "labelList": [ { "labelId": 0, "labelName": "" } ] }, "msg": "" } ``` #### 2、发送消息 **接口地址**:`https://ums.scut.edu.cn/api/message/open/api/sendMessage` **请求方式**:`POST` **请求数据类型**:`application/json` **请求示例**: ```javascript { "appid": "xxxxx", "secret": "xxxxxx", "isSmart": false, "isTemplate": false, "templateCode": 0, "content": "测试测试", "messageSendType": 1, "accounts": [], "labelList": [], "phoneList": [ "12345678911" ], "isEmailActive": true, "isSmsActive": true, "isWxActive": true, "isInnerActive": true, "title": "", "picTextContent": "", "picUrl": "", "originalTextLink": "", "description": "", "newsUrl": "", "annexLink": "", "author": "" } ``` **请求参数**: | 参数名称 | 数据类型 | 是否必须 | 参数说明 | | :--------------: | :-------: | :------: | :---------------------------------------: | | appid | string | true | 应用系统账号 | | secret | string | true | 应用系统密钥 | | isSmart | boolean | false | 是否使用智能模式推送（true：开启；false：不开启，默认不开启） | | isSmsActive | boolean | true | 是否推送短信，false：不推送，true：推送 | | isWxActive | boolean | true | 是否推送企业微信，false：不推送，true：推送 | | isEmailActive | boolean | true | 是否推送邮箱，false：不推送，true：推送 | | isInnerActive | boolean | true | 是否推送门户站内信，false：不推送，true：推送 | | accounts | array | false | 收件人认证账号或学工号 | | labelList | array | false | 标签群发的标签ID数组 | | phoneList | array | false | 收件人手机号（如果已经传了认证账号或学工号，则不需要再提供手机号 | | isTemplate | boolean | true | 是否模板消息 | | templateCode | integer | false | 模板编号，当发送模板消息时必填 | | jsonObject | object | false | 模板消息的参数列表，以英文参数名为key，参数值为value，注意参数名左右带特殊符号# | | messageSendType | integer | true | 发送类型（1：文本；2：图文；） | | content | string | false | 文本消息的内容 | | title | string | false | 图文消息的文章标题 | | author | string | false | 图文消息的图文作者 | | picUrl | string | false | 图文消息的封面图链接 | | description | string | false | 图文消息的简介 | | picTextContent | string | false | 图文消息的内容 | | originalTextLink | string | false | 图文消息的原文链接 | | newsUrl | string | false | 图文消息的文章链接 | | annexLink | string | false | 图文消息的附件链接 | [comment]: <> (| **smsProviderId** | integer | false | 短信通道ID，非必填，用于指定某个特定通道 |) [comment]: <> (| weComProviderId | integer | false | 企业微信通道ID，非必填，用于指定某个特定通道 |) [comment]: <> (| emailProviderId | integer | false | 邮箱通道ID，非必填，用于指定某个特定通道 |) **响应参数**: | 参数名称 | 类型 | 参数说明 | | -------------------------------- | ------- | ---------------- | | code | integer | 响应码 | | msg | string | 响应信息 | | data | json | 响应数据 | |   messageId | long | 消息主体ID | |   outOfViewAccountList | array | 无效或无权限账号列表 | **响应示例**: ```javascript { "code": 0, "data": { "messageId": 0, "outOfViewAccountList": [] }, "msg": "" } ``` #### 3、获取消息发送结果 **接口地址**:`https://ums.scut.edu.cn/api/message/open/api/getMessageResult` **请求方式**:`POST` **请求数据类型**:`application/json` **请求示例**: ```javascript { "messageId": 0, "appid": "", "secret": "" } ``` **请求参数**: | 参数名称 | 数据类型 | 是否必须 | 参数说明 | | :-------------------: | :------: | -------- | ------------ | | messageId | integer | true | 消息ID | | appid | string | true | 应用系统账号 | | secret | string | true | 应用系统密钥 | **响应参数**: | 参数名称 | 类型 | 参数说明 | | -------------------------- | ----------------- | ---------------------------------- | | code | integer | 响应码 | | msg | string | 响应信息 | | data | json | 响应数据 | |   id | integer | 消息id | |   addresseeNum | integer | 收件人数 | |   content | string | 消息内容 | |   cost | integer | 计费条数 | |   pushTime | string(date-time) | 发送时间 | |   sendFailNum | integer | 发送失败人数 | |   sendStatus | string | 消息状态 1=待发送,2=已发送,3已取消 | |   sendSucceedNum | integer | 发送成功人数 | |   submitTime | string(date-time) | 提交时间 | **响应示例**: ```javascript { "code": 0, "data": { "addresseeNum": 0, "content": "", "cost": 0, "id": 0, "pushTime": "", "sendFailNum": 0, "sendStatus": "", "sendSucceedNum": 0, "stateUnsolvedNum": 0, "submitTime": "" }, "msg": "" } ``` ### 全局状态码 | 错误码 | 描述 | | ------ | ------------------------------------------------------ | | 200 | 成功 | | 400016 | 应用系统账号或者密钥不匹配 | | 400005 | 消息id不存在 | | 400028 | IP校验失败 | | 400022 | 该应用系统开启了模板限制，只支持模板消息 | | 400023 | 没有该消息类型的推送权限 | | 400024 | 模板消息必须携带模板编号 | | 400025 | 非模板的文本消息携带content参数 | | 400026 | 没有有效的接收人参数 | | 400021 | 没有有效的接收人 | | 400019 | 该应用系统短信余额不足 | | 400003 | 消息模板不存在 | | 400034 | 渠道权限不足 | | 500000 | 业务异常 | | 500 | 系统异常 | ## V1.0（已废弃） ### 第三方集成身份认证接口 接入华南理工大学统一身份认证的第三WebAPP，可通过添加"华工信使第三方放认证接口"实现与华工信使APP、华南理工大学微信企业号及华南理工大学手机QQ公众号进行集成。 **** > 字符编码:UTF-8 **** ### 手机QQ公众号认证接口 > 备注:在Demo里面的js方法要放到在QQ打开的首页里面。 > 跳转到指定页面时会带上参数code和apitype,如果是QQ访问,apitype=1 **接口地址** URL: https://ums.scut.edu.cn/Wisdom/qq/getAuthentication **请求方式**:`POST` **请求数据类型**:`application/json` **请求包结构体为**: ```json { "code":"" //QQ提供的code } ``` **返回结果** 成功时： ```json { "userId":"", //用户的学工号 (String) "types":["","",""], //用户所在的组的id (JSONArray) "account":"", //用户的中央认证帐号 (String) "result":"success" //(发送成功) } ``` ```json { "result":"no authentication" //(该用户未认证) } ``` 失败时： ```json { "result":"fail" //code错误 } ``` *** ### 微信企业号认证接口 > 备注:在Demo里面的js方法要放到在QQ打开的首页里面。 > 跳转到指定页面时会带上参数code和apitype,如果是微信访问,apitype=2 **请求说明**： 请求方式: POST dataType:"json" Content-Type: application/json **接口地址** URL: https://ums.scut.edu.cn/Wisdom/wx/getAuthentication **请求包结构体为**: ```json { "code":"" //在企业号里面打开页面微信会提供一个code(String) } ``` **返回结果** 成功时： ```json { "userId":"", //用户的学工号 (String) "types":["","",""], //用户所在的组的id (JSONArray) "account":"", //用户的中央认证帐号 (String) "result":"success" //(发送成功) } ``` 失败时： ```json { "result":"fail" // code错误 } ``` *** ### 第三方可推送`服务`与`标签`接口 `服务`和`标签`说明: `服务`只是决定消息从哪个地方发出来,不影响发送到的用户。 `标签`里面的是用户，选择标签就是选择要发送的用户。 **请求说明** 请求方式:POST dataType:"json" Content-Type: application/json ***URL**: https://ums.scut.edu.cn/Wisdom/message/getAuth **请求包结构体为**: ```json { "account":" ", //账号（String）(另外方式告知) "password":" " //密码（String）（另外方式告知） } ``` **返回结果** 成功时： ```json { "services": [ //所能推送的服务 { "serviceId":"", //服务ID（long） "serviceName":"" //服务名称(String) }], "labels": [ //所能推送的标签 { "labelId":"", //标签ID（long） "labelName":"" //标签姓名(String) }] } ``` 失败时： ```json { "result":" wrong account or password " //账号或密码错误 } ``` ### 消息发送接口 **请求说明** 请求方式:POST dataType:"json" Content-Type: application/json **URL**: https://ums.scut.edu.cn/Wisdom/message/thirdAccess **请求包结构体为**: ```json { "account":"", //账号（String）(另外方式告知) "password":"", //密码（String）（另外方式告知）    "serviceId":"", //消息所属服务Id(long) (通过获取权限接口获得) "messages":"", //消息数组(JSONArray) "type":"", //所推送人群标签号(long)（群发的时候传对应标签号，单发就传0） "desAccount":"", //目标用户的学号(String)（针对某个用户推送消息的时候传对应学号，群发时传字符串"0"） "isPushAPP":"", //是否推给APP的标记(int)（0：不推给APP;1：推给APP） "isPushWX":"", //是否推给微信的标记(int)（0：不推给微信;1：推给微信） "isPushQQ":"", //是否推给QQ的标记(int)（0：不推给QQ;1：推给QQ） "isPushSMS":"", //是否推给短信的标记(int)（0：不推给短信;1：推给短信） "isPushMail":"" //是否推给邮箱的标记(int)（0：不推给用户邮箱;1：推给用户邮箱） } ``` > messages中的每个对象都有以下属性： ```json { "title":"", //消息标题（String）（没有就传"",即空字符串） "url":"", //消息所在网页url（String）（没有就传"",即空字符串） "summary":"", //消息简介(String)（纯文本消息就传消息内容） "picture":"" //图片地址(String) （没有就传"",即空字符串） } ``` **返回结果** 成功时： ```json {        "users":[],       //所推送用户的学号数组 (JSONArray) "result":"success" //(发送成功) } ``` 失败时： ```json { "result":"title is too long" //(标题太长(超过16个字)) } ``` ```json { "result":"summary is too long" //(图文最多60字,纯文字最多400字) } ``` ```json { "result":" wrong account or password " //(账号或密码错误) } ``` ```json { "result":"no permission" // (没有权限) } ``` ```json { "result":"no such user" //(单发时学号错误) } ```