HAI-Notice(通知中心)对接文档V2.0-三个一网系统对接

数字海南有限公司

Digital Hainan Co., Ltd

版本修订记录

序号	日期	更改内容	版次	起草或修订人	批准人
1	2024-01-11	第一版	1.0	梁其良	梁其良

范围

本指南提供了统一消息服务接入接口说明，定义了接入接口的调用方式、请求协议、报文格式等内容。

缩略语

JSON：JavaScript Object Notation，是一种轻量级的数据交换格式；

SDK：Software Development Kit，软件开发工具包，提供项目的快速集成；

AK：Access Key，授权码AK，提供接口的安全访问，由接口方提供，使用方妥善保管；

SK：Secret Key，授权码SK，提供接口的安全访问，由接口方提供，使用方妥善保管；

请求协议

通知中心与接入服务通过HTTPS协议交互，字符编码为UTF-8，报文格式为JSON。

调用SDK

通知中心通过统一网关提供服务，在请求时，需要集成Apione SDK，通过统一的调用地址，传递不同的调用参数进行调用。

SDK下载：apione-http-client-hzt-1.0.11-RELEASE.jar

调用示例：

java

/**
 * 接口请求
 *
 * @param contentJson     接口请求Body入参
 * @param ak              分配的AK SK
 * @param sk              我的应用-我申请的功能-对应功能查看sk
 * @param apiName         对应接口名称
 * @param region          接口所属区域 INTRA(政务外网),INTER(政务互联网)
 * @param requestUrl      接口请求地址
 * @return 接口返回数据
 */
public static String invoke(String contentJson,
                                String ak,
                                String sk,
                                String apiName,
                                String region,
                                String requestUrl) {

    ContentBody contentBody = new ContentBody(contentJson);
    
    HttpParameters parameters = HttpParameters.builder()
            .api(apiName)
            .region(region)
            .accessKey(ak)
            .secretKey(sk)
            .contentBody(contentBody)
            .requestUrl(requestUrl)
            .build();

    // 打印入参
    log.info(JSONObject.toJSONString(parameters));
    //请求接口服务，获取response
    HttpReturn call = HttpCaller.getInstance().call(parameters);
    // 打印出参
	log.info(JSONObject.toJSONString(call));
    // 获取接口响应
    return call.getResponse();
}

请求地址

通知中心通过统一网关提供服务，需要请求统一的网关地址，调用不同接口根据接口名称进行区分。

:::tips
生产环境：https://api-one.digitalhainan.com.cn/apione

测试环境：https://api-one-dev.digitalhainan.com.cn/apione

:::

注意：政务网需要开通网络策略：10.111.128.134:80/443，并配置本地HOST

统一接口鉴权

如果接口需要鉴权，需要在header中增加调用凭证（token）信息

字段说明	类型	必填	备注
`Authorization`	`String`	是	用户中心用户凭证（token）信息<br/>示例：<br/>Bearer 4405f5b106d740919b848f728f6f1609

统一响应参数

所有的接口都由统一的响应参数结构进行包装，具体的接口响应参数定义在data字段中

字段说明	类型	必填	备注
`success`	Boolean	是	响应头
`code`	String	否	异常代码
`message`	String	否	异常信息
`data`		否	响应参数

接口说明

统一发送消息

通过此接口可进行海政通“工作通知”消息发送。

:::tips

接口名称（ApiName） ：notice.prd.sendMessage
所属区域（Region） ：INTER
需要鉴权 ：否

:::

请求参数

参数	字段说明	类型	必填	备注
`messages`	发送消息列表	`MessageSendVO`	`Y`	支持批量发送消息

MessageSendVO:

