拓展
共 2708字，需浏览 6分钟
· 2023-04-19
IP 限制
UniSMS 支持对接口调用请求的 IP 地址进行限制，以保障您的短信接口调用由可信任的服务器发出。您可以通过设置白名单指定允许访问的 IP 地址，或通过设置黑名单来指定禁止访问的 IP 地址。
设置
本功能为扩展服务，默认不开启。请根据您的实际需求前往控制台「扩展管理-IP 限制」进行配置。
支持填入 IPv4 地址如 111.243.214.169 或 IPv4 网段如 108.160.167.147/24，多个以英文逗号分隔，最多添加 50 条记录。
发送频率限制
为防止短信资源被特定用户过度调用，UniSMS 支持对短信发送频率进行限制，从而屏蔽无用请求有效控制短信发送成本。您可以选择开启并指定针对同一手机号码按分、按时、按天 (自然日) 的限速规则。
设置
本功能为扩展服务，默认不开启。请根据您的实际需求前往控制台「扩展管理-发送频率限制」进行配置。
号码白名单
如果您存在期望不受发送频率限制的手机号码，可以通过号码白名单功能进行设置。请使用 E.164 格式填入号码，多个以英文逗号分隔，最多添加 50 条记录。
状态报告 (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小时。