调用说明
一、短信下行
1、请求
(1)请求地址:
https://u.smsyun.cc/sms-partner/access/{用户帐号}/sendsms
注意:为了确保数据隐私和安全,用户需要通过Https Post方式请求,消息格式:json表达式。
(2)Https标准包头字段:
Accept:application/json;
Content-Type:application/json;charset=utf-8;
(3)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
clientid | String | 必选 | 帐号,6位,
如:a00012,b00012 |
password | String | 必选 | 密码,8-12位,MD5加密后32位,小写,
如:1bbd886460827015e5d605ed44252251 |
mobile | String | 必选 | 发送手机号码,
国内短信不要加前缀,国际短信号码前须带相应的国家区号,如日本:0081,
支持多号码,号码之间用英文逗号隔开,最多100个。
国内手机号码如:18612341234
国际号码如:0085265656565 |
smstype | String | 必选 | 短信类型,
"0":通知短信,"4":验证码短信,"5":营销短信 |
content | String | 必选 | 【签名】+ 短信内容,UTF-8编码,
短信内容最长500个字(包括英文字母),其中签名2-12个字(包括英文字母) |
sendtime | String | 可选 | 定时发送时间,
为空表示立即发送,定时发送格式2016-11-11 09:00:00
(未生效) |
extend | String | 可选 | 自扩展端口,
1-4位,只能为数字,可以为空
(注:请先询问配置的通道是否支持自扩展端口,如果不支持,请填空) |
uid | String | 可选 | 用户透传ID,
随状态报告返回,最长60位 |
注:
①extend字段用于客户传送由客户自行分配给子客户的扩展端口,用于上行短信回来与之对应。
如:某客户下有A、B、C三个子客户,并且该客户获得某通道两位自扩展,分别对其子客户自行分配的扩展端口依次为子客户A:01,子客户B:02,子客户C:03。
若子客户A在发送下行短信时将该扩展端口01填入此字段即可,上行短信将会把此字段的扩展端口01发给客户,用于客户区分哪个子客户的上行短信,子客户A可根据上行短信中的电话号码对应之前的下行手机号码;
②uid字段用户在单、群发短信时,由用户生成并下发到平台的序列号(最长不超过60位),该uid将在应答、状态报告中返回给客户,用于客户区分或对应单、群发短信的批次。
群发一次最多100个号码(目前不支持多内容组发)。
(4)JSON请求示例:
{
"clientid":"test",
"password":"6918d0046aab6a1ee290f751e02bd0b2",
"mobile":"13800138000,13800138001,19800138002,19800138003",
"smstype":"4",
"content":"【云通讯】您的验证码为:1234",
"sendtime":"2016-11-11 09:00:00",
"extend":"00",
"uid":"00"
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /sms-partner/access/test/sendsms HTTP/1.1 Accept-Encoding:identity Content-Length:191 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,
保证路径正确,采用HTTPS的POST方式发送; |
Body | { "clientid":"test", "password":"6918d0046aab6a1ee290f751e02bd0b2", "mobile":"13800138000,13800138001,19800138002,19800138003", "smstype":"4", "content":"【云通讯】您的验证码为1234", "sendtime":"2016-11-11 09:00:00", "extend":"00", "uid":"00" }
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
total_fee | Int | 必选 | 短信发送的计费总条数 |
data | | | 每个手机号发送的详细情况 |
code | Int | 必选 | 短信请求响应返回码,
参考“请求响应返回码”定义的返回码
(详见第九章第1节) |
msg | String | 必选 | 短信请求响应返回中文描述,
参考“请求响应返回码”定义的中文描述
(详见第九章第1节) |
fee | Int | 必选 | 成功发送的短信计费条数,
计费规则如下:
70个字一条,超出70个字时按每67字一条计费
(英文按字母个数计算) |
mobile | String | 必选 | 接收短信的手机号码 |
sid | String | 必选 | 短信标识符(用于匹配状态报告),
一个手机号对应一个sid |
uid | String | 可选 | 用户透传ID,
随状态报告返回 |
注:
①total_fee表示单(群)发短(长)短信总共计费的条数,该条数等于data域中各个fee字段数量之和;
②fee表示每个短信接收的手机号码收到短信的计费条数(长短信按照短信计费规则进行计费,长短信拆分最大不超过10条);
③sid是短信平台产生的唯一标示,与后面返回的状态报告中的sid一一对应,用于下发短息与状态报告相对应;
④uid字段返回内容和第一章第1节请求中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
(2)JSON响应示例:
{
"total_fee":2,
"data":[
{
"code":0,
"msg":"发送成功",
"fee":1,
"mobile":"13800138000",
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"1234"
},
{
"code":0,
"msg":"发送成功",
"fee":1,
"mobile":"13800138001",
"sid":"09faf6-5728-838d-95ed-e0e0cec4fd39",
"uid":"1234"
},
{
"code":-7,
"msg":"手机号码格式错误"
"fee":0,
"mobile":"19800138002",
"sid":"753af6-5728-838d-95ed-e0e0cec4fd39",
"uid":"1234"
},
{
"code":-7,
"msg":"手机号码格式错误"
"fee":0,
"mobile":"19800138003",
"sid":"95sw6-5728-838d-95ed-e0e0cec4fd39",
"uid":"1234"
}
]
}
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:424 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分 |
Body | { "total_fee":2, "data":[{ "code":0, "msg":"发送成功", "fee":1, "mobile":"13800138000", "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37" }, { "code":0, "msg":"发送成功", "fee":1, "mobile":"13800138001", "sid":"09faf6-5728-838d-95ed-e0e0cec4fd39" }, { "code":-7, "msg":"手机号码格式错误", "fee":0, "mobile":"19800138002", "sid":"753af6-5728-838d-95ed-e0e0cec4fd39" }, { "code":-7, "msg":"手机号码格式错误", "fee":0, "mobile":"19800138003", "sid":"95sw6-5728-838d-95ed-e0e0cec4fd39", "uid":"1234" }] }
| 蓝色字体为可变部分 |
二、定时短信下行
1、请求
(1)请求地址:
https://u.smsyun.cc/sms-partner/access/{用户帐号}/timer_send_sms
注意:为了确保数据隐私和安全,用户需要通过Https Post方式请求,消息格式:json表达式。
(2)Https标准包头字段:
Accept:application/json;
Content-Type:application/json;charset=utf-8;
(3)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
clientid | String | 必选 | 帐号,6位,
如:a00012,b00012 |
password | String | 必选 | 密码,8-12位,MD5加密后32位,小写,
如:1bbd886460827015e5d605ed44252251 |
mobile | String | 必选 | 发送手机号码,
国内短信不要加前缀,国际短信号码前须带相应的国家区号,如日本:0081,
支持多号码,号码之间用英文逗号隔开,最多10万个。
国内手机号码如:18612341234
国际号码如:0085265656565
拼接起来以后用compress_type中指定的压缩类型压缩,然后用base64编码压缩后的数据 |
smstype | String | 必选 | 短信类型,
"0":通知短信,"4":验证码短信,"5":营销短信 |
content | String | 必选 | 【签名】+ 短信内容,UTF-8编码,
短信内容最长500个字(包括英文字母),其中签名2-12个字(包括英文字母) |
sendtime | String | 可选 | 定时发送时间,
定时发送格式2016-11-11 09:00:00,
定时发送时间距当前时间应该大于5分钟以上 |
extend | String | 可选 | 自扩展端口,
1-4位,只能为数字,可以为空
(注:请先询问配置的通道是否支持自扩展端口,如果不支持,请填空) |
uid | String | 可选 | 用户透传ID,
随状态报告返回,最长60位 |
compress_type | String | 可选 | 默认为gzip压缩
"0": gzip压缩 |
注:
①extend字段用于客户传送由客户自行分配给子客户的扩展端口,用于上行短信回来与之对应。
如:某客户下有A、B、C三个子客户,并且该客户获得某通道两位自扩展,分别对其子客户自行分配的扩展端口依次为子客户A:01,子客户B:02,子客户C:03。
若子客户A在发送下行短信时将该扩展端口01填入此字段即可,上行短信将会把此字段的扩展端口01发给客户,用于客户区分哪个子客户的上行短信,子客户A可根据上行短信中的电话号码对应之前的下行手机号码;
②uid字段用户在单、群发短信时,由用户生成并下发到平台的序列号(最长不超过60位),该uid将在应答、状态报告中返回给客户,用于客户区分或对应单、群发短信的批次。
定时短信一次最多设置10万个号码(目前不支持多内容组发)。
(4)JSON请求示例:
{
"clientid":"test",
"password":"6918d0046aab6a1ee290f751e02bd0b2",
"mobilelist":"H4sICGUEPloAA3Bob25lLmxpc3QATdo7bmNJEEXBDbUxWZW/2v/GmmxgwJCjpPD0rncMIuK/fz….",
"smstype":"4",
"content":"【云通讯】您的验证码为:1234",
"sendtime":"2016-11-11 09:00:00",
"extend":"00",
"uid":"00",
"compress_type":"0"
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /sms-partner/access/test/sendsms HTTP/1.1 Accept-Encoding:identity Content-Length:191 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,
保证路径正确,采用HTTPS的POST方式发送; |
Body | { "clientid":"test", "password":"6918d0046aab6a1ee290f751e02bd0b2", "mobilelist":"H4sICGUEPloAA3Bob25lLmxpc3QATdo7bmNJEEXBD bUxWZW/2v/GmmxgwJCjpPD0rncMIuK/fz…", "smstype":"4", "content":"【云通讯】您的验证码为1234", "sendtime":"2016-11-11 09:00:00", "extend":"00", "uid":"00", "compress_type":"0" }
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
total_fee | Int | 必选 | 短信发送的计费总条数 |
sid | String | 必选 | 短信标识符(sid + 手机号用于匹配状态报告),
一批定时短信手机号对应一个sid |
uid | String | 可选 | 用户透传ID,
随状态报告返回 |
comporess_type | String | 可选 | 返回号码列表使用的压缩算法。
默认gzip:
0: gzip |
data | | | 发送的详细情况 |
code | Int | 必选 | 短信请求响应返回码,
参考“请求响应返回码”定义的返回码
(详见第九章第1节) |
msg | String | 必选 | 短信请求响应返回中文描述,
参考“请求响应返回码”定义的中文描述
(详见第九章第1节) |
mobilelist | String | 可选 | 当code=-7或code=-30时存在,表示code对应的号码列表(同样使用compress_type指定类型压缩+base64编码);
code为其它时无此域 |
mobilecnt | Int | 可选 | 当code=0或code=-7或code=-30时存在,表示code对应的号码个数;
code为其它时无此域 |
注:
①total_fee表示单(群)发短(长)短信总共计费的条数,该条数等于单条短信计费条数X所有成功返回的号码数;
②sid是短信平台产生的唯一标示,与后面返回的状态报告中的sid+手机号一一对应,用于下发短息与状态报告相对应;
③uid字段返回内容和第一章第1节请求中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
(2)JSON响应示例:
{
"total_fee":200,
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"1234",
"data":[
{
"code":0,
"msg":"发送成功",
"mobilecnt":200
},
{
"code":-7,
"msg":"手机号码格式错误",
"mobilelist":"H4sICGUEPloAA3Bob25lLmxp….",
"mobilecnt":4
}
]
}
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:424 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分 |
Body | { "total_fee":200, "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37", "uid":"1234", "data":[{ "code":0, "msg":"发送成功", "mobilecnt":200, }, { "code":-7, "msg":"手机号码格式错误", "fee":0, "mobilelist":"1843123454,1843123454,22344433,21822222", "mobilecnt":4 }] }
| 蓝色字体为可变部分 |
三、短信上行-推送方式
1、请求
(1)请求地址:
需要第三方自行配置URL地址,接受http post请求,消息格式:json表达式。
该接口一次推送1条上行。
(2)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
moid | String | 必选 | 上行标识符 |
mobile | String | 必选 | 短信发送端手机号码 |
content | String | 必选 | 短信内容,UTF-8编码,最长600个字 |
sign | String | 必选 | 签名字段,UTF-8编码 |
extend | String | 可选 | 扩展端口(注:此功能需要通道支持) |
reply_time | String | 必选 | 上行时间 |
注:
①moid是由短信平台产生的唯一标示,可用于客户到平台查询上行情况;
②extend字段返回内容和第一章(或第二章)第1节请求中的“扩展端口”一致,请查看之前详细说明;
上行短信中的extend字段与客户自行分配给子客户的扩展端口相对应,子客户即可通过上行中的电话号码找到之前下发的下行短信与之对应;
(3)JSON请求示例:
{
"moid":"79a11e15-5363-4a0f-b3f0-46240bd3cea6",
"mobile":"13800138000",
"content":"短信上行1",
"sign":"云通讯",
"extend":"00",
"reply_time":"2016-04-02 17:52:15",
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /xxx/xxx/xxx HTTP/1.1 Accept-Encoding:identity Content-Length:191 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,
保证路径正确,采用HTTPS的POST方式发送; |
Body | { "moid":"test", "mobile":"13800138000", "content":"短信上行1", "sign":"云通讯", "extend":"00", "reply_time":"2016-04-02 17:52:15", }
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
code | String | 必选 | 返回错误码,0:成功,其它失败 |
errmsg | String | 可选 | 返回错误详细描述 |
注:
①total_fee表示单(群)发短(长)短信总共计费的条数,该条数等于单条短信计费条数X所有成功返回的号码数;
②sid是短信平台产生的唯一标示,与后面返回的状态报告中的sid+手机号一一对应,用于下发短息与状态报告相对应;
③uid字段返回内容和第一章第1节请求中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
(2)JSON响应示例:
成功:
{
"code":"0",
}//成功
失败:
{
"code":"403",
"errmsg":"ip limit",
}//ip非法
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:13 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分 |
Body | {"code":"0"} 或 {"code":"403","errmsg":"ip limit"}
| 蓝色字体为可变部分 |
四、短信状态报告-推送方式
1、请求
(1)请求地址:
需要第三方自行配置URL地址,接受http post请求,消息格式:json表达式。该接口一次最多推送100个状态报告。
(2)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
sid | String | 必选 | 短信标识符 |
uid | String | 可选 | 用户透传ID,随状态报告返回 |
mobile | String | 必选 | 短信接收端手机号码 |
report_status | String | 必选 | 状态码,SUCCESS/FAIL |
desc | String | 必选 | 状态报告代码,
代码分类:
1.运营商返回的状态报告代码;
短信平台返回的状态报告代码,参考“短信状态报告返回码”定义(详见第九章第2节); |
user_receive_time | String | 必选 | 状态报告时间 |
注:
①sid字段返回内容和第一章(或第二章)第2节响应中的“短信标识符”一致,用于与之前下行短信的发送记录相对应;
②uid字段返回内容和第一章(或第二章)第2节响应中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
③report_status表示短信是否成功投递到手机,下行短信成功投递到手机上(即手机收到下行短信)状态码为SUCCESS,④desc字段将会有投递成功等相似字段出现(根据不同协议中文描述将会不一样),如“DELIVER”、“投递成功”等;下行短信没有投递到手机上(即手机没有收到下行短信)状态码为FAIL;④desc字段将会有投递失败等相似字段出现(根据不同协议中文描述将会不一样),如“空号”、“超频”等。
通过sid和mobile两字段可确定是哪个手机的下行短信状态报告;
通过report_status和desc字段可确定手机是否收到下行短信,并清楚下行短信投递状态;
通过user_receive_time字段可确定下行短信的到达时间。
(3)JSON请求示例:
[
{
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"00",
"mobile":"13800138000",
"report_status":"SUCCESS",
"desc":"DELIVRD",
"user_receive_time":"2016-04-02 17:52:15"
},
{
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"00",
"mobile":"13800138001",
"report_status":"FAIL",
"desc":"MC:0001",
"user_receive_time":"2016-04-02 17:52:15"
}
]
包头/包体 | 实例 | 备注 |
---|
Header | POST /xxx/xxx/xxx HTTP/1.1 Accept-Encoding:identity Content-Length:339 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,
保证路径正确,采用HTTPS的POST方式发送; |
Body | [{ "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37", "uid":"00", "mobile":"13800138000", "report_status":"SUCCESS", "desc":"DELIVRD", "user_receive_time":"2016-04-02 17:52:15", "clientid":"test", }, { "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37", "uid":"00", "mobile":"13800138001", "report_status":"FAIL", "desc":"MC:0001", "user_receive_time":"2016-04-02 17:52:15", }]
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
code | String | 必选 | 返回错误码,0:成功,其它失败 |
errmsg | String | 可选 | 返回错误详细描述 |
注:
①total_fee表示单(群)发短(长)短信总共计费的条数,该条数等于单条短信计费条数X所有成功返回的号码数;
②sid是短信平台产生的唯一标示,与后面返回的状态报告中的sid+手机号一一对应,用于下发短息与状态报告相对应;
③uid字段返回内容和第一章第1节请求中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
(2)JSON响应示例:
成功:
{
"code":"0",
}//成功
失败:
{
"code":"403",
"errmsg":"ip limit",
}//ip非法
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:13 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分 |
Body | {"code":"0"} 或 {"code":"403","errmsg":"ip limit"}
| 蓝色字体为可变部分 |
五、短信上行-拉取方式
1、请求
(1)请求地址:
https://u.smsyun.cc/sms-partner/report/{用户帐号}/getmo
注意:为了确保数据隐私和安全,用户需要通过Https Post方式请求,消息格式:json表达式。
(2)Https标准包头字段:
Accept:application/json;
Content-Type:application/json;charset=utf-8;
(3)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
clientid | String | 必选 | 帐号,6位,如:a00012,b00012 |
password | String | 必选 | 密码,8-12位,MD5加密后32位,小写,如:1bbd886460827015e5d605ed44252251 |
(4)JSON请求示例:
{
"clientid":"test",
"password":"6918d0046aab6a1ee290f751e02bd0b2"
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /sms-partner/access/test/getmo HTTP/1.1 Accept-Encoding:identity Content-Length:67 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,
保证路径正确,采用HTTPS的POST方式发送; |
Body | {"clientid":"test","password":"6918d0046aab6a1ee290f751e02bd0b2"}
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
code | Int | 必选 | 拉取上行请求响应返回码,参考“请求响应返回码”定义的返回码(详见第九章第1节) |
msg | String | 必选 | 拉取上行请求响应返回的中文描述,参考“请求响应返回码”定义的中文描述(详见第九章第1节) |
data | | | 上行的详细情况当code<0时,无此数组 |
moid | String | 必选 | 上行标识符 |
mobile | String | 必选 | 短信发送端手机号码 |
content | String | 必选 | 短信内容,UTF-8编码,最长600个字 |
sign | String | 必选 | 签名字段,UTF-8编码 |
extend | String | 可选 | 扩展端口(注:此功能需要通道支持) |
reply_time | String | 必选 | 上行时间 |
注:
①moid是由短信平台产生的唯一标示,可用于客户到平台查询上行情况;
②extend字段返回内容和第一章(或第二章)第1节请求中的“扩展端口”一致,请查看之前详细说明;
上行短信中的extend字段与客户自行分配给子客户的扩展端口相对应,子客户即可通过上行中的电话号码找到之前下发的下行短信与之对应;
(2)JSON响应示例:
{
"code":0,
"msg":"成功",
"data":[
{
"moid":"79a11e15-5363-4a0f-b3f0-46240bd3cea6",
"mobile":"13800138000",
"content":"短信上行1",
"sign":"云通讯",
"extend":"00",
"reply_time":"2016-04-02 17:52:15"
}
]
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /xxx/xxx/xxx HTTP/1.1 Accept-Encoding:identity Content-Length:157 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,保证路径正确,采用HTTPS的POST方式发送; |
Body | { "code":0 ,"msg":"成功" , "data":[{ "moid":"79a11e15-5363-4a0f-b3f0-46240bd3cea6", "mobile":"13800138000", "content":"短信上行1", "sign":"云通讯", "extend":"00", "reply_time":"2016-04-02 17:52:15" }] }
| 蓝色字体为可变部分 |
六、短信状态报告-拉取方式
1、请求
(1)请求地址:
https://u.smsyun.cc/sms-partner/report/{用户帐号}/getreport
注意:为了确保数据隐私和安全,用户需要通过Https Post方式请求,消息格式:json表达式。
(2)Https标准包头字段:
Accept:application/json;
Content-Type:application/json;charset=utf-8;
(3)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
clientid | String | 必选 | 帐号,6位,如:a00012,b00012 |
password | String | 必选 | 密码,8-12位,MD5加密后32位,小写,如:1bbd886460827015e5d605ed44252251 |
(4)JSON请求示例:
{
"clientid":"test",
"password":"6918d0046aab6a1ee290f751e02bd0b2"
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /sms-partner/access/test/getreport HTTP/1.1 Accept-Encoding:identity Content-Length:67 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,保证路径正确,采用HTTPS的POST方式发送; |
Body | {"clientid":"test","password":"6918d0046aab6a1ee290f751e02bd0b2"}
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
code | Int | 必选 | 拉取状态报告请求响应返回码,参考“请求响应返回码”定义的返回码(详见第九章第1节) |
msg | String | 必选 | 拉取状态报告请求响应返回的中文描述,参考“短信请求响应返回码”定义的中文描述(详见第九章第1节) |
data | | | 上行的详细情况当code<0时,无此数组 |
sid | String | 必选 | 短信标识符 |
uid | String | 可选 | 用户透传ID,随状态报告返回 |
mobile | String | 必选 | 短信接收端手机号码 |
report_status | String | 必选 | 状态码,SUCCESS/FAIL |
desc | String | 必选 | 状态报告代码,
代码分类:
1.运营商返回的状态报告代码;
短信平台返回的状态报告代码,参考“短信状态报告返回码”定义(详见第八章第2节) |
user_receive_time | String | 可选 | 状态报告时间 |
注:
①sid字段返回内容和第一章(或第二章)第2节响应中的“短信标识符”一致,用于与之前下行短信的发送记录相对应;
②uid字段返回内容和第一章(或第二章)第2节响应中的“用户透传ID”一致,用于客户区分或对应单、群发短信的批次;
③report_status表示短信是否成功投递到手机,下行短信成功投递到手机上(即手机收到下行短信)状态码为SUCCESS;④desc字段将会有投递成功等相似字段出现(根据不同协议中文描述将会不一样),如“DELIVER”、“投递成功”等;下行短信没有投递到手机上(即手机没有收到下行短信)状态码为FAIL;④desc字段将会有投递失败等相似字段出现(根据不同协议中文描述将会不一样),如“空号”、“超频”等。
通过sid和mobile两字段可确定是哪个手机的下行短信状态报告;
通过report_status和desc字段可确定手机是否收到下行短信,并清楚下行短信投递状态;
通过user_receive_time字段可确定下行短信的到达时间。
(2)JSON响应示例:
{
"code":0,
"msg":"成功" ,
"data":[
{
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"00",
"mobile":"13800138000",
"report_status":"SUCCESS",
"desc":" DELIVRD",
"user_receive_time":"2016-04-02 17:52:15"
},
{
"sid":"08faf6-5728-438d-95ed-e0e0cec4fd37",
"uid":"00",
"mobile":"13800138001",
"report_status":"FAIL",
"desc":"MC:0001",
"user_receive_time":"2016-04-02 17:52:15"
}
]
}
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:339 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,保证路径正确,采用HTTPS的POST方式发送; |
Body | { "code":0, "msg":"成功" , "data":[ { "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37", "uid":"00", "mobile":"13800138000", "report_status":"SUCCESS", "desc":"DELIVRD", "user_receive_time":"2016-04-02 17:52:15" }, { "sid":"08faf6-5728-438d-95ed-e0e0cec4fd37", "uid":"00", "mobile":"13800138001", "report_status":"FAIL", "desc":"MC:0001", "user_receive_time":"2016-04-02 17:52:15" } ] }
| 蓝色字体为可变部分 |
七、余额查询
1、请求
(1)请求地址:
https://u.smsyun.cc/sms-partner/report/{用户帐号}/getbalance
注意:为了确保数据隐私和安全,用户需要通过Https Post方式请求,消息格式:json表达式。
(2)Https标准包头字段:
Accept:application/json;
Content-Type:application/json;charset=utf-8;
(3)请求包体:
属性 | 类型 | 约束 | 说明 |
---|
clientid | String | 必选 | 帐号,6位,如:a00012,b00012 |
password | String | 必选 | 密码,8-12位,MD5加密后32位,小写,如:1bbd886460827015e5d605ed44252251 |
(4)JSON请求示例:
{
"clientid":"test",
"password":"6918d0046aab6a1ee290f751e02bd0b2"
}
包头/包体 | 实例 | 备注 |
---|
Header | POST /sms-partner/access/test/getreport HTTP/1.1 Accept-Encoding:identity Content-Length:67 Host:172.16.5.20:9999 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,保证路径正确,采用HTTPS的POST方式发送; |
Body | {"clientid":"test","password":"6918d0046aab6a1ee290f751e02bd0b2"}
| 蓝色字体为可变部分 |
2、响应
(1)响应包体:
属性 | 类型 | 约束 | 说明 |
---|
code | Int | 必选 | 余额查询请求返回码,参考“请求响应返回码”定义的返回码(详见第八章第1节) |
msg | String | 必选 | 余额查询请求应答返回中文描述参考“请求响应返回码”定义的中文描述(详见第八章第1节) |
data | | | 余额的详细情况当code<0时,无此数组 |
product_type | Int | 必选 | 产品类型,0:行业,1:营销,2:国际,7:USSD,8:闪信,9:挂机短信 |
remain_quantity | String | 可选 | 剩余总数量,普通短信:条,国际短信:元 |
注:
行业、营销、USSD、闪信和挂机短信等类型产品返回剩余总条数,国际类型产品返回剩余余额。
(2)JSON响应示例:
{
"code":0,
"msg":"成功" ,
"data":[
{
"product_type":0,
"remain_quantity":"1000"
},
{
"product_type":1,
"remain_quantity":"800"
},
{
"product_type":2,
"remain_quantity":"618.00"
},
{
"product_type":7,
"remain_quantity":"700"
},
{
"product_type":8,
"remain_quantity":"800"
},
{
"product_type":9,
"remain_quantity":"900"
}
]
}
失败回应:
{
"code":-13,
"data":null,
"msg":"您的费用信息不存在"
}
包头/包体 | 实例 | 备注 |
---|
Header | HTTP/1.1 200 OK Accept-Encoding:identity Content-Length:314 Host:172.16.5.21:45302 Accept:application/json Content-Type:application/json;charset=utf-8
| 蓝色字体为可变部分,保证路径正确,采用HTTPS的POST方式发送; |
Body | { "code":0, "msg":"成功", "data":[{ "product_type":0, "remain_quantity":"1000" }, { "product_type":1, "remain_quantity":"800" }, { "product_type":2, "remain_quantity":"618.00" }, { "product_type":7, "remain_quantity":"700" }, { "product_type":8, "remain_quantity":"800" }, { "product_type": 9, "remain_quantity":"900" }] }
| 蓝色字体为可变部分 |
八、返回码定义
1、请求返回码
返回码 | 描述 | 适用类型 |
0 | 成功 | 全部 |
-1 | 鉴权失败(帐号或密码错误) | 全部 |
-2 | 账号余额不足 | 短信下行、 模板短信下行 |
-3 | 账号被注销 | 全部 |
-4 | 账号被锁定 | 短信下行、 模板短信下行、定时短信下行 |
-5 | ip鉴权失败 | 全部 |
-6 | 发送号码为空 | 全部 |
-7 | 手机号码格式错误 | 短信下行、 模板短信下行、定时短信下行 |
-8 | 短信内容超长 | 短信下行、 模板短信下行、定时短信下行 |
-9 | 签名未报备 | 短信下行、 模板短信下行 |
-10 | 协议类型不匹配 | 短信下行、 模板短信下行、定时短信下行 |
-11 | 不允许拉取状态报告 | 短信状态报告 |
-12 | 访问频率过快 | 余额查询、 短信状态报告、 短信上行 |
-13 | 您的费用信息不存在 | 余额查询 |
-14 | 内部错误 | 余额查询、 短信状态报告、 短信上行 |
-15 | 用户对应的模板ID不存在、或模板未通过审核、或模板已删除 | 模板短信下行 |
-16 | 模板参数不匹配 | 模板短信下行 |
-17 | USSD、闪信和挂机短信模板不允许发送国际号码 | 模板短信下行 |
-18 | 模板ID为空 | 模板短信下行 |
-19 | 模板参数含有非法字符 | 模板短信下行 |
-20 | json格式错误 | 全部 |
-21 | 解析json失败 | 全部 |
-22 | 账号被冻结 | 短信下行、 模板短信下行、定时短信下行 |
-23 | 短信类型为空 | 短信下行、 定时短信下行 |
-24 | 短信内容为空 | 短信下行、 定时短信下行 |
-25 | 发送号码数量超过100个 | 短信下行、 模板短信下行 |
-26 | 未找到签名 | 短信下行、 定时短信下行 |
-27 | 签名长度过短(少于2个字) | 短信下行、 定时短信下行 |
-28 | 签名长度过长 | 短信下行、 定时短信下行 |
-29 | 发送号码黑名单 | 短信下行、 模板短信下行、 定时短信下行 |
-30 | 重复的发送号码 | 短信下行、 模板短信下行、 定时短信下行 |
-31 | 无查询结果 | 状态报告查询接口 |
-32 | 不允许拉取上行 | 短信上行 |
-33 | 定时短信时间格式错误 | 定时短信下行 |
-34 | 定时发送时间太短 | 定时短信下行 |
-35 | 客户不支持发送定时短信 | 定时短信下行 |
-36 | 号码解压失败 | 定时短信下行 |
2、状态报告返回码
返回码 | 描述 |
YX:1000 | 发送号码超频 |
YX:1006 | 关键字超频 |
YX:4000 | 系统内部错误4000 |
YX:4001 | 系统内部错误4001 |
YX:4002 | 短信处理超时 |
YX:4010 | 系统内部错误4010 |
YX:4011 | 系统内部错误4011 |
YX:4012 | 系统内部错误4012 |
YX:4014 | 系统内部错误4014 |
YX:4015 | 系统内部错误4015 |
YX:4016 | 系统内部错误4016 |
YX:4017 | 系统内部错误4017 |
YX:4018 | 系统内部错误4018 |
YX:4019 | 系统内部错误4019 |
YX:5001 | 系统内部错误5001 |
YX:5002 | 系统内部错误5002 |
YX:5004 | 系统内部错误5004 |
YX:5006 | 系统内部错误5006 |
YX:5007 | 系统内部错误5007 |
YX:5008 | 系统内部错误5008 |
YX:5009 | 订单余额不足 |
YX:7000 | 审核不通过 |
YX:8008 | 系统黑名单 |
YX:8010 | 系统内部错误8010 |
YX:8019 | 系统关键字 |
YX:9000 | 系统内部错误9000 |
YX:9001 | 号码格式错误 |
YX:9002 | 账号不存在 |
YX:9003 | 系统内部错误9003 |
YX:9004 | 无可用通道组 |
YX:9005 | 系统内部错误9005 |
YX:9006 | 无可选用通道 |
YX:9007 | 系统内部错误9007 |
YX:9008 | 系统内部错误9008 |
YX:9010 | 系统内部错误9010 |
YX:9011 | 系统内部错误9011 |
YX:9012 | 系统超频错误9012 |
YX:9013 | 系统内部错误9013 |
YX:9014 | 系统内部错误9014 |
YX:9015 | 系统内部错误9015 |