跳到主要内容

状态报告接收 API

当您使用 PaaSoo 国际短信/通信服务发送短信后，您可以通过本回调机制接收短信的投递状态报告（即 DLR）。请注意：这些投递状态报告（DLR）通常由运营商端返回，因此在不同国家/地区，运营商的上报机制和时效性可能存在差异，在某些区域，报告可能不够完整或可靠，无法完全反映最终的送达情况。

通过集成此回调功能，您可以在业务数据库或前端系统中同步更新短信的投递结果，从而更好地管理、追踪各条短信是否成功送达用户终端。本文档将向您介绍回调方式、参数含义以及常见的接收处理示例。

1. 回调说明​

调用方式
  • HTTP Method：GET
  • 回调地址：在 PaaSoo 平台中预先配置的 USER_CALLBACK_URL (由您提供)。
  • 回调时机：当目标运营商生成或更新状态报告时，PaaSoo 会将状态通过 GET 请求推送到您指定的回调地址。
  • 重试策略：若您的服务器未能正确返回 HTTP 200，PaaSoo 会在 5 / 10 / 30 分钟间隔尝试重新发送。

2. 回调示例​

当状态报告产生后，PaaSoo 平台会以如下 GET 请求形式调用您的回调地址：

https://USER_CALLBACK_URL?type=dlr&messageid=MESSAGE_ID&to=8618911111111&status=0&statuscode=delivered&errcode=0&network=52099&price=0.03&counts=1×tamp=1686045579378

注意：timestamp 参数中的加号（+）会在 URL 中被编码为 %3A 或其它转义字符，这取决于实际 URL 编码方式。

3. 参数说明​

参数类型描述示例
typestring回调消息类型，DLR 回调固定为 dlr。dlr
messageidstring发送请求时所返回的消息 ID，用于唯一标识一条短信请求。015bd4-d6dfa7-58w
tostring短信目标号码，格式为国家区号 + 手机号码（不含前导 00 或 +）。8618911111111
statusinteger状态值：
  • 0 - 正常状态
  • 400 - 异常状态
0
statuscodestring详细状态代码：
  • delivered - 短信送达 (对应 status=0)
  • accepted - 运营商接收 (对应 status=0)
  • rejected - 运营商拒绝 (对应 status=400)
  • failed - 发送失败 (对应 status=400)
  • expired - 运营商超时 (对应 status=400)
  • deleted - 被运营商删除 (对应 status=400)
  • unknown - 未知错误 (对应 status=400)
delivered
errcodestring运营商返回的错误码（如果有），与 statuscode 对应：
  • 0 - 正常
  • 1 - 未知错误
  • 2 - 消息无法送达（停机、关机、无信号等）
  • 3 - 号码已停用或无效
  • 4 - 用户拒收短信
  • 5 - 被运营商拒绝
  • 6 - 运营商超时
  • 7 - 被运营商删除
  • 8 - 用户免打扰（DND）
  • 10 - 无效的 Sender ID
  • 11 - 模板无效
  • 12 - Entity ID 不匹配
  • 99 - 其他运营商错误
0 - 正常
networkstring目标号码的运营商网络，如 MCC+MNC 组合。52099
pricenumber单条短信计费价格（单位：USD 或由账户计费货币决定）。 0.03
countsinteger计费条数（可能受短信长度、GSM7/Unicode 转换、拆分计费等因素影响）。1
refstring客户自定义参数，用于将初始请求与 PaaSoo 的响应（通过异步通知或查询结果返回）进行关联。
timestamplong状态报告生成的时间戳，单位毫秒。1686045579378

4. 回调响应与重试​

  • 成功响应：当您接收到回调并完成处理后，需要返回 HTTP 200 或类似的成功响应，以告知 PaaSoo 回调已被正确接收。
  • 重试机制：如果 PaaSoo 未接收到有效的成功响应，系统会在 5 分钟、10 分钟、30 分钟间隔分别重试一次。如仍未收到 200 响应，则放弃后续重试。
  • 建议：在实际生产环境中，务必为回调添加日志记录或数据库插入逻辑，以防止多次重试造成重复数据。可通过 messageid 进行去重操作。

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

  1. 安全性：
    • 建议在回调 URL 中采用 HTTPS 加密，以保障数据传输安全。
    • 可通过验证来源 IP、查询签名参数等方式加强安全控制，避免恶意调用。
  2. 参数存储：
    • 务必记录 messageid、to、statuscode 等核心字段，以支持后续对账和日志分析。
    • 如需对计费、扣费情况进行统计，可记录 price 和 counts 字段。
  3. 幂等处理：
    • 若同一条 DLR 回调多次到达（在重试状态下可能发生），请使用 messageid 进行幂等性判断，避免重复入库与处理。
  4. 兼容性：
    • 部分运营商可能不会按时返回最终状态，或在网络不稳定时延迟回调。
    • 部分运营商可能不提供完整的 errcode 详细信息。
    • 由于状态报告依赖运营商端，本身的准确性在部分国家或地区可能受限，需额外关注。

6. 小结​

以上便是 PaaSoo 平台推送短信状态报告（Delivery Receipt, DLR）至用户指定回调地址的相关说明与实现示例。 由于这类报告在不同国家或地区的可靠性取决于当地运营商的同步机制，您可能需要结合业务场景来评估最终送达情况。 通过搭建 DLR 回调接收端，您可以在短信触达的全流程中获得更全面、更实时的监控能力。

技术支持

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