短信网关接口规范(JSON)

version 2.0

 

目录

1. 前言 3

http://sms.it1688.com.cn 3

2. 短信批量发送接口 3

2.1 调用地址 3

2.2 请求包头定义 3

2.3 请求参数 4

2.4 响应结果 4

2.5 请求示例 4

3. 短信一对一发送接口 4

3.1 调用地址 4

3.2 请求包头定义 5

3.3 请求参数 5

3.4 响应结果 5

3.5 请求示例 5

4. 回执状态推送接口 6

4.1 调用地址 6

4.2 推送请求包头定义 6

4.3 请求参数 6

4.4 响应结果 7

4.5 推送请求示例 7

5. 上行回复推送接口 7

5.1 调用地址 7

5.2 推送请求包头定义 7

5.3 请求参数 7

5.4 响应结果 8

5.5 推送请求示例 8

6. 回执状态获取接口 8

6.1 调用地址 8

6.2 请求包头定义 8

6.3 请求参数 8

6.4 响应结果 9

6.5 请求示例 9

7. 上行回复获取接口 10

7.1 调用地址 10

7.2 请求包头定义 10

7.3 请求参数 10

7.4 响应结果 10

7.5 请求示例 11

8. 查询余额接口 11

8.1 调用地址 11

8.2 请求包头定义 12

8.3 请求参数 12

8.4 响应结果 12

8.5 请求示例 12

9. 响应状态码列表 12

 

1. 前言

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

字段命名方式：驼峰法。

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

 

2. 短信批量发送接口

2.1 调用地址

地址：http://send.it1688.com.cn:8001/sms/api/sendMessage

请求方法：POST

2.2 请求包头定义

Accept: application/json

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

2.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码
content	String	是	短信内容
phoneList	[Array]	是	发送手机号码，JSON数组格式。 最大数量不得超过10000个号码。
sendTime	String	否	短信定时发送时间，格式：yyyy-MM-dd HH:mm:ss。 定时时间限制15天以内。
callData	String	否	用户回传数据，最大长度64。 用户若传递此参数将在回执推送时回传给用户。

2.4 响应结果

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

 

2.5 请求示例

批量发送请求：

POST http://send.it1688.com.cn:8001/sms/api/sendMessag

Accept: application/json

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

 

{

userName: "myUserName",

password: "myPassword",

content: "【签名】您的验证码是123456",

phoneList: ["13500000001", "13500000002", "13500000003"]

}

发送响应结果：

{

code: 0,

message: "处理成功",

smsId: 123456

}

3. 短信一对一发送接口

3.1 调用地址

地址：http://send.it1688.com.cn:8001/sms/api/batchSendMessage

请求方法：POST

3.2 请求包头定义

Accept: application/json

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

3.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码
messageList	[Array]	是	数组形式，包含多个JSON对象，对象参数见下表。 每个JSON对象包含短信内容和号码数据，最大1000个号码。
callData	String	否	用户回传数据，最大长度64。 用户若传递此参数将在回执推送时回传给用户。

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

参数名	类型	必填	说明
phone	String	是	发送手机号码
content	String	是	短信内容
extcode	String	否	可选，附带通道扩展码

3.4 响应结果

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

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

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

3.5 请求示例

批量发送请求：

POST http://send.it1688.com.cn:8001/sms/api/batchSendMessage

Accept: application/json

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

 

{

"userName": "myUserName",

"password": "myPassword",

"messageList": [

{

"phone": "13500000001",

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

},

{

"phone": "13500000002",

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

}

]

}

发送响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"code": 0,

"message": "处理成功",

"msgId": 11600001

},

{

"code": 0,

"message": "处理成功",

"msgId": 11600002

}

]

}

4. 回执状态推送接口

4.1 调用地址

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

推送请求方法：POST

4.2 推送请求包头定义

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

4.3 请求参数

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

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

4.4 响应结果

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

4.5 推送请求示例

[

{

"msgId": 11600001,

"phone": "13500000001",

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

"status": "DELIVRD"

},

{

"msgId": 11600002,

"phone": "13500000002",

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

"status": "FAILURE"

}

]

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	否	通道端口号

5.4 响应结果

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

5.5 推送请求示例

[

{

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

"destId": "106203069598",

"phone": "13500000001",

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

},

{

"content": "OK",

"phone": "13500000002",

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

}

]

6. 回执状态获取接口

6.1 调用地址

地址：http://send.it1688.com.cn:8001/sms/api/getReport

请求方法：POST

6.2 请求包头定义

Accept: application/json

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

6.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码

6.4 响应结果

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

每次请求间隔时间不得小于30秒，如果获取条数为2000条表示还有回执未获取，可立即再次请求获取回执。

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

 

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

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

 

6.5 请求示例

状态获取请求：

POST http://send.it1688.com.cn:8001/sms/api/getReport

Accept: application/json

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

 

{

userName: "myUserName",

password: "myPassword"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"data": [

{

"msgId": 11600001,

"phone": "13500000001",

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

"status": "DELIVRD"

},

{

"msgId": 11600002,

"phone": "13500000002",

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

"status": "FAILURE"

}

]

}

7. 上行回复获取接口

7.1 调用地址

地址：http://send.it1688.com.cn:8001/sms/api/getUpstream

请求方法：POST

7.2 请求包头定义

Accept: application/json

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

7.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码

7.4 响应结果

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

每次请求间隔时间不得小于30秒，如果获取条数为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	否	通道端口号

 

7.5 请求示例

状态获取请求：

POST http://send.it1688.com.cn:8001/sms/api/getReport

Accept: application/json

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

 

{

userName: "myUserName",

password: "myPassword"

}

响应结果：

{

"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 调用地址

地址：http://send.it1688.com.cn:8001/sms/api/getBalance

请求方法：POST

8.2 请求包头定义

Accept: application/json

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

8.3 请求参数

参数名	类型	必填	说明
userName	String	是	帐号用户名
password	String	是	帐号密码

8.4 响应结果

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

 

8.5 请求示例

状态获取请求：

POST http://send.it1688.com.cn:8001/sms/api/getBalance

Accept: application/json

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

 

{

userName: "myUserName",

password: "myPassword"

}

响应结果：

{

"code": 0,

"message": "处理成功",

"balance": 967793

}

 

9. 响应状态码列表

状态码	说明
0	处理成功
1	帐号名或密码为空
2	帐号名或密码错误
3	帐号已被锁定
4	此帐号业务未开通
5	帐号余额不足
6	缺少发送号码
7	发送号码数超过10000
8	发送消息内容为空
9	无效的RCS模板ID
10	非法的IP地址，提交来源IP地址与帐号绑定IP不一致
11	24小时发送时间段限制
12	定时发送时间错误或超过15天
13	请求过于频繁，每次请求数据时间间隔为一分钟
14	错误的用户扩展码
50	缺少模板标题
51	缺少模板内容
52	模板内容不全
53	不支持的模板帧类型
54	不支持的文件类型
99	错误的请求JSON字符串
500	系统异常