状态报告 (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¤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 算法，以设置好的签名密钥 (Secret) 对待签文本串生成签名，输出为 Base64 字符串，示例如下:

khZU1yxkyedU+va6L1WVgn418ycXs7xz0kxitwjFvl4=

将从 Authorization 中提取的 Signature 值与生成的签名比对，一致则校验成功。

Mock 测试

为方便开发者快速接入，UniSMS 贴心的提供了 Mock 测试功能。您可以通过控制台直接向目标服务器发送模拟构造的 DLR 请求。

重新推送

在第一次推送状态报告失败后，UniSMS 仍会向目标地址重推信息，直至推送成功或超过最大推送次数。重推间隔为 1分钟, 5分钟, 10分钟, 30分钟, 1小时。