国际富信 API 接口规范

1 文档说明

1.1 文档目的

该文档是面向第三方客户提供国际富信消息发送的相关API 接口调用规范。

1.2 适用范围

本文档适用于国际富信客户侧业务系统相关富信发送业务场景所需的接口调用。

1.3 参考文档

超文本传送协议(Hypertext Transfer Protocol) -- HTTP/1.1---RFC 2616

HTTP 鉴权(HTTP Authentication: Basic and Digest Access Authentication)--RFC2617

Constrained RESTful Environments (CoRE) Link Format –RFC6690

2 协议规范

国际富信服务接口主要包含：认证服务、富信网关和状态通知三类服务接口，本接口规范遵循RESTful API 标准，采用当前流行的微服务2.0 技术架构，以HTTP/HTTPS 协议方式对外提供服务接口。接口遵循的RESTful 架构也是目前较为流行的一种互联网软件架构，它具有结构清晰、符合标准、易于理解、扩展方便等优点，从而被得到广泛使用。

2.1 协议说明

RESTFul API 接口常见的Body 格式有三种：

application/json

JSON 报文消息格式。

application/x-www-form-urlencoded

form 表单提交的消息格式。

multipart/form-data

多文件上传的消息格式。

国际富信发送服务目前只支持application/json 的形式。

2.2 接口约定
接口中的普通时间格式均约定为yyyy-MM-dd HH:mm:ss格式,采用24 小时制，如2021-09- 10 18:52:34

请求参数中时间戳格式均为14位yyyyMMddHHmmss日期格式，采用24小时制，如20131014120000。

接口请求和响应参数名称均区分大小写，接口传输过程中时应注意。

HTTP 协议，无特殊说明，实体内容及响应内容全部采用JSON 格式进行数据描述，并采用UTF-8 编码。

2.3 富信接口规范

国际富信客户API 接口主要分为：富信消息、状态通知两类服务接口。其中富信消息接口由国际富信平台提供，状态通知接口由客户侧系统提供。

2.3.1 接口地址

生产环境：

http://rbm.int-montnets.com:8081/{service}/openapi/{func}

测试环境：

http://test.int-montnets.com:8081/{service}/openapi/{func}

其中：

service:服务主目录，可动态配置，也可用于微服务部署模式对应的服务名称。

openapi：接口地址中规定的中间路径

{func}：接口所定义的业务路由路径或接口指令名称。

2.3.2 消息格式

接口消息格式分HTTP 头、请求消息、响应消息三方面进行说明，其中响应消息统一为当前主流的 JSON 包体报文格式。

2.3.3 HTTP 消息头

在进行HTTP/HTTPS 请求时，必须根据本接口协议规范进行HTTP 头标记信息的填充。该文档此处仅对HTTP 协议扩展头标记进行简单说明：

HTTP 头	选项	说明
ContentType	必填	内容格式信息与编码。这里规定为 application/json 表示传输内容为文本 JSON 格式，字符编码统一为 UTF-8 格式。未填写情况下服务接口默认以URL 方式进行
		解码。
User-Agent	可选	用户代理类型，一般用于标识浏览器类型版本信息。这里仅用于标识接口请求来源类型
Token	可选	接口访问令牌，仅用于令牌认证模式，富信发送服务接口支持令牌认证和签名认证两种方式，由富信发送服务配置决定。前期仅考虑签名认证模式。采用签名认证模式该参数可忽略不填。

2.3.4 请求消息

HTTP 消息头中 Content-Type 类型不同，请求消息格式不同。具体可参见第 4 章节接口定义部分。其中

当 Content-Type 为 application/json 时请求消息示例：

 {
"custom_id":"20210722124041000001",
"account":"JK0130",
"sign":"016edd3f94405876bd303449724935a4",
"req_time":"2021-07-22 12:40:41",
"timezone":"+0800"
}

2.3.5 响应消息

服务接口响应数据包均为JSON 格式。响应消息内容分为逻辑上分为响应消息头和消息体两部分，其中消息体为动态格式。

响应消息头部分：包含code、desc 元素标记