参数	字段说明	类型	必填	备注
`messageTypeCode`	消息类型代码	`String`	`Y`	由三个一网实施人员分配
`channelCode`	渠道代码	`String`	`Y`	由三个一网实施人员配置，如AC000001（需要提供配置内容到实施同学）
`receiverUidType`	接收人标识类型	`String`	`Y`	默认为“USERID”
`receiverUid`	接收人标识	`String`	`Y`	接收人标识主要对应接收人标识类型，填写实际接收用户的标识，仅支持传入海政通用户ID
`attachments`	消息附件列表	`List<String>`	`N`	需要先调用「8.3.消息附件上传接口进行附件上传」，列表内容为接口返回的附件ID<br/>“90aa9cf266d147239a44722f14963f06”, “826cc20dfb3b4484a220e51fcc79d60a”
`variables`	消息模板变量	`List<VariableVO>`	`Y`	字段参考下表
`extras`	额外参数	`JSON`	`N`	目前只有特定渠道支持额外参数<br/>如：<br/>“extras”: {<br/> “linkConfig”: {<br/> “urlType”: “online”,<br/> “appUrlType”: “online”,<br/> “disable”: 0,<br/> “appDisable”: 0,<br/> “url”: “www.baidu.com”,<br/> “appUrl”: “www.baidu.com”<br/> }<br/> }

VariableVO：

参数	字段说明	类型	必填	备注
`key`	变量名称	`String`	`Y`	消息模板变量定义的KEY
`value`	变量值	`String`	`Y`	消息模板变量定义的Value，需要进行实际业务值替换

返回参数

参数	字段说明	类型	必填	备注
`rejects`	消息拒绝发送信息列表	`List<MessageRejectDTO>`	`Y`	拒绝发送消息列表，如果此列表不为空，则表示消息被拒绝发送
`messageIds`	消息ID列表	`List<String>`	`Y`	消息发送成功分配的消息ID，用于消息查询、跟踪

MessageRejectDTO：

参数	字段说明	类型	必填	备注
`rejectCode`	拒绝代码	`String`	`Y`	参考消息拒绝原因清单
`rejectReason`	拒绝原因	`String`	`Y`	参考消息拒绝原因清单
`rejectMessage`	拒绝发送的消息	`Message`	`Y`	参考消息入参

请求示例

可以仅传递部分请求参数。

json

{
    "messages": [
        {
            "messageTypeCode": "TM000023",
            "receiverUid": "111111111111",
            "receiverUidType": "USERID",
            "channelCode": "{海政通DING消息渠道代码}",
            "topicCode": "RXSQ",
            "variables": [
                {
                    "key": "RXR",
                    "value": "111"
                }
            ]
        }
    ]
}

成功响应

:::tips
条件：请求参数合法

判断条件： success=true

:::

json

{
    "success": true,
    "code": null,
    "message": null,
    "data": {
        "rejects": [],
      	"messageIds": ["1381445818959134720"]
    }
}

:::tips
💡 注意，当消息rejects不为空时，则表示请求的消息中存在因消息校验不通过，被服务拒绝发送

:::

json

{
    "success": true,
    "code": null,
    "message": null,
    "data": {
        "rejects": [
            {
              	"rejectCode": "NOTICE-REJECT-1101",
                "rejectReason": "应用代码不能为空",
                "message": {
                      "appCode": "ONECODE",
                      "topicCode": "BSDT",
                      "messageTypeCode": "YYGHCGTZ",
                      "channelCode": "海政通DING消息渠道代码",
                      "receiverUid": "17789770704",
                      "receiverUidType": "USERID",
                      "sourceCode": "HNSRMYY",
                      "variables": [
                          {
                              "key": "JZR",
                              "value": "张三"
                          }
                    ]
                }
            }
        ]
    }
}

错误响应

:::tips
条件：请求数据非法或服务器出现异常。

判断条件： success=false

:::

json

{
  	"success": false,
    "code": "SYSTEM-500"
    "data":null
}

发送Ding消息

通过此接口可进行海政通应用Ding渠道的消息发送。

:::tips

接口名称（ApiName） ：notice.prd.sendDingMessage
所属区域（Region） ：INTER
需要鉴权 ：否

:::

请求参数

参数	字段说明	类型	必填	备注
`messages`	发送消息列表	`MessageSendVO`	`Y`	支持批量发送消息

MessageSendVO:

参数	字段说明	类型	必填	备注
`messageTypeCode`	消息类型代码	`String`	`Y`	传入通知中心创建的模板代码
`channelCode`	渠道代码	`String`	`Y`	传入通知中心DING消息渠道的应用渠道编码
`receiverUidType`	接收人标识类型	`String`	`Y`	默认为“USERID”
`receiverUid`	接收人标识	`String`	`Y`	接收人标识主要对应接收人标识类型，填写实际接收用户的标识，仅支持传入海政通用户ID
`variables`	消息模板变量	`List<VariableVO>`	`Y`	字段参考下表
`extras`	额外参数	`JSON`	`N`	通过以下发送可以动态指定发送人<br/>“extras”:<br/>{<br/>“channel”:{<br/>“senderId”:“XXX”<br/>}<br/>}

VariableVO：

参数	字段说明	类型	必填	备注
`key`	变量名称	`String`	`Y`	消息模板变量定义的KEY
`value`	变量值	`String`	`Y`	消息模板变量定义的Value，需要进行实际业务值替换

返回参数

参数	字段说明	类型	必填	备注
`rejects`	消息拒绝发送信息列表	`List<MessageRejectDTO>`	`Y`	拒绝发送消息列表，如果此列表不为空，则表示消息被拒绝发送
`messageIds`	消息ID列表	`List<String>`	`Y`	消息发送成功分配的消息ID，用于消息查询、跟踪

MessageRejectDTO：

参数	字段说明	类型	必填	备注
`rejectCode`	拒绝代码	`String`	`Y`	参考消息拒绝原因清单
`rejectReason`	拒绝原因	`String`	`Y`	参考消息拒绝原因清单
`rejectMessage`	拒绝发送的消息	`Message`	`Y`	参考消息入参

请求示例

可以仅传递部分请求参数。

json

{
    "messages": [
        {
            "messageTypeCode": "{消息模板代码}",
            "receiverUid": "{海政通用户ID}",
            "receiverUidType": "USERID",
            "channelCode": "{海政通DING消息渠道代码}",
            "variables": [
                {
                    "key": "RXR",
                    "value": "111"
                }
            ]
        }
    ]
}

成功响应

:::tips
条件：请求参数合法

判断条件： success=true

:::

json

{
    "success": true,
    "code": null,
    "message": null,
    "data": {
        "rejects": [],
      	"messageIds": ["1381445818959134720"]
    }
}

:::tips
💡 注意，当消息rejects不为空时，则表示请求的消息中存在因消息校验不通过，被服务拒绝发送

:::

json

{
    "success": true,
    "code": null,
    "message": null,
    "data": {
        "rejects": [
            {
              	"rejectCode": "NOTICE-REJECT-1101",
                "rejectReason": "应用代码不能为空",
                "message": {
                      "appCode": "ONECODE",
                      "topicCode": "BSDT",
                      "messageTypeCode": "YYGHCGTZ",
                      "channelCode": "海政通DING消息渠道代码",
                      "receiverUid": "17789770704",
                      "receiverUidType": "USERID",
                      "sourceCode": "HNSRMYY",
                      "variables": [
                          {
                              "key": "JZR",
                              "value": "张三"
                          }
                    ]
                }
            }
        ]
    }
}

错误响应

:::tips
条件：请求数据非法或服务器出现异常。

判断条件： success=false

:::

json

{
  	"success": false,
    "code": "SYSTEM-500"
    "data":null
}

消息附件上传接口

通过此接口上传消息附件。

:::tips

接口名称（ApiName） ：
- 生产：notice.prd.messageAttachmentUpload
- 测试：notice.dev.messageAttachmentUpload
所属区域（Region） ：INTER
需要鉴权 ：否

:::

请求参数

参数	字段说明	类型	必填	备注
`业务自定义附件Key1`	附件	`String`	`Y`
`业务自定义附件Key2`	附件	`String`	`Y`

备注：参数类型为form-data，上传附件保存7天

返回参数

参数	字段说明	类型	必填
`fileId`	附件ID	`String`	`Y`
`fileKey`	业务自定义附件Key	`String`	`Y`
`fileName`	附件名称	`String`	`Y`

请求示例

必须传递全部请求参数。

java

