短信网关接口规范(JSON)

version 3.1

 

目录

 

1. 前言

本协议基于HTTPS服务，使用POST请求方式，请求和应答均为JSON格式数据.。

字段命名方式：小驼峰法。

统一请求和响应编码：UTF-8

统一请求Header内容：Content-Type: application/json

sign参数计算规则：多个指定参数值组合成字符串后计算MD5 32位小写结果

假设要求：MD5(userName + timeStamp + MD5(password))

参数：userName(帐号名)=test

           password(帐号密码)=123

           timeStamp(13位毫秒级别时间戳)=1691366400000

  计算：MD5(password)=202cb962ac59075b964b07152d234b70

sign结果：MD5(userName+timeStamp+MD5(password))=3750320ed993bac81b634580ef904c35

 

请注意：

1. 应运营商要求，您在测试短信发送接口的时候也请携带正式签名，否则可能会发送失败

2. 受运营商管控，发送营销短信，必须在短信文本末添加：拒收请回复R

3. 如果您在夜间也有发送短信的需求，请务必报备您发送短信服务器的公网出口IP至我们的客服，否则会触及夜间管控引起短信提交失败

 

 

 

2. 短信批量发送接口

2.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/sendList

请求方法：POST

2.2 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

2.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
content	String	是	短信内容
phoneList	[Array]	是	发送手机号码，JSON数组格式。 最大数量不得超过10000个号码，系统将自动去除重复号码。
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))
sendTime	String	否	短信定时发送时间，格式：yyyy-MM-dd HH:mm:ss。 定时时间限制15天以内。
extCode	String	否	可选，附带通道扩展码
callData	String	否	用户回传数据，最大长度64。 用户若传递此参数将在回执推送时回传给用户。
custom	String	否	批次统计使用

2.4 响应结果

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
messageCount	Number	计费条数
msgId	Number	当code=0时，系统返回唯一消息Id

 

2.5 请求示例

批量发送请求：

POST https://v3.it1688.com.cn:7000/sms/sign/sendList

Accept: application/json

Content-Type: application/json;charset=utf-8

{

"userName": "MyUserName",

  "content": "【签名】短信内容",

"phoneList": ["188xxxxxxxx","189xxxxxxxx"],

"timeStamp": 1596254400000,

"sign": "43fcac8cf3079f86f2f8409158c51ff6",

  "sendTime": "可选的发送时间",

  "extCode": “可选的通道扩展码”,

 "callData": "这是测试回传参数",

  "custom": "这是自定义参数"

}

 

 

发送响应结果：

{

"code": "0",

"message": "处理成功",

"messageCount": 2,

"msgId": 123456

}

3. 短信一对一发送接口

3.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/send

请求方法：POST

3.2 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

3.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
messageList	[Array]	是	数组形式，包含多个JSON对象，对象参数见下表。 每个JSON对象包含短信内容和号码数据，最大1000个号码。
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

messageList由多个JSON对象构成的JSON数组，具体参数列表：

参数名	类型	必填	说明
phone	String	是	发送手机号码
content	String	是	短信内容
extCode	String	否	可选，附带通道扩展码
callData	String	否	用户回传数据，最大长度64。 用户若传递此参数将在回执推送时回传给用户。
custom	String	否	批次统计使用

3.4 响应结果

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	当code=0时，系统返回处理结果的数组对象集合，对象参数见下表。

data由多个JSON对象构成的JSON数组，具体参数列表：

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
msgId	Number	当code=0时，系统返回唯一消息Id
phone	String	发送手机号码
messageCount	Number	该号码的计费条数

3.5 请求示例

批量发送请求：

POST  https://v3.it1688.com.cn:7000/sms/sign/send

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "myUserName",

"sign": "43fcac8cf3079f86f2f8409158c51ff6",

"timeStamp": 1596254400000,

"messageList": [

{

"phone": "13500000001",

"content" : "【签名】尊敬的张先生，本次共消费211.45元",

"callData": "可选的测试回传数据",

"custom": "可选的测试自定义参数",

"extcode": "可选的附带通道扩展码"

},

{

"phone": "13500000002",

"content" : "【签名】尊敬的林女士，本次共消费78.00元",

"callData": "可选的测试回传数据",

"custom": "可选的测试自定义参数",

"extcode": "可选的附带通道扩展码"

}

]

}

