状态报告查询 API

除了通过回调机制（Callback）获取短信的投递状态报告（DLR），PaaSoo 平台同时支持同步查询的方式，便于您在需要时调用接口来检查特定消息的投递结果。该查询接口在您希望主动轮询或手动触发查询的时候特别有用，无需依赖被动回调。

1. 调用说明

调用方式

HTTP Method：GET
请求地址：https://api.paasoo.cn/dlr
使用场景：当您需要基于消息 ID 手动获取或定时审核短信发送状态时，可调用此接口。在部分国家或地区，运营商的 DLR 可靠性有限，因此可通过此查询进一步确认发送状态。

2. 请求示例

GET https://api.paasoo.cn/dlr?key=API_KEY&secret=API_SECRET&messageid=MESSAGE_ID

3. 请求参数说明

参数	类型	必填	描述	示例
key	string	是	API Key（字母或数字构成，共 8 位），用于唯一标识您的账户。可在PaaSoo 客户端后台获取。	Abcdefgh
secret	string	是	API Secret（字母或数字构成，共 8 位），与 `key` 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。	Abc123EF
messageid	string	是	需要查询的消息 ID，用于唯一标识一条短信发送请求。	015bd4-d6dfa7-58w

4. 响应示例

当查询成功时，您将收到详细的状态报告数据；若查询失败，则会返回错误码及相应提示。

4.1 响应参数说明

4.1.1 成功参数说明

返回数组列表，数组项说明

参数	类型	描述	示例
price	number	单条短信计费价格（单位：USD 或由账户计费货币决定）。	0.03
network	string	发送号码的运营商网络，如 MCC+MNC 组合。	23420
status	string	发送状态。 1 - 发送中 0 - 提交供应商成功 400 - 提交供应商失败	1 - 发送中
to	string	发送目标号码，格式为`国家区号 + 手机号码`（不含前导 00 或 +）。	8618911111111
drTime	string	报告时间(UTC+0)，格式（yyyy-MM-dd HH:mm:ss.ZZZ）	2025-08-12 09:01:17.676
drStatus	integer	状态报告值： 0 - 正常状态 400 - 异常状态	0
type	string	结果数据类型，状态报告查询返回 dlr。	dlr
messageid	string	被查询的消息 ID，用以唯一标识一条短信请求。	015bd4-d6dfa7-58w
counts	integer	计费条数（根据短信长度或拆分等因素可能会超过 1 条）。	1
drStatuscode	string	详细状态报告代码： delivered - 短信送达，对应 drStatus=0 accepted - 运营商接收，对应 drStatus=0 rejected - 运营商拒绝，对应 drStatus=400 failed - 发送失败，对应 drStatus=400 expired - 运营商超时，对应 drStatus=400 deleted - 被运营商删除，对应 drStatus=400 unknown - 未知错误，对应 drStatus=400	delivered
drErrcode	string	运营商返回的错误码，与 drStatuscode 相对应： 0 - 正常 1 - 未知错误 2 - 消息无法送达（停机、关机、无信号等） 3 - 号码已停用或无效 4 - 用户拒收短信 5 - 被运营商拒绝 6 - 运营商超时 7 - 被运营商删除 8 - 用户免打扰（DND） 10 - 标题/ Sender ID 无效 11 - 模板无效 12 - Entity ID 不匹配 99 - 其他运营商错误	0 - 正常

4.1.2 失败参数说明

参数	类型	描述	示例
code	integer	状态码。 2 - Missing parameters：缺少必要参数 3 - Invalid parameters：参数格式错误 4 - Invalid credentials：Key或Secret错误 5 - Unauthorized IP：IP限制 9 - Quota exceeded：欠费或信用额度不足 11 - System error：系统错误 20 - Dlr search not support：报告查询不支持	2
descr	string	状态码描述。	Invalid credentials

4.2 成功响应示例

[
    {
        "type": "dlr",
        "messageid": "00041d-23fefc-c000",
        "to": "919340275066",
        "status": 0,
        "drStatus": 400,
        "drStatuscode": "failed",
        "drErrcode": "5",
        "price": 0.001,
        "counts": 1,
        "drTime": "2025-12-16 15:51:20.055",
        "network": "405840"
    }
]

4.3 失败响应示例

{
    "code": 2,
    "descr": "Missing parameters"
}

5. 最佳实践与注意事项

签名与安全：
- 通过 key 和 secret 进行身份验证，请妥善保管，避免泄露。
- 建议使用 HTTPS 调用接口，防止敏感信息在传输过程中被窃取。
轮询策略：
- 若您已配置 DLR 回调机制，可仅在回调失败或消息状态长期未更新时再使用此查询接口。
- 为避免对服务器造成过大压力，应合理设置查询频率。
数据解析：
- 根据 status 判断查询请求是否成功，0 表示成功查询并可获取 drStatus 等详细字段。
- 同样的 drStatus / drStatuscode 解释与回调 DLR 保持一致，请结合前端或系统逻辑进行对账和状态映射。
兼容性：
- 与 DLR 回调类似，某些国家或地区的运营商可能无法提供准确或实时的状态报告。
- 如查询结果与实际投递情况不符，可联系相关运营商或 PaaSoo 技术支持做进一步排查。

6. 小结

通过上述状态报告查询 API，您可以随时主动获取指定短信的发送状态。结合 DLR 回调与手动查询两种方式，能够有效提升对短信发送链路的监控与管理能力。

技术支持

如在 API 对接过程中遇到任何技术问题或业务疑问，欢迎随时联系我们的开发者支持团队：support@paasoo.com。我们将竭诚为您提供技术协助。

1. 调用说明​

2. 请求示例​

3. 请求参数说明​

4. 响应示例​

4.1 响应参数说明​

4.1.1 成功参数说明​

4.1.2 失败参数说明​

4.2 成功响应示例​

4.3 失败响应示例​

5. 最佳实践与注意事项​

6. 小结​