public void callUpload() {
    String ak = "${AK}";
    String sk = "${SK}";
    String api = "messageAttachmentUploadTest" // 生产为messageAttachmentUpload;
    String region = "INTER";
    String requestUrl = "http://api-one.digitalhainan.com.cn/apione";
    String mediaType = "multipart/form-data";//文档上方请求正文格式

    File file1 = new File("${上传文件路径}");
    byte[] fileByte1 = fileConvertToByteArray(file1);
    File file2 = new File("${上传文件路径}");
    byte[] fileByte2 = fileConvertToByteArray(file2);
    Map<String, AttachFile> attachFileMap = new HashMap<>();
    AttachFile attachFile1 = new AttachFile();
    attachFile1.setFileBytes(fileByte1);
    attachFile1.setFileName(file1.getName());
    attachFile1.setMediaType(MediaType.parse("application/octet-stream"));
    attachFileMap.put("${业务自定义附件Key1}", attachFile1);
    AttachFile attachFile2 = new AttachFile();
    attachFile2.setFileBytes(fileByte2);
    attachFile2.setFileName(file2.getName());
    attachFile2.setMediaType(MediaType.parse("application/octet-stream"));
    attachFileMap.put("${业务自定义附件Key2}", attachFile2);
    String response = invokeUpload(ak, sk, api, region, requestUrl, mediaType, attachFileMap);
}

/**
 * 接口请求
 *
 * @param ak              我的应用-我申请的功能-对应功能查看ak
 * @param sk              我的应用-我申请的功能-对应功能查看sk
 * @param apiName         接口api name
 * @param region          接口请求区域 INTRA(政务外网),INTER(政务互联网)
 * @param requestUrl      接口请求地址
 * @param mediaType       请求正文格式 默认application/json
 * @param attachFileMap   上传文件Map
 * @return 接口返回数据
 */
public static String invokeUpload(String ak,
                                  String sk,
                                  String apiName,
                                  String region,
                                  String requestUrl,
                                  String mediaType,
                                  Map<String, AttachFile> attachFileMap) {
    HttpParameters parameters = HttpParameters.builder()
    .api(apiName)
    .region(region)
    .mediaType(MediaType.parse(mediaType))
    .attachFileMaps(attachFileMap)
    .accessKey(ak)
    .secretKey(sk)
    .requestUrl(requestUrl)
    .build();
    System.out.println(JSONObject.toJSONString(parameters));
    //请求开发服务，获取response
    HttpReturn call = HttpCaller.getInstance().call(parameters);
    System.out.println(call.responseHttpStatus);
    System.out.println(call.getResponse());
    return call.getResponse();
}

成功响应

:::tips
条件：请求参数合法

判断条件： success=true

:::

json

{
	"success": true,
	"code": null,
	"message": null,
	"data": {
		"attachments": [
			{
				"fileId": "00eacecfc37f4972bb94d4ef66cd98c6",
				"fileKey": "file1",
				"fileName": "11.txt"
			},
			{
				"fileId": "fc7b4df8d03f405eab2a4b3df7606d63",
				"fileKey": "file2",
				"fileName": "22.txt"
			}
		]
	}
}

错误响应

:::tips
条件：请求数据非法或服务器出现异常。

判断条件： success=false

:::

json

{
    "success": false,
    "code": "NOTICE-1010",
    "message": "上传附件不能为空",
    "data": null
}

HAI-Notice(通知中心)对接文档V2.0-三个一网系统对接 ​

版本修订记录 ​

范围 ​

缩略语 ​

请求协议 ​

调用SDK ​

请求地址 ​

统一接口鉴权 ​

统一响应参数 ​

接口说明 ​

统一发送消息 ​

请求参数 ​

返回参数 ​

请求示例 ​

成功响应 ​

错误响应 ​

发送Ding消息 ​

请求参数 ​

返回参数 ​

请求示例 ​

成功响应 ​

错误响应 ​

消息附件上传接口 ​

请求参数 ​

返回参数 ​

请求示例 ​

成功响应 ​

错误响应 ​

HAI-Notice(通知中心)对接文档V2.0-三个一网系统对接

版本修订记录

范围

缩略语

请求协议

调用SDK

请求地址

统一接口鉴权

统一响应参数

接口说明

统一发送消息

请求参数

返回参数

请求示例

成功响应

错误响应

发送Ding消息

请求参数

返回参数

请求示例

成功响应

错误响应

消息附件上传接口

请求参数

返回参数

请求示例

成功响应

错误响应