互億無(wú)線 · 文檔中心

短信營(yíng)銷 - API文檔

短信營(yíng)銷接口文檔 點(diǎn)擊下載

短信營(yíng)銷接口接入指南 點(diǎn)擊訪問(wèn)

1.概要

1.1文檔說(shuō)明

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

1.2接口內(nèi)容

本文檔包含短信批量提交、余額查詢、短信模板提交、回執(zhí)推送、上行推送、模板審核推送。

1.3提交方式

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)銷短信”模塊，在產(chǎn)品概覽頁(yè)面右側(cè)獲取，如下圖所示：

1.6短信模版

短信模板是對(duì)您將要發(fā)送的短信進(jìn)行相似性提取后的內(nèi)容。
舉個(gè)例子，
A用戶在您平臺(tái)注冊(cè)會(huì)員，需要發(fā)送一條短信，內(nèi)容如下：
尊敬的王先生，互億無(wú)線雙旦活動(dòng)，送您100元優(yōu)惠券！回T退訂
同時(shí)，B用戶也在您的平臺(tái)注冊(cè)會(huì)員，發(fā)送了如下短信：
尊敬的李先生，互億無(wú)線雙旦活動(dòng)，送您100元優(yōu)惠券！回T退訂
我們提取相同部分以后，可以制作以下短信模板：
尊敬的${name}，互億無(wú)線雙旦活動(dòng)，送您100元優(yōu)惠券！回T退訂
其中，${name}為變量部分，可以是數(shù)字、字母、漢字。

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

1.7短信簽名

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

2. 公共請(qǐng)求參數(shù)(json格式)

參數(shù) 類型 是否必填 說(shuō)明
api_id string 是 Api的ID 如:sms-yx*******
signature string 是

請(qǐng)求驗(yàn)證加密簽名(非短信簽名);
簽名生成方式:


32位小寫(xiě);
如:
timestamp int 是 東八時(shí)區(qū);10位時(shí)間戳,時(shí)間允許相差±60S
golang: time.Now().Unix()
php: time()
request_id string 是 請(qǐng)求方請(qǐng)求ID,建議使用唯一ID,比如使用uuid;我方系統(tǒng)會(huì)2小時(shí)內(nèi)去重驗(yàn)證處理,防止網(wǎng)絡(luò)重放攻擊;

3. 短信批量提交接口

3.1協(xié)議說(shuō)明

協(xié)議類目 說(shuō)明
請(qǐng)求方式 POST
編碼格式 UTF-8
Content-Type application/json

3.2請(qǐng)求地址

https://api.ihuyi.com/sms-yx/v1/batchSend

3.3請(qǐng)求參數(shù)（json格式,需要包含公共請(qǐng)求參數(shù)）

參數(shù)              類型     是否必填   說(shuō)明
product_id int 是 產(chǎn)品ID,如:1001（獲取方式見(jiàn)下文）
phone array 是 手機(jī)號(hào)數(shù)組(最多1萬(wàn)個(gè)號(hào)碼),如:["18800000000","18800000001"]
sign_name string 是 短信簽名,如:互億無(wú)線
content string 是/否 template_id為空時(shí)必填； 
短信內(nèi)容,如:您的短信群發(fā)功能已開(kāi)通,請(qǐng)?jiān)?個(gè)工作日之內(nèi)至平臺(tái)進(jìn)行企業(yè)認(rèn)證! 短信內(nèi)容和模板ID必須傳入1個(gè);當(dāng)短信內(nèi)容和模板ID都傳入時(shí),傳入內(nèi)容生效,模板ID屬性失效;
template_id int 是/否 content為空時(shí)必填； 
模板ID
template_var object 否 選擇模板時(shí),且模板是變量模板時(shí),可以傳入變量值,需要傳入json格式;
key value 格式存儲(chǔ),如:{"${name}":"\u5f20\u4e09","${order_no}":"202009041156181103"}
send_time string 否 定時(shí)發(fā)送時(shí)間 2020-08-26 16:08:14


*product_id獲?。旱卿浀娇刂婆_(tái)，進(jìn)入“云通訊 -> 營(yíng)銷短信 -> 產(chǎn)品總覽 -> 我的資源包”頁(yè)面查看。

3.4返回參數(shù)(json格式)

參數(shù) 類型 說(shuō)明
task_id string 下發(fā)批次ID,推送回執(zhí)相關(guān)會(huì)用作關(guān)聯(lián)
code string 狀態(tài)碼,OK表示發(fā)送成功,其他則是錯(cuò)誤
message string 消息內(nèi)容

4. 余額查詢接口

4.1請(qǐng)求地址

https://api.ihuyi.com/sms-yx/v1/balance

4.2請(qǐng)求參數(shù)（json格式,需要包含公共請(qǐng)求參數(shù)）

4.3返回參數(shù)(json格式)

參數(shù) 類型 說(shuō)明
task_id string 下發(fā)批次ID,推送回執(zhí)相關(guān)會(huì)用作關(guān)聯(lián)
code string 狀態(tài)碼,OK表示發(fā)送成功,其他則是錯(cuò)誤
message string 消息內(nèi)容
data array 多個(gè)數(shù)組方式返回
DataItem結(jié)構(gòu):
參數(shù) 類型 描述
product_id int 產(chǎn)品ID
product_name string 產(chǎn)品名稱
balance float 余額

示例：

 

{

    "code": "OK",

    "message": "請(qǐng)求成功",

    "data": [

        {

            "product_id": 1018,

            "product_name": "營(yíng)銷短信-房產(chǎn)類",

            "balance": 188888

        },

        {

            "product_id": 1020,

            "product_name": "營(yíng)銷短信-商超類",

            "balance": 200000

        }

    ]

}

