短信營(yíng)銷(xiāo)接口

1、概要

1.1 文檔說(shuō)明

本文檔主要提供給互億平臺(tái)的用戶對(duì)接接口的使用說(shuō)明，開(kāi)發(fā)者可以利用 ihuyi 提供的 HTTP 接口，調(diào)用 ihuyi 的短信營(yíng)銷(xiāo)服務(wù)。

1.2 接口內(nèi)容

本文檔包含短信發(fā)送、余額查詢、發(fā)送回執(zhí)推送、上行回復(fù)推送等。

1.3 提交方式

GET / POST

1.4 加密方式

1、采用HTTPS協(xié)議提交請(qǐng)求
2、通過(guò)MD5動(dòng)態(tài)簽名方式加密

1.5 API ID / API KEY

登錄用戶中心，進(jìn)入【短信營(yíng)銷(xiāo)】模塊，在【產(chǎn)品總攬】頁(yè)面右上角

1.6 短信模版

短信模板是對(duì)您將要發(fā)送的短信進(jìn)行相似性提取后的內(nèi)容。舉個(gè)例子，
A用戶在您平臺(tái)注冊(cè)會(huì)員，需要發(fā)送一條短信，內(nèi)容如下：

您好，您的驗(yàn)證碼是：666666

同時(shí)，B用戶也在您的平臺(tái)注冊(cè)會(huì)員，發(fā)送了如下短信：

您好，您的驗(yàn)證碼是：888888

我們提取相似度以后，可以制作以下短信模板：

您好，您的驗(yàn)證碼是：【變量】

其中，變量是可變的，可以是 數(shù)字、字母、漢字。

注意：付費(fèi)用戶可以通過(guò)左側(cè)導(dǎo)航【短信營(yíng)銷(xiāo)】-【短信發(fā)送】-【模版管理】新增短信模板，運(yùn)營(yíng)商審核通過(guò)之后即可正式使用。

1.7 短信簽名

短信簽名是加在短信的開(kāi)頭或結(jié)尾，在【】加上您的公司名稱(chēng)或店鋪名稱(chēng)的標(biāo)識(shí)符，例如：【互億無(wú)線】。 根據(jù)電信基礎(chǔ)運(yùn)營(yíng)商的規(guī)定，每條短信必須附加短信簽名，否則將無(wú)法正常發(fā)送。

2、短信發(fā)送

2.1 接口描述

通過(guò)POST、 GET 方式進(jìn)行短信提交，數(shù)據(jù)編碼采用utf-8格式，24小時(shí)全天發(fā)送。

2.2 請(qǐng)求地址

http://api.yx.ihuyi.com/webservice/sms.php?method=Submit

2.3 請(qǐng)求參數(shù)

參數(shù)名稱(chēng)	參數(shù)值描述	必填
account	APIID（請(qǐng)登錄用戶中心【短信營(yíng)銷(xiāo)】-【產(chǎn)品縱覽】查看）	是
password	1、APIKEY（請(qǐng)登錄用戶中心【短信營(yíng)銷(xiāo)】-【產(chǎn)品縱覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明）	是
mobile	接收手機(jī)號(hào)碼， 多個(gè)號(hào)碼請(qǐng)用英文逗號(hào)隔開(kāi)。	是
content	短信內(nèi)容（編碼格式為UTF-8，支持300個(gè)字的長(zhǎng)短信，長(zhǎng)短信按多條計(jì)費(fèi)） 注：1、請(qǐng)?zhí)顚?xiě)有實(shí)際意義的短信內(nèi)容，避免用"短信測(cè)試、aaaaa"等字樣。        2、【簽名】請(qǐng)用您的公司名、品牌名等。 例：尊敬的會(huì)員，您好，夏季新品已上市，請(qǐng)關(guān)注。退訂回TD【互億無(wú)線】	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
stime	指定短信下發(fā)時(shí)間（格式：2016-11-30 15:30:00）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否

用戶通過(guò)http 或 https提交發(fā)送短信請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，SubmitResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱(chēng)	類(lèi)型	描述
code	int	返回值為2時(shí)，表示提交成功
smsid	string	當(dāng)提交成功后，此字段為流水號(hào)，否則為0
msg	string	提交結(jié)果描述

2.4 響應(yīng)示例

示例（成功）

 2 提交成功 14745625541233112231 

示例（失?。?/p>

 405 用戶名或密碼不正確 0 

2.5 響應(yīng)參數(shù)

