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

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,AC000002<br/>传入海政通Ding消息渠道代码
`receiverUidType`	接收人标识类型	`String`	`Y`	接收人标识类型主要是定义想要发送的用户的标识类型，比如短信发送的渠道就填手机号相关的标识
`receiverUid`	接收人标识	`String`	`Y`	接收人标识主要对应接收人标识类型，填写实际接收用户的标识，比如短信发送的渠道就填写手机号
`attachments`	消息附件列表	`List<String>`	`N`	需要先调用「7.消息附件上传接口进行附件上传」，列表内容为接口返回的附件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，需要进行实际业务值替换

:::tips
💡 接口入参示例可以在管理端-模板管理中查看模板的【接口入参】，可以快速生成参数

:::

返回参数

参数	字段说明	类型	必填	备注
`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": "PHONE",
            "channelCode": "AC000423",
            "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": "SMS",
                      "receiverUid": "17789770704",
                      "receiverUidType": "PHONE",
                      "sourceCode": "HNSRMYY",
                      "variables": [
                          {
                              "key": "JZR",
                              "value": "张三"
                          }
                    ]
                }
            }
        ]
    }
}

错误响应

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

判断条件： success=false

:::

json

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

发送Ding消息

通过此接口可进行任意渠道的消息发送。

:::tips

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

:::

请求参数

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

MessageSendVO:

参数	字段说明	类型	必填	备注
`messageTypeCode`	消息类型代码	`String`	`Y`	由通知中心应用管理员分配
`channelCode`	渠道代码	`String`	`Y`	由通知中心应用管理员分配，如果需要发送多个渠道，则以英文逗号分隔(,)，如AC000001,AC000002
`receiverUidType`	接收人标识类型	`String`	`Y`	接收人标识类型主要是定义想要发送的用户的标识类型，比如短信发送的渠道就填手机号相关的标识
`receiverUid`	接收人标识	`String`	`Y`	接收人标识主要对应接收人标识类型，填写实际接收用户的标识，比如短信发送的渠道就填写手机号
`attachments`	消息附件列表	`List<String>`	`N`	需要先调用「7.消息附件上传接口进行附件上传」，列表内容为接口返回的附件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，需要进行实际业务值替换

:::tips
💡 接口入参示例可以在管理端-模板管理中查看模板的【接口入参】，可以快速生成参数

:::

返回参数

参数	字段说明	类型	必填	备注
`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": "SMS",
                      "receiverUid": "17789770704",
                      "receiverUidType": "PHONE",
                      "sourceCode": "HNSRMYY",
                      "variables": [
                          {
                              "key": "JZR",
                              "value": "张三"
                          }
                    ]
                }
            }
        ]
    }
}

错误响应

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

判断条件： success=false

:::

json

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

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

版本修订记录 ​

范围 ​

缩略语 ​

请求协议 ​

调用SDK ​

请求地址 ​

统一接口鉴权 ​

统一响应参数 ​

接口说明 ​

统一发送消息 ​

请求参数 ​

返回参数 ​

请求示例 ​

成功响应 ​

错误响应 ​

发送Ding消息 ​

请求参数 ​

返回参数 ​

请求示例 ​

成功响应 ​

错误响应 ​

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

版本修订记录

范围

缩略语

请求协议

调用SDK

请求地址

统一接口鉴权

统一响应参数

接口说明

统一发送消息

请求参数

返回参数

请求示例

成功响应

错误响应

发送Ding消息

请求参数

返回参数

请求示例

成功响应

错误响应