-
富媒體短信
-
云語音
-
認(rèn)證核驗
-
數(shù)字權(quán)益
-
企業(yè)服務(wù)
短信營銷 - API文檔
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
登錄用戶中心，進入“營銷短信”模塊，在產(chǎn)品概覽頁面右側(cè)獲取，如下圖所示：
1.6短信模版
舉個例子，
A用戶在您平臺注冊會員，需要發(fā)送一條短信，內(nèi)容如下：
注意：付費用戶可以通過左側(cè)導(dǎo)航【營銷短信】-【短信發(fā)送】-【模版管理】新增短信模板，運營商審核通過之后即可正式使用。
1.7短信簽名
短信簽名是加在短信的開頭或結(jié)尾，在【】加上您的公司名稱或店鋪名稱的標(biāo)識符，例如：【互億無線】。 根據(jù)電信基礎(chǔ)運營商的規(guī)定，每條短信必須附加短信簽名，否則將無法正常發(fā)送。
2. 公共請求參數(shù)(json格式)
| 參數(shù) | 類型 | 是否必填 | 說明 |
| api_id | string | 是 | Api的ID 如:sms-yx******* |
| signature | string | 是 |
請求驗證加密簽名(非短信簽名);
|
| 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 |
是 | 手機號數(shù)組(最多1萬個號碼),如:["18800000000","18800000001"] |
| sign_name | string | 是 | 短信簽名,如:互億無線 |
| content | string | 是/否 | template_id為空時必填； 短信內(nèi)容,如:您的短信群發(fā)功能已開通,請在3個工作日之內(nèi)至平臺進行企業(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獲?。旱卿浀娇刂婆_，進入“云通訊 -> 營銷短信 -> 產(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):
|
示例：
{
"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 | 手機號碼 |
| 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 | 手機號碼 |
| content | string | 上行內(nèi)容 |
| dest_code | string | 上行通道擴展號 |
| 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 | 隨機數(shù)已存在 |
| SingError | 簽名錯誤 |
| SignExpired | 簽名過期 |
| BalanceNotEnough | 余額不足 |
| PackIDExisted | 資源包ID已存在 |
| SystemError | 系統(tǒng)異常 |
| InputDataInvalid | 請求參數(shù)異常 |