发送响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"code": 0,

"msg": "处理成功",

"msgId": 11600001,

"messageCount": 1,

"phone": "13500000001"

},

{

"code": 0,

"msg": "处理成功",

"msgId": 11600002,

"messageCount": 1,

"phone": "13500000002"

}

]

}

4. 回执状态推送接口

4.1 调用地址

地址：客户需向我司提交接收回执状态地址，由平台主动推送回执状态数据

推送请求方法：POST

4.2 推送请求包头定义

Content-Type: application/json;charset=utf-8

4.3 请求参数

推送数据为JSON数组形式，每次推送不大于2000条。推送字段如下：

参数名	类型	必填	说明
msgId	Number	是	消息id，对应发送成功时系统响应的msgId
phone	String	是	手机号码
status	String	是	回执状态，DELIVRD成功，其他失败
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
messageCount	Number	是	消息计费条数
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

4.4 响应结果

正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式

4.5 推送请求示例

[

{

"msgId": 11600001,

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32",

"status": "DELIVRD",

"messageCount": 1,

"callData": "测试回传数据"

},

{

"msgId": 11600002,

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32",

"status": "SMS:015",

"messageCount": 1,

"callData": "测试回传数据"

}

]

5. 上行回复推送接口

5.1 调用地址

地址：客户需向我司提交接收上行回复地址，由平台主动推送上行回复数据

推送请求方法：POST

5.2 推送请求包头定义

Content-Type: application/json;charset=utf-8

5.3 请求参数

推送数据为JSON数组形式，每次推送不大于2000条。推送字段如下：

参数名	类型	必填	说明
content	String	是	上行回复内容
phone	String	是	手机号码
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
destId	String	否	通道端口号
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

5.4 响应结果

正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式

5.5 推送请求示例

[

{

"content": "好的, 已收到",

"destId": "106203069598",

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32",

"callData": "测试回传数据1"

},

{

"content": "OK",

"phone": "13500000002",

"destId": "106203069599",

"receiveTime": "2020-06-09 11:10:32",

"callData": "测试回传数据2"

}

]

6. 回执状态获取接口

6.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/getReport

请求方法：POST

6.2 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

6.3 请求参数

每次请求间隔时间不得小于30秒。

参数名	类型	必填	说明
userName	String	是	帐号用户名
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

6.4 响应结果

响应数据为JSON形式，每次获取不大于2000条，已获取的数据不会被再次获取到。

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	获取的回执列表。JSON数组形式，具体字段如下

 

data包含推送字段如下（与4.4推送参数一致）

参数名	类型	必填	说明
msgId	Number	是	消息id，对应发送成功时系统响应的msgId
phone	String	是	手机号码
status	String	是	回执状态，DELIVRD成功，其他失败
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
messageCount	Number	是	消息计费条数
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

 

6.5 请求示例

状态获取请求：

POST  https://v3.it1688.com.cn:7000/sms/sign/getReport

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "test",

"timeStamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"msg": "处理成功",

"data": [

{

"msgId": 11600001,

"phone": "13500000001",

"messageCount": 1,

"receiveTime": "2020-06-09 11:10:32",

"status": "DELIVRD"

},

{

"msgId": 11600002,

"phone": "13500000002",

"messageCount": 1,

"receiveTime": "2020-06-09 11:10:32",

"status": "FAILURE"

}

]

}

7. 上行回复获取接口

7.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/getUpstream

请求方法：POST

7.2 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

7.3 请求参数

每次请求间隔时间不得小于30秒

参数名	类型	必填	说明
userName	String	是	帐号用户名
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

7.4 响应结果

响应数据为JSON形式，每次获取不大于2000条，已获取的数据不会被再次获取到。

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
data	[Array]	获取的回执列表。JSON数组形式，具体字段如下

 

data包含推送字段如下（与5.4推送参数一致）

参数名	类型	必填	说明
content	String	是	上行回复内容
phone	String	是	手机号码
receiveTime	String	是	回执时间，格式：yyyy-MM-dd HH:mm:ss
destId	String	否	通道端口号
callData	String	否	用户回传数据，如果提交时有传递此参数将原样推送带回

 

7.5 请求示例