code ：响应状态码，仅用于表示接口调用结果情况的标识，不代表真正的业务执行结果。业务执行的结果依赖于data 包体中的相关定义来做标识。code 状态码的定义延续HTTP 请求状态码的定义，但用法有所差异。HTTP 状态码是协议层面的，code 是接口调用层面的，其中0 为成功，其它为失败原因代码，具体请参见附录中的状态码定义。

desc ：响应提示信息，比如请求失败的具体原因描述等。

响应消息内容部分：包含响应内容元素标记

当code 为0 时，根据具体的报文说明处理相关的字段信息；

当code 非 0 时，则无须关注其他字段的内容

响应示例：

 {
"code":0,
"desc":"ok",
"file_id":"578106112816451584",
"url":"http://file.io/rc/578106112816451584"
}

2.4 安全签名机制

安全签名机制是面向对签名认证模式的一种安全签权算法，本文仅针对接口定义章节的相关接口有效，具体规则如下：

接口请求中的参数除 sign 外其它已填参数以参数名作为 key 进行 ascii 字母顺序排序，然后将值(json 对象、 json 数组不参与拼接) 直接进行拼接开头加上 ”{appid}”变量值末尾加上”{apikey}”值进行拼接，将拼接结果进行 MD5 摘要得到签名信息。

接口生成签名示例如下：

account	=”JK0100”
custom_id	=”2021072212000000100001”
req_time	=”2021-07-22 12:00:00”
message_id	=”6853212118188288
msisdn	=”85212341234”

//实际接口参数排序进行拼接：

String parametersStr=”JK0100”

+”2021072212000000100001”

+”6853212118188288”

+”85212341234”

+”2021-07-22 12:00:00”

……

);

//生成安全签名信息：

String sign=MD5( appid+parametersStr+apikey);

注意：

1、实际使用中请严格控制 appid、apikey 的泄漏，避免造成不必要的损失。

2、appid 和 apikey 信息可以使用企业开通的管理员帐号登录 web 控制台，打开安全中心查
看。如下图所示：

3 接口定义

遵照接口规范定义对各服务接口进行具体定义，其中 JSON响应消息仅对消息体data元素进行描述说明。

3.1 富信消息

3.1.1 模板消息发送接口

请求地址

/grms/openapi/rmssend

功能说明

模板消息发送接口。主要用于富信控制台和客户侧系统调用，具有高频次、大

流量调用特性。

认证方式

签名认证

输入参数：

参数名称	类型	说明
account	string	发送签权帐号，必填，接口调用的 API 帐号。
sender	string	SENDERID，必填，自动检测字母-数字，是否携带国家码
msisdn	string	目标手机号码，含国家码，必填。
check_dnc	integer	是否拒收登记册检查，必填 0-不过拒收登记册检查 1-需要拒收登记册检查
title	string	富信主题，必填，

		实际展示以该字段展示富信主题。
template_id	string	模板编号，非必填。当未填写模板编号时，则按顺序排列参数拼接内容进行发送。
tag	string	标签，非必填，用于标注业务场景、类型或用途
parameter	jsonarray	参数对象数组，非必填， template_id 不存在时，参数个数限制在 8 个以内。其格式参见下方 parameter 对象格式说明
send_type	integer	发送方式： 1-即时发送 2-定时发送
send_time	string	定时发送时间，非必填，格式： yyyy-MM-dd HH:mm:ss 1) send_type=1，即时发送时无须填写； 2) send_type=2，定时发送时必须填写；若定时发送时间小于服务器时间或未填写该字段，消息将立即发送，其他情况按填充时间进行定时发送。若定时发送时间大于当前不足 1 分钟，则按及时发送方式进行发送。
send_timezone	string	时区，选填，格式： +HHmm，默认+0800
custom_id	string	客户请求方唯一流水号，选填。限定 64 位 ASCII 字符。
sign	string	签名信息，签名方式必填，具体可参见 2.5 安全签名机制

parameter 对象格式

