狀態(tài)報(bào)告 (DLR)
共 2248字，需瀏覽 5分鐘
·
2023-04-19 15:17
短信發(fā)送狀態(tài)報(bào)告 (Delivery Receipt, DLR)，也稱為短信回執(zhí)消息。是為開發(fā)者程序化獲取短信發(fā)送狀態(tài)所提供的服務(wù)，UniSMS 支持通過 Webhook 主動推送短信狀態(tài)報(bào)告。
設(shè)置
本功能為擴(kuò)展服務(wù)，默認(rèn)不開啟。請根據(jù)您的實(shí)際需求前往控制臺「擴(kuò)展管理-狀態(tài)報(bào)告」進(jìn)行配置。
設(shè)置接收狀態(tài)報(bào)告的 Webhook URL，并指定您需要接收的請求主體數(shù)據(jù)格式，支持 JSON 或 XML，默認(rèn)為 JSON。即完成基礎(chǔ)配置，準(zhǔn)備接入。
接入
UniSMS 將以 POST 方法向您設(shè)定的 Webhook URL 發(fā)送 HTTP 請求，請求主體以 JSON 格式為例。
Request Body
| 參數(shù)名 | 類型 | 描述 | 示例值 |
|---|---|---|---|
| id | string | 消息標(biāo)識 | b3f6106a6135ad78d6ac3f232bbf1812 |
| status | string | 發(fā)送狀態(tài) | delivered |
| to | string | 收件人手機(jī)號 (E.164) | +8618600001234 |
| regionCode | string | 國際代碼 | CN |
| countryCode | string | 國際電話區(qū)號 | 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 | 提交時間 (ISO 8601) | 2022-03-07T05:18:00.252Z |
| doneDate | string | 完成時間 (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 不對響應(yīng)載荷進(jìn)行額外校驗(yàn)。
簽名驗(yàn)證
為進(jìn)一步保障數(shù)據(jù)安全，UniSMS 支持通過配置簽名以驗(yàn)證 Webhook 請求來自 UniSMS 且數(shù)據(jù)在傳輸過程中未被篡改。僅需在設(shè)置頁面中啟用「簽名驗(yàn)證」并設(shè)定簽名密鑰 (Secret) 即可。
啟用簽名驗(yàn)證后，UniSMS 將在 Webhook 請求頭中攜帶 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)換為小寫后加入請求有效載荷中，根據(jù)參數(shù) Key 按字典順序排序 (正序)，以 = 連接 Key-Value，以 & 連接參數(shù)對組成待簽文本串，示例如下：
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) 對待簽文本串生成簽名，輸出為 Base64 字符串，示例如下:
khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=將從 Authorization 中提取的 Signature 值與生成的簽名比對，一致則校驗(yàn)成功。
Mock 測試
為方便開發(fā)者快速接入，UniSMS 貼心的提供了 Mock 測試功能。您可以通過控制臺直接向目標(biāo)服務(wù)器發(fā)送模擬構(gòu)造的 DLR 請求。
重新推送
在第一次推送狀態(tài)報(bào)告失敗后，UniSMS 仍會向目標(biāo)地址重推信息，直至推送成功或超過最大推送次數(shù)。重推間隔為 1分鐘, 5分鐘, 10分鐘, 30分鐘, 1小時。