version 1.1
版本修订历史 |
||
版本 |
日期 |
说明 |
1.0 |
2020-06-09 |
接口规范与参数定义 |
1.1 |
2021-01-01 |
增强接口调用安全性 |
本协议基于HTTP服务,使用POST请求方式,请求和应答均为JSON格式数据.。
字段命名方式:驼峰法。
统一请求和响应编码:UTF-8
统一请求Header内容:Content-Type: application/json
sign参数计算规则:多个指定参数值组合成字符串后计算MD5 32位小写结果
假设要求:MD5(userName + content + timestamp + MD5(password))
参数:userName(帐号名)=test
password(帐号密码)=123
content=测试内容
timestamp=1596254400000
计算:MD5(password)=202cb962ac59075b964b07152d234b70
组合字符串:test测试内容1596254400000202cb962ac59075b964b07152d234b70
sign结果:MD5(组合字符串)=92f4abe1a56cac716bc790c93149a3ae
地址:http://send.it1688.com.cn:8001/sms/api/sendMessage
请求方法:POST
Accept: application/json
Content-Type: application/json;charset=utf-8
参数名 |
类型 |
必填 |
说明 |
userName |
String |
是 |
帐号用户名 |
content |
String |
是 |
短信内容 |
phoneList |
[Array] |
是 |
发送手机号码,JSON数组格式。 最大数量不得超过10000个号码,系统将自动去除重复号码。 |
timestamp |
Long |
是 |
当前时间戳,精确到毫秒。 例如2020年8月1日12:00:00 时间戳为:1596254400000 |
sign |
String |
是 |
由以下参数值组合成字符串并计算MD5值,参考详细规则 计算:MD5(userName + content + timestamp + MD5(password)) |
sendTime |
String |
否 |
短信定时发送时间,格式:yyyy-MM-dd HH:mm:ss。 定时时间限制15天以内。 |
extcode |
String |
否 |
可选,附带通道扩展码 |
callData |
String |
否 |
用户回传数据,最大长度64。 用户若传递此参数将在回执推送时回传给用户。 |
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,0为成功,其他失败,详细参考响应状态码 |
message |
String |
处理结果描述 |
msgId |
Long |
当code=0时,系统返回唯一消息Id |
批量发送请求:
POST http://send.it1688.com.cn:8001/sms/api/sendMessage
Accept: application/json
Content-Type: application/json;charset=utf-8
{
"userName": "test",
"content": "【签名】您的验证码是123456",
"phoneList": ["13500000001", "13500000002", "13500000003"],
"timestamp": 1596254400000,
"sign": "43fcac8cf3079f86f2f8409158c51ff6"
}
发送响应结果:
{
"code": 0,
"message": "处理成功",
"smsId": 123456
}
地址:http://send.it1688.com.cn:8001/sms/api/sendMessageOne
请求方法:POST
Accept: application/json
Content-Type: application/json;charset=utf-8
参数名 |
类型 |
必填 |
说明 |
userName |
String |
是 |
帐号用户名 |
messageList |
[Array] |
是 |
数组形式,包含多个JSON对象,对象参数见下表。 每个JSON对象包含短信内容和号码数据,最大1000个号码。 |
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天以内。 |
messageList由多个JSON对象构成的JSON数组,具体参数列表:
参数名 |
类型 |
必填 |
说明 |
phone |
String |
是 |
发送手机号码 |
content |
String |
是 |
短信内容 |
extcode |
String |
否 |
可选,附带通道扩展码 |
callData |
String |
否 |
用户回传数据,最大长度64。 用户若传递此参数将在回执推送时回传给用户。 |
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,0为成功,其他失败,详细参考响应状态码 |
message |
String |
处理结果描述 |
data |
[Array] |
当code=0时,系统返回处理结果的数组对象集合,对象参数见下表。 |
data由多个JSON对象构成的JSON数组,具体参数列表:
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,0为成功,其他失败,详细参考响应状态码 |
message |
String |
处理结果描述 |
msgId |
Long |
当code=0时,系统返回唯一消息Id |
phone |
String |
发送手机号码 |
批量发送请求:
POST http://send.it1688.com.cn:8001/sms/api/sendMessageOne
Accept: application/json
Content-Type: application/json;charset=utf-8
{
"userName": "test",
"messageList": [
{
"phone": "13500000001",
"content" : "【签名】尊敬的张先生,本次共消费211.45元"
},
{
"phone": "13500000002",
"content" : "【签名】尊敬的林女士,本次共消费78.00元"
}
],
"timestamp": 1596254400000,
"sign": "e315cf297826abdeb2092cc57f29f0bf"
}
发送响应结果:
{
"code": 0,
"message": "处理成功",
"data": [
{
"code": 0,
"message": "处理成功",
"msgId": 11600001,
"phone": "13500000001"
},
{
"code": 0,
"message": "处理成功",
"msgId": 11600002,
"phone": "13500000002"
}
]
}
地址:客户需向我司提交接收回执状态地址,由平台主动推送回执状态数据
推送请求方法:POST
Content-Type: application/json;charset=utf-8
推送数据为JSON数组形式,每次推送不大于2000条。推送字段如下:
参数名 |
类型 |
必填 |
说明 |
msgId |
Long |
是 |
消息id,对应发送成功时系统响应的msgId |
phone |
String |
是 |
手机号码 |
status |
String |
是 |
回执状态,DELIVRD成功,其他失败 |
receiveTime |
String |
是 |
回执时间,格式:yyyy-MM-dd HH:mm:ss |
callData |
String |
否 |
用户回传数据,如果提交时有传递此参数将原样推送带回 |
正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式
[
{
"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"
}
]
地址:客户需向我司提交接收上行回复地址,由平台主动推送上行回复数据
推送请求方法:POST
Content-Type: application/json;charset=utf-8
推送数据为JSON数组形式,每次推送不大于2000条。推送字段如下:
参数名 |
类型 |
必填 |
说明 |
content |
String |
是 |
上行回复内容 |
phone |
String |
是 |
手机号码 |
receiveTime |
String |
是 |
回执时间,格式:yyyy-MM-dd HH:mm:ss |
destId |
String |
否 |
通道端口号 |
callData |
String |
否 |
用户回传数据,如果提交时有传递此参数将原样推送带回 |
正常响应HTTP状态码200即可。非200状态码将转换为客户获取形式
[
{
"content": "好的, 已收到",
"destId": "106203069598",
"phone": "13500000001",
"receiveTime": "2020-06-09 11:10:32"
},
{
"content": "OK",
"phone": "13500000002",
"receiveTime": "2020-06-09 11:10:32"
}
]
地址:http://send.it1688.com.cn:8001/sms/api/getReport
请求方法:POST
Accept: application/json
Content-Type: application/json;charset=utf-8
每次请求间隔时间不得小于30秒,如果获取条数为2000条表示还有回执未获取,可立即再次请求获取回执。
参数名 |
类型 |
必填 |
说明 |
userName |
String |
是 |
帐号用户名 |
timestamp |
Long |
是 |
当前时间戳,精确到毫秒。 例如2020年8月1日12:00:00 时间戳为:1596254400000 |
sign |
String |
是 |
由以下参数值组合成字符串并计算MD5值,参考详细规则 计算:MD5(userName + timestamp + MD5(password)) |
响应数据为JSON形式,每次获取不大于2000条,已获取的数据不会被再次获取到。
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,0为成功,其他失败,详细参考响应状态码 |
message |
String |
处理结果描述 |
data |
[Array] |
获取的回执列表。JSON数组形式,具体字段如下 |
data包含推送字段如下(与4.4推送参数一致)
参数名 |
类型 |
必填 |
说明 |
msgId |
Long |
是 |
消息id,对应发送成功时系统响应的msgId |
phone |
String |
是 |
手机号码 |
status |
String |
是 |
回执状态,DELIVRD成功,其他失败 |
receiveTime |
String |
是 |
回执时间,格式:yyyy-MM-dd HH:mm:ss |
callData |
String |
否 |
用户回传数据,如果提交时有传递此参数将原样推送带回 |
状态获取请求:
POST http://send.it1688.com.cn:8001/sms/api/getReport
Accept: application/json
Content-Type: application/json;charset=utf-8
{
"userName": "test",
"timestamp": 1596254400000,
"sign": "e315cf297826abdeb2092cc57f29f0bf"
}
响应结果:
{
"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"
}
]
}
地址:http://send.it1688.com.cn:8001/sms/api/getUpstream
请求方法:POST
Accept: application/json
Content-Type: application/json;charset=utf-8
每次请求间隔时间不得小于30秒,如果获取条数为2000条表示还有上行未获取,可立即再次请求获取上行数据。
参数名 |
类型 |
必填 |
说明 |
userName |
String |
是 |
帐号用户名 |
timestamp |
Long |
是 |
当前时间戳,精确到毫秒。 例如2020年8月1日12:00:00 时间戳为:1596254400000 |
sign |
String |
是 |
由以下参数值组合成字符串并计算MD5值,参考详细规则 计算:MD5(userName + timestamp + MD5(password)) |
响应数据为JSON形式,每次获取不大于2000条,已获取的数据不会被再次获取到。
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,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 |
否 |
用户回传数据,如果提交时有传递此参数将原样推送带回 |
状态获取请求:
POST http://send.it1688.com.cn:8001/sms/api/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"
}
]
}
地址:http://send.it1688.com.cn:8001/sms/api/getBalance
请求方法:POST
Accept: application/json
Content-Type: application/json;charset=utf-8
参数名 |
类型 |
必填 |
说明 |
userName |
String |
是 |
帐号用户名 |
timestamp |
Long |
是 |
当前时间戳,精确到毫秒。 例如2020年8月1日12:00:00 时间戳为:1596254400000 |
sign |
String |
是 |
由以下参数值组合成字符串并计算MD5值,参考详细规则 计算:MD5(userName + timestamp + MD5(password)) |
参数名 |
类型 |
说明 |
code |
Integer |
处理结果,0为成功,其他失败,详细参考响应状态码 |
message |
String |
处理结果描述 |
balance |
Long |
当code=0时,系统返回帐号短信余额 |
状态获取请求:
POST http://send.it1688.com.cn:8001/sms/api/getBalance
Accept: application/json
Content-Type: application/json;charset=utf-8
{
"userName": "test",
"timestamp": 1596254400000,
"sign": "e315cf297826abdeb2092cc57f29f0bf"
}
响应结果:
{
"code": 0,
"message": "处理成功",
"balance": 967793
}
状态码 |
说明 |
0 |
处理成功 |
1 |
帐号名为空 |
2 |
帐号名或密码鉴权错误 |
3 |
帐号已被锁定 |
4 |
此帐号业务未开通 |
5 |
帐号余额不足 |
6 |
缺少发送号码 |
7 |
发送号码数超过10000 |
8 |
发送消息内容为空 |
9 |
无效的RCS模板ID |
10 |
非法的IP地址,提交来源IP地址与帐号绑定IP不一致 |
11 |
24小时发送时间段限制 |
12 |
定时发送时间错误或超过15天 |
13 |
请求过于频繁,每次获取数据最小间隔为30秒 |
14 |
错误的用户扩展码 |
16 |
时间戳差异过大,与系统时间误差不得超过5分钟 |
50 |
缺少模板标题 |
51 |
缺少模板内容 |
52 |
模板内容不全 |
53 |
不支持的模板帧类型 |
54 |
不支持的文件类型 |
97 |
此链接不支持GET请求 |
98 |
HTTP Content-Type错误, 请设置Content-Type: application/json |
99 |
错误的请求JSON字符串 |
500 |
系统异常 |