参数名称	类型	说明
name	string	参数名，必填，用于匹配模板中参数占位符。
type	integer	参数类型，必填 1-文本 2- 图片 3-音频 4-视频
suffix	string	文件扩展名文本： txt 图片： jpg/jpeg、gif、png 音频： mp3 、acc 视频： mp4(必须是 H.264 编码)
value	string	参数值：

1)当 type 为 1 时， value 值内容有效，即实际文本内容； 2) 当 type 非 1 时，其值内容为图片或音频或视频进行 base64 编码的字串，非必填。

3)如 url 非空情况下将优先使用url 指示的地址进行下载。

url

string

参数资源地址，非必填，若填写，则从该地址下载参数值进

行模板拼接组装。

注意事项：

1、所有参数总和加上模板大小不超过 1.9MB

2 、为确保视频内容清晰度，建议视频播放时间不超过 33 秒

3 、请求参数模版编号为空的情况，适用于无须创建模版直接通过参数进行拼接模版的情况，建议慎用。

输出参数：

参数名称	类型	说明
code	integer	消息接收状态 0-成功其他-失败，见错误码表
desc	string	描述信息
message_id	string	消息编号
custom_id	string	调用方请求流水号，将请求中 custom_id 原值返回；请求报文未填写时，使用 message_id 填充

报文示例：

CURL 请求示例：
curl http://host:port/grms/openapi/rmssend -s -H"Content-Type:application/json" -d

 '{
"account": "USR007",
"custom_id": "1634113718787",
"sender": "MontRMS",
"msisdn": "852xxxxx",
"check_dnc": 0,
"template_id": "",
"tag": "",
"title": "Montnets RMS",
"sign": "xxxxxxxxxxxxxxx",
"parameter": [
{
"name": "1.png",
"url": "1.png.url",
"type": 2,
"suffix": "png"
},
{
"name": "1.mp4",
"url": "1.mp4.url",
"type": 4,
"suffix": "mp4"
},
{
"name": "1.txt",
"value": "Max number of connections to a single broker that is kept in the pool",
"type": 1,
"suffix": "txt"
}
],
"send_time": "",
"send_timezone": "+0800",
"send_type": 1
}'

响应示例：

 {
"code": 0,
"desc": "ok",
"message_id": "6868856361645170690",
"custom_id": "1634113718787"
}

3.1.2 文件上传接口

请求地址	/grms/openapi/fileupload
功能说明	富信模板参数文件上传接口。
认证方式	签名认证

输入参数：

参数名称	类型	说明
account	string	消息发送用户 ID 必填
md5	string	文件 md5 摘要
name	string	文件名称
mime	string	ext/richtext text/html image/tiff image/jpeg image/gif audio/mid video/mpeg application/octet-stream
value	string	文件内容 base64
sign	string	签名信息，具体可参见 2.5 安全签名机制

输出参数：

参数名称	类型	说明
code	integer	文件接收状态 0-成功其他-失败，见错误码表
desc	string	描述信息
file_id	string	文件编号
url	string	文件下载地址

CURL 请求示例：

curl http://HOST:PORT/grms/openapi/fileupload-s -H"Content-Type:application/json" -d

 '{"name":"curltest.txt", "mime":"text/plain","value":"Y3VybCBodHRwOi8vMTkyLjE2OS4yLjE4OTo4MDgzL3JzYy9vcGV uYXBpL3IvdXBsb2FkIC1kIC1IQ29udGVudC1UeXBlOmFwcGxpY2F0aW9uL2pzb24geyJuYW1lIjoiY3V ybHRlc3QudHh0IiwgIm1pbWUiOiJ0ZXh0L3BsYWluIiwidmFsdWUiOiIiLCJzaWduIjoieHgiLCJtZDU iOiJ4eHgifQo=","sign":"xx","md5":"xxx"}'

响应示例：

 {
"file_id": "6868858389289164868",
"url": "http://host:port/6868858389289164868",
"code": 0,
"desc": "ok"
}

3.2 状态通知
回调给客户侧的状态通知接口，该部分接口由客户侧实现，用于接收消息发送状态、下载状态的回调通知。如客户侧不提供服务接口，视为不接收状态报告。

3.2.1 通知消息状态报告接口

请求地址

由客户侧提供

功能说明

