短信接口文档

说明

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

切勿在网页中使用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 通道未分配

JAVA

需要的jar包:httpclient、httpcore、httpmime

/**
 * 单条、批量短信发送代码
 */

public static void batchSend() {

    String appKey = "sbbndjdgcsxxmdsxxxxxxxxafbw2";
    String appSecret = "1845adaa959e40ddxxxxxxxxxxxdb3076";
    String phones = "1506789xxxx,1378592xxxx";
    String missionNums = "mission_001,mission_002";
    String content = "【云锋网络】验证码是123456";
    String batchNum = "001";
    String extraNum = "001";

    List<NameValuePair> params = new ArrayList<>();
    params.add(new BasicNameValuePair("appKey", appKey));
    params.add(new BasicNameValuePair("appSecret", appSecret));
    params.add(new BasicNameValuePair("phones", phones));
    params.add(new BasicNameValuePair("missionNums", missionNums));
    params.add(new BasicNameValuePair("content", content));
    params.add(new BasicNameValuePair("batchNum", batchNum));
    params.add(new BasicNameValuePair("extraNum", extraNum));

    String url = "https://api.zhuanxinyun.com/api/v2/sendSms.json";
    String resultMsg = HttpUtil.post(url, params);
    System.out.println(resultMsg);

}


/**
 * 个性化模板短信发送代码
 */

public static void batchTplSend() throws UnsupportedEncodingException {

    String appKey = "sbbndjdgcsxxmdsxxxxxxxxafbw2";
    String appSecret = "1845adaa959e40ddxxxxxxxxxxxdb3076";
    String phones = "1506789xxxx,1378592xxxx";
    String content = URLEncoder.encode("【云锋网络】您好,这是测试1234", "UTF-8") +
        "," + URLEncoder.encode("【云锋网络】您好,这是测试4321", "UTF-8");
    String batchNum = "001";
    String extraNum = "001";
    String templateId = "27";

    List<NameValuePair> params = new ArrayList<>();
    params.add(new BasicNameValuePair("appKey", appKey));
    params.add(new BasicNameValuePair("appSecret", appSecret));
    params.add(new BasicNameValuePair("phones", phones));
    params.add(new BasicNameValuePair("content", content));
    params.add(new BasicNameValuePair("batchNum", batchNum));
    params.add(new BasicNameValuePair("extraNum", extraNum));
    params.add(new BasicNameValuePair("templateId", templateId));

    String url = "https://api.zhuanxinyun.com/api/v2/sendTplSms.json";
    String resultMsg = HttpUtil.post(url, params);
    System.out.println(resultMsg);

}

/**
* 余额查询代码(建议间隔20秒执行1次)
 */

public static void querySmsCount() {

    String appKey = "sbbndjdgcsxxmxxxxxxxxxxxr1afbw2";
    String appSecret = "1845adaa959e40dxxxxxxxxxx0d697ecdb3076";

    List<NameValuePair> params = new ArrayList<>();
    params.add(new BasicNameValuePair("appKey", appKey));
    params.add(new BasicNameValuePair("appSecret", appSecret));

    String url = "https://api.zhuanxinyun.com/api/v2/querySmsCount.json";
    String resultMsg = HttpUtil.post(url, params);
    System.out.println(resultMsg);

}


/**
 * HttpUtil请求工具类代码
 */
public class HttpUtil {

    // 默认编码格式
    private static String ENCODING = "UTF-8";

    /**
     * post形式提交
     * @param url   路径
     * @param paramList 参数集合
     * @return
     */

