拓展
共 2708字，需瀏覽 6分鐘
·
2023-04-19 16:44
IP 限制
UniSMS 支持對(duì)接口調(diào)用請(qǐng)求的 IP 地址進(jìn)行限制，以保障您的短信接口調(diào)用由可信任的服務(wù)器發(fā)出。您可以通過設(shè)置白名單指定允許訪問的 IP 地址，或通過設(shè)置黑名單來指定禁止訪問的 IP 地址。
設(shè)置
本功能為擴(kuò)展服務(wù)，默認(rèn)不開啟。請(qǐng)根據(jù)您的實(shí)際需求前往控制臺(tái)「擴(kuò)展管理-IP 限制」進(jìn)行配置。
支持填入 IPv4 地址如 111.243.214.169 或 IPv4 網(wǎng)段如 108.160.167.147/24，多個(gè)以英文逗號(hào)分隔，最多添加 50 條記錄。
發(fā)送頻率限制
為防止短信資源被特定用戶過度調(diào)用，UniSMS 支持對(duì)短信發(fā)送頻率進(jìn)行限制，從而屏蔽無用請(qǐng)求有效控制短信發(fā)送成本。您可以選擇開啟并指定針對(duì)同一手機(jī)號(hào)碼按分、按時(shí)、按天 (自然日) 的限速規(guī)則。
設(shè)置
本功能為擴(kuò)展服務(wù)，默認(rèn)不開啟。請(qǐng)根據(jù)您的實(shí)際需求前往控制臺(tái)「擴(kuò)展管理-發(fā)送頻率限制」進(jìn)行配置。
號(hào)碼白名單
如果您存在期望不受發(fā)送頻率限制的手機(jī)號(hào)碼，可以通過號(hào)碼白名單功能進(jìn)行設(shè)置。請(qǐng)使用 E.164 格式填入號(hào)碼，多個(gè)以英文逗號(hào)分隔，最多添加 50 條記錄。
狀態(tài)報(bào)告 (DLR)
短信發(fā)送狀態(tài)報(bào)告 (Delivery Receipt, DLR)，也稱為短信回執(zhí)消息。是為開發(fā)者程序化獲取短信發(fā)送狀態(tài)所提供的服務(wù)，UniSMS 支持通過 Webhook 主動(dòng)推送短信狀態(tài)報(bào)告。
設(shè)置
本功能為擴(kuò)展服務(wù)，默認(rèn)不開啟。請(qǐng)根據(jù)您的實(shí)際需求前往控制臺(tái)「擴(kuò)展管理-狀態(tài)報(bào)告」進(jìn)行配置。
設(shè)置接收狀態(tài)報(bào)告的 Webhook URL，并指定您需要接收的請(qǐng)求主體數(shù)據(jù)格式，支持 JSON 或 XML，默認(rèn)為 JSON。即完成基礎(chǔ)配置，準(zhǔn)備接入。
接入
UniSMS 將以 POST 方法向您設(shè)定的 Webhook URL 發(fā)送 HTTP 請(qǐng)求，請(qǐng)求主體以 JSON 格式為例。
Request Body
| 參數(shù)名 | 類型 | 描述 | 示例值 |
|---|---|---|---|
| id | string | 消息標(biāo)識(shí) | b3f6106a6135ad78d6ac3f232bbf1812 |
| status | string | 發(fā)送狀態(tài) | delivered |
| to | string | 收件人手機(jī)號(hào) (E.164) | +8618600001234 |
| regionCode | string | 國際代碼 | CN |
| countryCode | string | 國際電話區(qū)號(hào) | 86 |
| messageCount | integer | 計(jì)費(fèi)消息總條數(shù) | 1 |
| price | string | 消費(fèi)金額 | 0.040000 |
| currency | string | 計(jì)費(fèi)幣種 | CNY |
| errorCode | string | 回執(zhí)代碼 | DELIVRD |
| errorMessage | string | 回執(zhí)描述消息 | 發(fā)送成功 |
| submitDate | string | 提交時(shí)間 (ISO 8601) | 2022-03-07T05:18:00.252Z |
| doneDate | string | 完成時(shí)間 (ISO 8601) | 2022-03-07T05:18:03.252Z |
示例內(nèi)容如下：
{
"id": "b3f6106a6135ad78d6ac3f232bbf1812",
"status": "delivered",
"to": "+8618600001234",
"regionCode": "CN",
"countryCode": "86",
"messageCount": 1,
"price": "0.040000",
"currency": "CNY",
"errorCode": "DELIVRD",
"errorMessage": "發(fā)送成功",
"submitDate": "2022-03-07T05:18:00.252Z",
"doneDate": "2022-03-07T05:18:03.252Z",
}Response
響應(yīng) HTTP Status Code 200 即被視為狀態(tài)報(bào)告接收成功，UniSMS 不對(duì)響應(yīng)載荷進(jìn)行額外校驗(yàn)。
簽名驗(yàn)證
為進(jìn)一步保障數(shù)據(jù)安全，UniSMS 支持通過配置簽名以驗(yàn)證 Webhook 請(qǐng)求來自 UniSMS 且數(shù)據(jù)在傳輸過程中未被篡改。僅需在設(shè)置頁面中啟用「簽名驗(yàn)證」并設(shè)定簽名密鑰 (Secret) 即可。
啟用簽名驗(yàn)證后，UniSMS 將在 Webhook 請(qǐng)求頭中攜帶 Authorization 字段，其值構(gòu)造格式為 UNI1-HMAC-SHA256 Timestamp={unix_epoch}, Nonce={nonce_str}, Signature={signature}，示例如下：
Authorization: UNI1-HMAC-SHA256 Timestamp=1646634211, Nonce=0702b4ae425b0c2e, Signature=khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=提取 Timestamp, Nonce 字段并將其字段名轉(zhuǎn)換為小寫后加入請(qǐng)求有效載荷中，根據(jù)參數(shù) Key 按字典順序排序 (正序)，以 = 連接 Key-Value，以 & 連接參數(shù)對(duì)組成待簽文本串，示例如下：
countryCode=86¤cy=CNY&doneDate=2022-03-07T06%3A23%3A31.361Z&errorCode=DELIVRD&errorMessage=%E5%8F%91%E9%80%81%E6%88%90%E5%8A%9F&id=1e72734fabab9d42c9a32f9b8ad87940&messageCount=1&nonce=0702b4ae425b0c2e&price=0.045000?ionCode=CN&status=delivered&submitDate=2022-03-07T06%3A23%3A28.361Z×tamp=1646634211&to=%2B8618600001234使用 HmacSHA256 算法，以設(shè)置好的簽名密鑰 (Secret) 對(duì)待簽文本串生成簽名，輸出為 Base64 字符串，示例如下:
khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=將從 Authorization 中提取的 Signature 值與生成的簽名比對(duì)，一致則校驗(yàn)成功。
Mock 測試
為方便開發(fā)者快速接入，UniSMS 貼心的提供了 Mock 測試功能。您可以通過控制臺(tái)直接向目標(biāo)服務(wù)器發(fā)送模擬構(gòu)造的 DLR 請(qǐng)求。
重新推送
在第一次推送狀態(tài)報(bào)告失敗后，UniSMS 仍會(huì)向目標(biāo)地址重推信息，直至推送成功或超過最大推送次數(shù)。重推間隔為 1分鐘, 5分鐘, 10分鐘, 30分鐘, 1小時(shí)。