短信接口文档

说明

测试时,请使用正式内容进行测试,请勿给同一手机号连续发送相同内容,运营商已进行规则调整以应对短信炸弹问题。

切勿在网页中使用js代码实现短信发送,网页中js代码可被查看,因此容易被盗发;

验证码短信,如果用于注册验证环节,请务必加入图片验证码,以免被短信轰炸。

因为短信接口需要绑定IP,请登陆短信后台添加白名单IP或者与管理员联系。

单条、批量短信发送接口

功能说明:
该接口用于批量(支持单条)提交短信息,涉及到主要应用参数信息以及参数定义规则,请详细阅读!
请求地址(APIURL):https://api.zhuanxinyun.com/api/v2/sendSms.{format}
请求地址示例:默认返回json格式
https://api.zhuanxinyun.com/api/v2/sendSms.json (返回json格式的响应内容)
https://api.zhuanxinyun.com/api/v2/sendSms.xml (返回xml格式的响应内容)
请求方式:
post请求 | get请求(单次提交数量少),请求编码设置为UTF-8
应用参数如下:
名称 变量名 必填 类型 描述
公钥 appKey String 账户开通API接口后由客服提供或登陆用户后台API设置界面查看
私钥 appSecret String
终端手机号 phones String 接收短信的终端手机号,以英文逗号分隔
单次最大提交1000个号码
例:152677xxxx,1396888xxxx
任务工单号 missionNums String 发送短信的唯一标识,与手机号一一对应,用来锁定状态报告返回时对应的记录
若无需状态报告返回,则任务工单号可不填
最多32位,区分英文大小写;允许英文大小写,数字
短信内容 content String 包括签名在内容短信内容,签名需先申请报备,未报备的将会发送失败
例:【云锋网络】尊敬的用户,你好...
批次号 batchNum String
批次号都不允许重复!正式启用接口时可以考虑使用账户名+自然数若干位作为batch_num.
建议对该参数做日志,可与厂商校验提交问题
最多32位,区分英文大小写;允许英文大小写,数字
扩展号 extraNum String 支持接入号拓展,默认最大6位
请求示例如下:
请求内容:
https://api.zhuanxinyun.com/api/v2/sendSms.{format}?appKey=sbbndjdfgddsfdsz0c496t9onr1afbw2&appSecret=1845adajhgjh4hgjdcc6495b0d697ecdb3076&phones=1506789xxxx,1526779xxxx&missionNums=mission_001,mission_002&content=【云锋网络】验证码123456&batchNum=zhuanxinyun001
响应内容(其余响应代码详见文档最下页):
名称 变量名 类型 描述
错误代码(头信息) errorCode String 000000表示提交成功,其他代码请参考文档末页
错误信息(头信息) errorMsg String 错误信息描述
{format}为json时的响应 {format}为xml时的响应
{"err"rCode":"000000","errorMsg":"提交成功"}
//*注意:返回“000000”代表提交成功,手机实际状态报告请根据真实状态报告判断
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
    <errorCode>000000</errorCode>
    <errorMsg>提交成功</errorMsg>
</xml>
//*注意:返回“000000”代表提交成功,手机实际状态报告请根据真实状态报告判断

真实短信状态报告推送

客户需先在云锋网络短信后台填写URL地址,该url支持get方法获取。

(1)短信服务器以post方式,信息内容以utf-8编码,向客户提供的短信状态URL接收地址主动推送状态报告。

(2)URL格式示例:http://8.8.8.8:8000/acceptreport.jsp

(3)推送规则:每次推送一个状态报告消息包,多次无间隔连续推送!

(4)以下为格式推送示例:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <head>
        <app_key>nqzuhh1wq9lxlpya1q0976gdb50p1eqi</app_key>
        <time_stamp>20160823143033</time_stamp>
        <nonce_str>sdowenfwierhfwdkpkadbi</nonce_str>
        <sign>72b16e1d63b9f2f2ee588df4e88d7706</sign>
    </head>
    <body>
        <records>
            <record>
                <mission_num>100001</mission_num>
                <dest_id>15267797477</dest_id>
                <send_status>SUCCESS</send_status>
                <receive_status>SUCCESS</receive_status>
                <receive_real_status>DELIVRD</receive_real_status>
                <batch_num> zhuanxinyun100001</batch_num>
                <stat_time>2017-04-21 22:42:22</stat_time>
            </record>
        </records>
    </body>
</xml>

//*send_status即提交状态,一般为SUCCESS。可以不读取

//*receive_status即编译后的状态,真实网关状态为0或者DELIVRD则编译为SUCCESS,其他均为FAIL,可以不读取

//*receive_real_status即真实网关状态,0或DELIVRD表示发送成功,其他表示失败原因

//*stat_time网关状态报告返回时间,代表手机收到时间!

用户上行短信推送

客户需先在云锋网络短信后台填写URL地址,该url支持get方法获取。

(1)短信服务器以post方式,信息内容以utf-8编码,向客户提供的回复短信URL接收地址主动推送状态报告。

(2)URL格式示例:http:8.8.8.8:8000/acceptreport.jsp

(3)推送规则:每次推送一个状态报告消息包,连续推送!

(4)以下为格式推送示例:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <head>
        <app_key>nqzuhh1wq9lxlpya1q0976gdb50p1eqi</app_key>
        <time_stamp>20160823143033</time_stamp>
        <nonce_str>sdhi23hsdpghu32ohzh</nonce_str>
        <sign>72b16e1d63b9f2f2ee588df4e88d7706</sign>
    </head>
    <body>
        <dest>
            <src_id>8615058306581</src_id>
            <content>测试</content>
            <dest_id>410001123</dest_id>
        </dest>
    </body>
</xml>

余额查询接口

功能说明: 该接口用于账户余额查询,限每20秒请求一次
请求地址(APIURL):https://api.zhuanxinyun.com/api/v2/querySmsCount.{format}
请求地址示例:默认返回json格式
https://api.zhuanxinyun.com/api/v2/querySmsCount.json (返回json格式的响应内容)
https://api.zhuanxinyun.com/api/v2/querySmsCount.xml (返回xml格式的响应内容)
请求方式: post请求|get请求,请求编码设置为UTF-8
请求参数如下:
名称 变量名 必填 类型 描述
公钥 appKey String 账户开通API接口后由客服提供或登陆用户后台API设置界面查看
私钥 appSecret String
请求示例如下:
请求内容:
https://api.zhuanxinyun.com/api/v2/querySmsCount.{format}?appKey=sbbndjdfgddsfdsz0c496t9onr1afbw2&appSecret=1845adajhgjh4hgjdcc6495b0d69sddb3076
响应内容(其余响应代码详见文档最下页):
名称 变量名 类型 描述
错误代码(头信息) errorCode String 000000表示提交成功,其他代码请参考文档末页
错误信息(头信息) errorMsg String 错误信息描述
短信余额 count Int 短信余额
{format}为json时的响应 {format}为xml时的响应
{"count":100,"errorCode":"000000","errorMsg":"获取成功"} <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
    <errorCode>000000</errorCode>
    <errorMsg>获取成功</errorMsg>
    <count>100</count>
</xml>

接口提交返回参数说明

序号 errorCode返回值 errorMsg错误信息描述
1 000000 提交成功|获取成功
2 100001 参数格式错误
3 100002 账户不存在或状态异常
4 100003 appSecret错误
5 100004 请求IP不在白名单内(请在API设置页面添加白名单或与管理员联系)
6 100005 单次最大提交可1000条短信
7 100006 missionNum数量必须与手机号数量一致
8 100007 有号码格式错误
9 100008 有号码在一定时间段内请求频次过多
10 100009 账户余额不足
11 100010 日流量限制
12 100011 找不到模板
13 100012 短信条数需与手机号一致
14 100013 短信内容与模板不匹配
15 100014 访问频率过高,请稍后再试
16 999999 系统错误

部分真实网关状态报告注释

序号 网关状态报告 注释
1 MK:0000 是由于用户停机造成的。一般会发生在月初账务扣费导致该用户余额不足,BOSS对该用户停机。
2 MK:0001 被叫用户是空号
3 MK:0004 被叫用户无短信功能,一般为欠费停机导致
4 MK:0005 被叫用户无短信功能,一般为欠费停机导致
5 MK:0010 被叫用户因关机、内存满,暂时无法接收短信
6 MI:0012 被叫用户因关机、内存满,暂时无法接收短信
7 MK:0015 被叫手机终端故障导致接收短信失败
8 2:1 空号
9 2:3 空号或手机难接通
10 2:5 停机
11 2:10 一般是停机关机
12 2:11 客户短信功能异常,咨询10010
13 2:12 空号或者停机或者暂停服务
14 2:15 返回15手机接收端的问题,让客户手机清理一下,或者咨询一下联通10010短信功能是否正常的
15 2:13 已停机
16 2:33 空号
17 2:37 停机
18 YF:01 手机号无效
19 YF:02 未知运营商类型
20 YF:03 黑名单
21 YF:11 非法短信签名
22 YF:13 内容审核失败
23 YF:21 通道未分配