短信接口描述/API錯誤代碼/開發語言代碼示例/注意事項
切勿在網頁中使用js代碼實現短信發送,網頁中js代碼可被查看,因此容易被盜發;
驗證碼短信,如果用于注冊驗證環節,請務必加入圖片驗證碼,以免被短信轟炸。
因為短信接口需要綁定IP,請登陸短信后臺添加白名單IP或者與管理員聯系。
| 名稱 | 變量名 | 必填 | 類型 | 描述 |
|---|---|---|---|---|
| 公鑰 | 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”代表提交成功,手機實際狀態報告請根據真實狀態報告判斷
|
||
(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網關狀態報告返回時間,代表手機收到時間!
(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>
| 名稱 | 變量名 | 必填 | 類型 | 描述 |
|---|---|---|---|---|
| 公鑰 | 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 | 通道未分配 |
/** * 單條、批量短信發送代碼 */ 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; } }
// +---------------------------------------------------------------------- // | 普通短信發送代碼 // +---------------------------------------------------------------------- $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; }
// 普通短信發送代碼 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; } } }