互億無線 · 文檔中心

短信營銷 - API文檔

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

短信營銷接口接入指南 點(diǎn)擊訪問

1.概要

1.1文檔說明

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

1.2接口內(nèi)容

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

1.3提交方式

POST

1.4加密方式

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

1.5 api id / api key

登錄用戶中心，進(jìn)入“營銷短信”模塊，在產(chǎn)品概覽頁面右側(cè)獲取，如下圖所示：

1.6短信模版

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

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

1.7短信簽名

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

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

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

請求驗證加密簽名(非短信簽名);
簽名生成方式:


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

3. 短信批量提交接口

3.1協(xié)議說明

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

3.2請求地址

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

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

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


*product_id獲取：登錄到控制臺，進(jìn)入“云通訊 -> 營銷短信 -> 產(chǎn)品總覽 -> 我的資源包”頁面查看。

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

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

4. 余額查詢接口

4.1請求地址

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

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

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

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

示例：

 

{

    "code": "OK",

    "message": "請求成功",

    "data": [

        {

            "product_id": 1018,

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

            "balance": 188888

        },

        {

            "product_id": 1020,

            "product_name": "營銷短信-商超類",

            "balance": 200000

        }

    ]

}

5. 短信模板提交接口

5.1協(xié)議說明

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

5.2請求地址

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

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

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

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

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

6. 回執(zhí)推送

6.1協(xié)議說明

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

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

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

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

響應(yīng)說明:

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

7. 上行推送

7.1協(xié)議說明

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

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

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

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

響應(yīng)說明:

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

8.模板審核推送

8.1協(xié)議說明

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

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

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

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

9.錯誤碼查詢

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

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

在線咨詢
電話咨詢

服務(wù)熱線：

4008 808 898

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

4008 808 898

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

售后咨詢（非工作時間）：

驗證碼已發(fā)送到您的手機(jī)，請查收！

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

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