5. 短信模板提交接口

5.1協(xié)議說(shuō)明

協(xié)議類目 說(shuō)明
請(qǐng)求方式 POST
編碼格式 UTF-8
Content-Type application/json

5.2請(qǐng)求地址

https://api.ihuyi.com/sms-yx/v1/templateCreate

5.3請(qǐng)求參數(shù)(json格式,需要包含公共請(qǐng)求參數(shù))

參數(shù) 類型 是否必填 說(shuō)明
title string 是 模板標(biāo)題(用于標(biāo)識(shí),不會(huì)出現(xiàn)在短信內(nèi)容中)
content string 是 模板內(nèi)容(變量請(qǐng)使用變量標(biāo)識(shí)方式:${變量名稱}, 如: ${name} )
purpose string 是 應(yīng)用場(chǎng)景描述
is_variable int 是 0表示不帶變量，1表示帶變量

5.4返回參數(shù)(json格式)

參數(shù) 類型 說(shuō)明
template_id int 模板ID
code string 狀態(tài)碼,OK表示發(fā)送成功,其他則是錯(cuò)誤
message string 消息內(nèi)容

6. 回執(zhí)推送

6.1協(xié)議說(shuō)明

協(xié)議類目 說(shuō)明
調(diào)用方式 主動(dòng)回調(diào)
請(qǐng)求方式 POST
編碼格式 UTF-8
Content-Type application/json
數(shù)據(jù)格式 json

注意：接口推送后請(qǐng)記錄數(shù)據(jù)并及時(shí)返回結(jié)果，業(yè)務(wù)邏輯采用異步處理，避免接口響應(yīng)超時(shí)而導(dǎo)致重復(fù)推送。

6.2回執(zhí)數(shù)據(jù)定義

參數(shù) 類型 說(shuō)明
task_id string 下發(fā)批次ID
phone string 手機(jī)號(hào)碼
code string 狀態(tài)碼,DELIVERED則是成功,其他則是失敗
message string 返回消息,用戶接收成功
send_time string 發(fā)送時(shí)間
report_time string 回執(zhí)時(shí)間

響應(yīng)說(shuō)明:

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

7. 上行推送

7.1協(xié)議說(shuō)明

協(xié)議類目 說(shuō)明
調(diào)用方式 主動(dòng)回調(diào)
請(qǐng)求方式 POST
編碼格式 UTF-8
Content-Type application/json
數(shù)據(jù)格式 json

注意：接口推送后請(qǐng)記錄數(shù)據(jù)并及時(shí)返回結(jié)果，業(yè)務(wù)邏輯采用異步處理，避免接口響應(yīng)超時(shí)而導(dǎo)致重復(fù)推送。

7.2回執(zhí)數(shù)據(jù)定義

參數(shù) 類型 說(shuō)明
task_id string 下發(fā)批次ID
phone string 手機(jī)號(hào)碼
content string 上行內(nèi)容
dest_code string 上行通道擴(kuò)展號(hào)
send_time string 發(fā)送時(shí)間
receive_time string 收取時(shí)間

響應(yīng)說(shuō)明:

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

8.模板審核推送

8.1協(xié)議說(shuō)明

協(xié)議類目 說(shuō)明
調(diào)用方式 主動(dòng)回調(diào)
請(qǐng)求方式 POST
編碼格式 UTF-8
Content-Type application/json
數(shù)據(jù)格式 json

注意：接口推送后請(qǐng)記錄數(shù)據(jù)并及時(shí)返回結(jié)果，業(yè)務(wù)邏輯采用異步處理，避免接口響應(yīng)超時(shí)而導(dǎo)致重復(fù)推送。

8.2模板審核數(shù)據(jù)定義

參數(shù) 類型 說(shuō)明
template_id int 模板ID
code string 狀態(tài)值(SUCCESS審核通過(guò),FAIL審核失敗)
message string 審核消息

9.錯(cuò)誤碼查詢

Code 說(shuō)明
OK 請(qǐng)求成功
ParamError 參數(shù)錯(cuò)誤
AccessKeyIDNotExist AccessKeyID不存在
UserIDNotExist 用戶ID不存在
AmountError 數(shù)額錯(cuò)誤(超出許可范圍)
TimestampError 時(shí)間錯(cuò)誤(超出許可范圍)
ProductIDNotExist 產(chǎn)品ID不存在
TypeNotExist 類型不存在
RemarkError 備注錯(cuò)誤
RequestIDExisted 請(qǐng)求ID已存在
NonceExisted 隨機(jī)數(shù)已存在
SingError 簽名錯(cuò)誤
SignExpired 簽名過(guò)期
BalanceNotEnough 余額不足
PackIDExisted 資源包ID已存在
SystemError 系統(tǒng)異常
InputDataInvalid 請(qǐng)求參數(shù)異常

現(xiàn)在注冊(cè)，即享新用戶禮包!

在線咨詢
電話咨詢

服務(wù)熱線：

4008 808 898

服務(wù)熱線（工作時(shí)間）：

4008 808 898

業(yè)務(wù)咨詢（非工作時(shí)間）：

售后咨詢（非工作時(shí)間）：

驗(yàn)證碼已發(fā)送到您的手機(jī)，請(qǐng)查收！

輸入驗(yàn)證碼后，點(diǎn)擊“開(kāi)通體驗(yàn)賬戶”按鈕可立即開(kāi)通體驗(yàn)賬戶。

收不到短信驗(yàn)證碼？
互億無(wú)線不提供接碼服務(wù)，接碼用戶請(qǐng)勿點(diǎn)擊開(kāi)通按鈕。
×