状态获取请求：

POST  https://v3.it1688.com.cn:7000/sms/sign/getUpstream

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "test",

"timeStamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"content": "好的, 已收到",

"destId": "106203069598",

"phone": "13500000001",

"receiveTime": "2020-06-09 11:10:32"

},

{

"content": "OK",

"phone": "13500000002",

"receiveTime": "2020-06-09 11:10:32"

}

]

}

8. 查询余额接口

8.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/getBalance

请求方法：POST

8.2 请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

8.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

8.4 响应结果

参数名	类型	说明
code	Integer	处理结果，0为成功，其他失败，详细参考响应状态码
message	String	处理结果描述
balance	Long	当code=0时，系统返回帐号短信余额

 

8.5 请求示例

状态获取请求：

POST  https://v3.it1688.com.cn:7000/sms/sign/getBalance

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "test",

"timeStamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"balance": 967793

}

 

9. 删除定时短信接口

9.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/deleteTimingMessages

请求方法：POST

9.2请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

9.3请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
timingId	String	是	需要删除的短信ID
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

9.4响应结果

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
msg	String	处理结果描述

9.5请求示例

状态获取请求：

POST https://v3.it1688.com.cn:7000/sms/sign/deleteTimingMessages

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "myUserName",

"password": "myPassword",

"timeStamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf",

"timingId": "需要删除的短信ID"

}

响应结果：

{

"code": 0,

"msg": "处理成功"

}

10. 获取定时短信接口

10.1 调用地址

地址：https://v3.it1688.com.cn:7000/sms/sign/getTimingMessages

请求方法：POST

10.2请求包头定义

Accept: application/json

Content-Type: application/json;charset=utf-8

10.3请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码
timeStamp	Long	是	当前时间戳，精确到毫秒。 例如2020年8月1日12:00:00 时间戳为：1596254400000
sign	String	是	由以下参数值组合成字符串并计算MD5值，参考详细规则 计算：MD5(userName + timeStamp + MD5(password))

10.4响应结果

参数名	类型	说明
code	String	处理结果，0为成功，其他失败，详细参考响应状态码
msg	String	处理结果描述
data	[Array]	当code=0时，系统返回处理结果的数组对象集合，对象参数见下表。

data包含推送字段如下

参数名	类型	必填	说明
timingId	String	是	短信ID
messageContent	String	是	短信内容
sendTime	String	是	定时发送时间，格式：yyyy-MM-dd HH:mm:ss
phoneCount	String	否	号码数

 

10.5请求示例

状态获取请求：

POST https://v3.it1688.com.cn:7000/sms/sign/getTimingMessages

Accept: application/json

Content-Type: application/json;charset=utf-8

 

{

"userName": "myUserName",

"password": "myPassword",

"timeStamp": 1596254400000,

"sign": "e315cf297826abdeb2092cc57f29f0bf"

 

}

响应结果：

{

"code": 0,

"msg": "处理成功",

"data": [

      {

"timingId": "xxxxxxxxxx01",

"MessageContent": ""【签名】尊敬的张先生，本次共消费211.45元"",

"sendTime": "2020-06-09 11:10:32",

"PhoneCount": "1"

},

 {

"timingId": "xxxxxxxxxx02",

"MessageContent": ""【签名】尊敬的李先生，本次共消费584.69元"",

"sendTime": "2020-06-09 11:50:42",

"PhoneCount": "3"

}

 

]

}

 

 

11. 响应状态码列表

状态码	说明
0	处理成功
1	帐号名或密码为空
2	账号对应用户不存在
3	帐号已被锁定
4	此帐号业务未开通
5	帐号余额不足
6	缺少发送号码
7	发送号码数超过10000
8	发送消息内容为空
10	非法的IP地址，提交来源IP地址与帐号绑定IP不一致
11	24小时发送时间段限制
12	定时发送时间错误或超过15天
13	请求过于频繁，每次请求数据时间间隔为一分钟
14	错误的用户扩展码
50	缺少定时短信ID参数
51	定时短信ID参数格式不正确
52	该定时短信已发送或不存在
60	账号未配置后缀扩展
61	模板ID格式不正确或不存在
62	模板未生效
63	模板参数不符
99	错误的请求JSON字符串
500	系统异常