    public static String post(String url, List<NameValuePair> paramList) {

        CloseableHttpClient client = HttpClients.createDefault();
        String responseText = "";
        CloseableHttpResponse response = null;
        try {
            HttpPost method = new HttpPost(url);
            method.setEntity(new UrlEncodedFormEntity(paramList, ENCODING));
            response = client.execute(method);
            HttpEntity entity = response.getEntity();
            if (entity != null) {
                responseText = EntityUtils.toString(entity, ENCODING);
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                response.close();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
        return responseText;

    }

}

PHP


// +----------------------------------------------------------------------
// | 普通短信发送代码
// +----------------------------------------------------------------------

$post_data = array(
    'appKey' => 'sbbndjdgcsxxmdsz0xxxxonr1afbw2',
    'appSecret' => '1845adaa959e40ddxxxxxx697ecdb3076',
    'phones' => '1506789xxxx,1374862xxxx',
    'missionNums' => 'arthur_001,arthur_002',
    'content' => '【云锋网络】验证码是123456',
    'batchNum' => '001',
    'extraNum' => '001',
);
echo request_by_curl('https://api.zhuanxinyun.com/api/v2/sendSms.json', $post_data);


// +----------------------------------------------------------------------
// | 个性化模板短信发送代码
// +----------------------------------------------------------------------

$post_data = array(
    'appKey' => 'sbbndjdgcsxxmdszxxxxnr1afbw2',
    'appSecret' => '1845adaa959e40ddcc6xxx697ecdb3076',
    'phones' => '1506789xxxx,1506789xxxx',
    'content' => urlencode("【云锋网络】您好,这是测试1234").",".urlencode("【云锋网络】您好,这是测试4321"),
    'batchNum' => '001',
    'extraNum' => '001',
    'templateId' => '27'
);
echo request_by_curl('https://api.zhuanxinyun.com/api/v2/sendTplSms.json', $post_data);


// +----------------------------------------------------------------------
// | 余额查询代码(建议间隔20秒执行一次)
// +----------------------------------------------------------------------

$post_data = array(
    'appKey' => 'sbbndjdgcsxxmdszxxxr1afbw2',
    'appSecret' => '1845adaa959e40dxxxxx0d697ecdb3076'
);
echo request_by_curl('https://api.zhuanxinyun.com/api/v2/querySmsCount.json', $post_data);


// +----------------------------------------------------------------------
// | request_by_curl请求方法代码
// +----------------------------------------------------------------------

function request_by_curl($remote_server, $post_data) {
  $post_string = http_build_query($post_data);
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $remote_server);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERAGENT, "zhuanxinyun");
  $data = curl_exec($ch);
  curl_close($ch);
  return $data;
}

.NET

需要引入Newtonsoft.Json类库

// 普通短信发送代码

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo1
{
    class Program
    {
        static void Main(string[] args)
        {
            var httpClient = new HttpClient();
            var value = new List<KeyValuePair<string, string>>()
            {
                new KeyValuePair<string,string>("appKey","sbbndjdgcsxxmxxxxxxxr1afbw2"),
                new KeyValuePair<string,string>("appSecret","1845adaa9xxxxxxxxxxx3076"),
                new KeyValuePair<string,string>("phones","1301xxxx973,1506xxxx818"),
                new KeyValuePair<string,string>("content","【云锋网络】您的验证码是123456")
            };
            // 证书处理
            ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, error) =>
            {
                return true;
            };
            // 构建参数
            var param = new FormUrlEncodedContent(value);
            // 用POST请求得到JSON数据(异步操作)
            var task = httpClient.PostAsync("https://api.zhuanxinyun.com/api/v2/sendSms.json", param ).RunSync();
            // 将为字符串的HTTP结果值序列化(异步操作)
            var readTask = task.Content.ReadAsStringAsync().RunSync();
            // 转换成JObject数据
            var resultMsg = JObject.Parse(readTask);
            Console.Write(resultMsg);
    }
}


// 个性化模板短信发送代码

