接口文档

短信网关接口规范(JSON)

version 1.1

 

版本修订历史

版本

日期

说明

1.0

2020-06-09

接口规范与参数定义

1.1

2021-01-01

增强接口调用安全性

目录

 

1. 前言

本协议基于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

 

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

帐号用户名

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。

用户若传递此参数将在回执推送时回传给用户。

2.4 响应结果

参数名

类型

说明

code

Integer

处理结果,0为成功,其他失败,详细参考响应状态码

message

String

处理结果描述

msgId

Long

当code=0时,系统返回唯一消息Id

 

2.5 请求示例

批量发送请求:

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

}

3. 短信一对一发送接口

3.1 调用地址

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

请求方法: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))

sendTime

String

短信定时发送时间,格式:yyyy-MM-dd HH:mm:ss

定时时间限制15天以内。

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

参数名

类型

必填

说明

phone

String

发送手机号码

content

String

短信内容

extcode

String

可选,附带通道扩展码

callData

String

用户回传数据,最大长度64。

用户若传递此参数将在回执推送时回传给用户。

3.4 响应结果

参数名

类型

说明

code

Integer

处理结果,0为成功,其他失败,详细参考响应状态码

message

String

处理结果描述

data

[Array]

当code=0时,系统返回处理结果的数组对象集合,对象参数见下表。

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

参数名

类型

说明

code

Integer

处理结果,0为成功,其他失败,详细参考响应状态码

message

String

处理结果描述

msgId

Long

当code=0时,系统返回唯一消息Id

phone

String

发送手机号码

3.5 请求示例

批量发送请求:

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"

}

]

}

4. 回执状态推送接口

4.1 调用地址

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

推送请求方法:POST

4.2 推送请求包头定义

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

4.3 请求参数

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

参数名

类型

必填

说明

msgId

Long

消息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

通道端口号

callData

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 请求参数

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

参数名

类型

必填

说明

userName

String

帐号用户名

timestamp

Long

当前时间戳,精确到毫秒。

例如2020年8月1日12:00:00 时间戳为:1596254400000

sign

String

由以下参数值组合成字符串并计算MD5值,参考详细规则

计算:MD5(userName + timestamp + MD5(password))

6.4 响应结果

响应数据为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

用户回传数据,如果提交时有传递此参数将原样推送带回

 

6.5 请求示例

状态获取请求:

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"

}

]

}

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 请求参数

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

参数名

类型

必填

说明

userName

String

帐号用户名

timestamp

Long

当前时间戳,精确到毫秒。

例如2020年8月1日12:00:00 时间戳为:1596254400000

sign

String

由以下参数值组合成字符串并计算MD5值,参考详细规则

计算:MD5(userName + timestamp + MD5(password))

7.4 响应结果

响应数据为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

用户回传数据,如果提交时有传递此参数将原样推送带回

 

7.5 请求示例

状态获取请求:

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"

}

]

}

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

帐号用户名

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 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

}

 

9. 响应状态码列表

状态码

说明

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

系统异常

 

 


扫一扫

扫码关注 · 认证、审核结果通知 · 短信发送结果通知 · 活动及最新平台信息

返回顶部