code	msg
0	提交失敗
2	提交成功
400	非法ip訪問(wèn)
401	帳號(hào)不能為空
402	密碼不能為空
403	手機(jī)號(hào)碼不能為空
4030	手機(jī)號(hào)碼已被列入黑名單
404	短信內(nèi)容不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)
4051	剩余條數(shù)不足
4052	訪問(wèn)ip與備案ip不符
406	手機(jī)格式不正確
407	短信內(nèi)容含有敏感字符
4070	簽名格式不正確
4071	沒(méi)有提交備案模板
4072	短信內(nèi)容與模板不匹配
4073	短信內(nèi)容超出長(zhǎng)度限制
408	您的帳戶疑被惡意利用，已被自動(dòng)凍結(jié)，如有疑問(wèn)請(qǐng)與客服聯(lián)系。

2.6 請(qǐng)求示例

http://api.yx.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手機(jī)號(hào)碼&content=短信內(nèi)容【簽名】

3、余額查詢

3.1 接口描述

通過(guò)接口可以方便的查詢你的賬戶驗(yàn)證碼通知短信剩余條數(shù)。

3.2 請(qǐng)求地址

http://api.yx.ihuyi.com/webservice/sms.php?method=GetNum

3.3 請(qǐng)求參數(shù)

參數(shù)名稱(chēng)	參數(shù)值描述	是否必填
account	APIID（請(qǐng)登錄用戶中心【短信營(yíng)銷(xiāo)】-【產(chǎn)品縱覽】查看）	是
password	1、APIKEY（請(qǐng)登錄用戶中心【短信營(yíng)銷(xiāo)】-【產(chǎn)品縱覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明）	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否

用戶通過(guò)http 或 https提交帳戶余額查詢請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，GetNumResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱(chēng)	類(lèi)型	描述
code	int	狀態(tài)返回值
msg	string	查詢結(jié)果描述
num	string	剩余數(shù)量

3.4 響應(yīng)示例

示例（成功）

 2 查詢成功 856 

示例（失敗）

 405 用戶名或密碼不正確 0 

3.5 響應(yīng)參數(shù)

code	msg
2	查詢成功
400	非法ip訪問(wèn)
401	帳號(hào)不能為空
402	密碼不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)

3.6 GET請(qǐng)求示例

http://api.yx.ihuyi.com/webservice/sms.php?method=GetNum&account=APIID&password=APIKEY 

4、發(fā)送回執(zhí)推送

4.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無(wú)線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以POST方式實(shí)時(shí)的將回執(zhí)信息推送到此地址。

4.2 推送參數(shù)

參數(shù)名稱(chēng)	參數(shù)值描述
code	狀態(tài)值（2成功 其他為失?。?/td>
msg	回執(zhí)狀態(tài)說(shuō)明
mobilephone	手機(jī)號(hào)碼
task_id	流水號(hào)（對(duì)應(yīng)提交時(shí)返回的task_id）
report_time	回執(zhí)時(shí)間

注意: 成功接收請(qǐng)輸出字符 "success" （不包含引號(hào)）結(jié)束推送，否則以接收失敗處理。每個(gè)回執(zhí)最多推送3次。每次間隔疊加60秒。

5、上行回復(fù)推送

5.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無(wú)線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以POST方式實(shí)時(shí)的將回復(fù)信息推送到此地址。

5.2 推送參數(shù)

參數(shù)名稱(chēng)	參數(shù)值描述
mobilephone	手機(jī)號(hào)碼
content	上行內(nèi)容
task_id	流水號(hào)（對(duì)應(yīng)提交時(shí)返回的task_id）（僅作參考）
reply_time	上行時(shí)間

注意: 成功接收請(qǐng)輸出字符 "success" （不包含引號(hào)）結(jié)束推送，否則以接收失敗處理。每個(gè)回執(zhí)最多推送3次。每次間隔疊加60秒。

6、生成動(dòng)態(tài)密碼方式

以PHP為例，提交短信的生成方式：

$time = time();
$password = md5($account.$apikey.$mobile.$content.$time);

例如：

APIID： test
APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào)：138xxxxxxxx
內(nèi)容：尊敬的會(huì)員，您好，夏季新品已上市，請(qǐng)關(guān)注。退訂回TD【互億無(wú)線】
time：1451544941
結(jié)果：$password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d138xxxxxxxx尊敬的會(huì)員，您好，夏季新品已上市，請(qǐng)關(guān)注。退訂回TD【互億無(wú)線】1451544941');

注意：因?yàn)槎绦艃?nèi)容會(huì)包含中文，所以字符編碼統(tǒng)一為UTF-8

查詢剩余條數(shù)的生成方式：

$time = time();
$password = md5($account.$apikey.$time);

例如：

APIID： test
APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào)：138xxxxxxxx
time：1451544941
結(jié)果：$password=md5('test1q784322ba1d9bb88d50cf5cdfd89k7d1451544941');

Unix時(shí)間戳參考地址：http://tool.chinaz.com/Tools/unixtime.aspx