using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo2
{
    class Program
    {
        static void Main(string[] args)
        {
            var httpClient = new HttpClient();
            UTF8Encoding utf8 = new UTF8Encoding();
            int x = 1;
            string phones =  "1301xxxx73,15067xxxx68";
            string content = UTF_8.UTFCode("【云锋网络】您好,您的验证码是123456") + "," + UTF_8.UTFCode("【云锋网络】您好,您的验证码是123456");

            var value = new List<KeyValuePair<string, string>>()
            {
                new KeyValuePair<string,string>("appKey","sbbndjdgcsxxmdsxxxxxxnr1afbw2"),
                new KeyValuePair<string,string>("appSecret","1845adaa959e40ddcxxxxx7ecdb3076"),
                new KeyValuePair<string,string>("phones",phones),
                new KeyValuePair<string,string>("content",content),
                new KeyValuePair<string,string>("templateId",x.ToString())
            };
            ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, error) =>
            {
                return true;
            };
            var param = new FormUrlEncodedContent(value);
            var task = httpClient.PostAsync("https://api.zhuanxinyun.com/api/v2/sendTplSms.json", param ).RunSync();
            var readTask = task.Content.ReadAsStringAsync().RunSync();
            var resultMsg  = JObject.Parse(readTask);
            Console.Write(resultMsg );
         }
    }
}


// 余额查询代码

using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo3
{
    class Program
    {
        static void Main(string[] args)
        {
            var httpClient = new HttpClient();
            var value = new List<KeyValuePair<string, string>>()
            {
                new KeyValuePair<string,string>("appKey","sbbndjdgxxxxxxx9onr1afbw2"),
                new KeyValuePair<string,string>("appSecret","1845adaa959e40dxxxxxxx7ecdb3076"),
            };
            ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, error) =>
            {
                return true;
            };
            var param = new FormUrlEncodedContent(value);
            var task = httpClient.PostAsync("https://api.zhuanxinyun.com/api/v2/querySmsCount.json",
 param ).RunSync();
            var readTask = task.Content.ReadAsStringAsync().RunSync();
            var resultMsg= JObject.Parse(readTask);
            Console.Write(resultMsg);
        }
    }
}


// 上行短信查询代码

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo4
{
    class Program
    {
        static void Main(string[] args)
        {
            var httpClient = new HttpClient();
            var value = new List<KeyValuePair<string, string>>()
            {
                new KeyValuePair<string,string>("appKey","sbbndjdgcsxxxxxxxnr1afbw2"),
                new KeyValuePair<string,string>("appSecret","1845adaa959e40ddxxxxxx7ecdb3076"),
            };
            ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, error) =>
            {
                return true;
            };
            var param = new FormUrlEncodedContent(value);
            var task = httpClient.PostAsync("https://api.zhuanxinyun.com/api/v2/queryMoRecord.json", param ).RunSync();
            var readTask = task.Content.ReadAsStringAsync().RunSync();
            var jobject = JObject.Parse(readTask);
            Console.Write(jobject);
        }
    }
}


// 状态报告查询代码

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo5
{
    class Program
    {
        static void Main(string[] args)
        {
            var httpClient = new HttpClient();
            var value = new List<KeyValuePair<string, string>>()
            {
                new KeyValuePair<string,string>("appKey","sbbndjdgcsxxmxxxxxxxonr1afbw2"),
                new KeyValuePair<string,string>("appSecret","1845adaa959e40ddxxxxx97ecdb3076"),
                new KeyValuePair<string, string>("time","2017-11-07")
            };
            ServicePointManager.ServerCertificateValidationCallback = (sender, cert, chain, error) =>
            {
                return true;
            };
            var param = new FormUrlEncodedContent(value);
            var task = httpClient.PostAsync("https://api.zhuanxinyun.com/api/v2/queryStatusReport.json", param ).RunSync();
            var readTask = task.Content.ReadAsStringAsync().RunSync();
            var jobject = JObject.Parse(readTask);
            Console.Write(jobject);
        }
    }
}


// Task拓展类

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Demo
{
    public static class TaskExtension
    {
        /// <summary>
        /// 异步等待并返回结果值
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <param name="task"></param>
        /// <returns></returns>
        public static T RunSync<T>(this Task<T> task)
        {
            task.Wait();
            return task.Result;
        }
    }
}