状态报告 (DLR)
短信发送状态报告 (Delivery Receipt, DLR)，也称为短信回执消息。是为开发者程序化获取短信发送状态所提供的服务，UniSMS 支持通过 Webhook 主动推送短信状态报告。
设置
本功能为扩展服务，默认不开启。请根据您的实际需求前往控制台「扩展管理-状态报告」进行配置。
设置接收状态报告的 Webhook URL，并指定您需要接收的请求主体数据格式，支持 JSON 或 XML，默认为 JSON。即完成基础配置，准备接入。
接入
UniSMS 将以 POST 方法向您设定的 Webhook URL 发送 HTTP 请求，请求主体以 JSON 格式为例。
Request Body
| 参数名 | 类型 | 描述 | 示例值 |
|---|---|---|---|
| id | string | 消息标识 | b3f6106a6135ad78d6ac3f232bbf1812 |
| status | string | 发送状态 | delivered |
| to | string | 收件人手机号 (E.164) | +8618600001234 |
| regionCode | string | 国际代码 | CN |
| countryCode | string | 国际电话区号 | 86 |
| messageCount | integer | 计费消息总条数 | 1 |
| price | string | 消费金额 | 0.040000 |
| currency | string | 计费币种 | CNY |
| errorCode | string | 回执代码 | DELIVRD |
| errorMessage | string | 回执描述消息 | 发送成功 |
| submitDate | string | 提交时间 (ISO 8601) | 2022-03-07T05:18:00.252Z |
| doneDate | string | 完成时间 (ISO 8601) | 2022-03-07T05:18:03.252Z |
示例内容如下：
{ "id" : "b3f6106a6135ad78d6ac3f232bbf1812" , "status" : "delivered" , "to" : "+8618600001234" , "regionCode" : "CN" , "countryCode" : "86" , "messageCount" : 1 , "price" : "0.040000" , "currency" : "CNY" , "errorCode" : "DELIVRD" , "errorMessage" : "发送成功" , "submitDate" : "2022-03-07T05:18:00.252Z" , "doneDate" : "2022-03-07T05:18:03.252Z" , }
Response
响应 HTTP Status Code 200 即被视为状态报告接收成功，UniSMS 不对响应载荷进行额外校验。
签名验证
为进一步保障数据安全，UniSMS 支持通过配置签名以验证 Webhook 请求来自 UniSMS 且数据在传输过程中未被篡改。仅需在设置页面中启用「签名验证」并设定签名密钥 (Secret) 即可。
启用签名验证后，UniSMS 将在 Webhook 请求头中携带 Authorization 字段，其值构造格式为 UNI1-HMAC-SHA256 Timestamp={unix_epoch}, Nonce={nonce_str}, Signature={signature}，示例如下：
Authorization: UNI1-HMAC-SHA256 Timestamp=1646634211, Nonce=0702b4ae425b0c2e, Signature=khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=
提取 Timestamp, Nonce 字段并将其字段名 转换为小写后加入请求有效载荷中，根据参数 Key 按字典顺序排序 (正序)，以 = 连接 Key-Value，以 & 连接参数对组成待签文本串，示例如下：
countryCode = 86 & currency = 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 & regionCode = CN & status = delivered & submitDate = 2022 -03-07T06%3A23%3A28.361Z & timestamp = 1646634211 & to = %2B8618600001234
使用 HmacSHA256 算法，以设置好的签名密钥 (Secret) 对待签文本串生成签名，输出为 Base64 字符串，示例如下:
khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4 =
将从 Authorization 中提取的 Signature 值与生成的签名比对，一致则校验成功。
Mock 测试
为方便开发者快速接入，UniSMS 贴心的提供了 Mock 测试功能。您可以通过控制台直接向目标服务器发送模拟构造的 DLR 请求。
重新推送
在第一次推送状态报告失败后，UniSMS 仍会向目标地址重推信息，直至推送成功或超过最大推送次数。重推间隔为 1分钟, 5分钟, 10分钟, 30分钟, 1小时。