推送富信消息发送的状态报告信息到客户侧，状态报告反映了富信短信通知消息是否有送达到用户手机终端。状态报告推送失败会进行重推。

重推机制：推送失败后会按指定时间间隔进行重推；最多重推指定次数后若不成功则丢弃。

时间间隔默认 3 分钟；最大重推次数默认 5 次；可以根据实际情况进行调整。

认证方式

签名认证

输入参数：

参数名称

类型

说明

account

string

用户账号(同 3.2.1 章节模板消息发送接口请求参数中的账

号)

custom_id

string

调用侧请求方流水号；若发送时未提交，填写 message_id；限定 64 位 ASCII 字符。

message_id	string	消息流水号
sender	string	最终手机展示的 sender ID。
msisdn	string	手机号码，含国家码，必填。
recv_time	string	状态报告返回时间： YYYY-MM-DD HH:MM:SS
recv_timezone	string	时区，选填，格式： +HHmm，默认+0800
state	integer	接收状态： 0：失败 1：成功 2：待返(查询可见)
sign	string	签名信息，具体可参见 2.5 安全签名机制

输出参数：

参数名称

类型

说明

code

integer

文件接收状态

0- 失败

1- 成功

3.2.2 消息下载状态报告接口

请求地址

由客户侧提供

功能说明

推送下载状态报告到客户侧系统。下载状态报告反映了富信模版消息是否被

终端用户点击下载或自动下载过。其失败重推机制同 3.3.1 章节。

认证方式

签名认证

输入参数：

参数名称	类型	说明
account	string	用户账号(同 3.2.1 章节模板消息发送接口请求参数中的账号)
custom_id	string	调用侧请求方流水号，选填。限定 64 位 ASCII 字符。
message_id	string	消息流水号
sender	string	enderID
msisdn	string	手机号码(含国家码)
download_time	string	下载时间，非必填，超时未下载时不填写。格式如：yyyy- MM-dd HH:mm:ss

download

_timezone

string

时区，选填，格式： +HHmm，默认+0800

download_state

integer

下载状态

0：失败

1：成功

2：待返(查询可见)

sign

string

签名信息，具体可参见 2.5 安全签名机制

输出参数：

参数名称

类型

说明

code

integer

文件接收状态

0-失败

1-成功

4 附录说明

4.1 代码定义

4.1.1 数据类型

类型	说明
string	字串型
integer	整型
double	浮点型
long	长整型
JSONObject	JSON 对象
JSONArray	JSON 数组

4.1.2 响应代码

这里主要针对 2.3.5 响应消息头中的 code 元素所对应的状态码进行说明。

状态码及范围

说明

300~399

通信协议层相关校验的状态码范围，该错误代码范围内的请求记录不产生入库

记录。避免非法无效请求产生大量无效请求。一般用于调用侧或存在后向服务

	请求的场景。
400~410	接口请求安全权限认证非法的错误码范围，该错误代码情况下，请求消息不做入库记录。
500~510	网络错误代码范围，主要为上下游调用时所产生的相关网络错误代码。
1000-99999	该范围内的错误代码为富信发送务业务处理逻辑过程中产生的错误代码。

如下仅对与富信发送业务相关错误代码进行具体定义：

错误代码	说明	排查方法
10001	请求头错误	应正确填写 Content-Type:application/json
10002	请求数据 Body 错误	请求数据错误,非法的 JSON 格式,参数与约定协议不符等
10003	请求必填字段缺失	请求参数字段缺失,请确认所有必填参数是否填写
10004	请求必填字段值类型错误	请求必填字段值类型错误
10005	签名错误	请求携带的签名校验失败
20003	企业发送限量拦截发送超限	富信发送量超限,联系管理员充值
20004	sender 不可用	请求携带的 SENDER 非法不可用
20005	用户不存在	请求发起者用户信息不存在
20006	号码非法	号码非法请检查确认是否正确携带国家码, 号码长度最长 21 位
20007	任务被取消	定时任务被取消
20008	拒收登记拦截	目标号码在拒收登记册内拦截
-	其他错误码	请联系服务提供者核查确认