ZOLOZZOLOZDOCS

callbacksms

本文详细介绍ZOLOZ Global SMS服务的回调协议规范。当短信投递状态发生变化时（例如成功送达或发送失败），ZOLOZ会通过HTTP请求主动将状态报告推送到您预先配置的回调地址，帮助您及时获取短信投递结果。

回调机制

ZOLOZ系统接收到运营商返回的短信投递结果后，会立即将状态信息推送到您预先配置的回调URL。

此过程为异步回调。从API调用成功到收到回调通知的时间间隔通常在几秒到几分钟之间，具体时长取决于运营商的处理速度和实时网络状况。

请求内容

请求方式

  • 请求方法：HTTP POST
  • 内容类型：Content-Type为application/json

请求参数

字段名称

数据类型

是否必填

描述

示例值

transactionId

String

是

短信发送的唯一ID，可通过sendsms API获取。

G0062000011MT20250630eowLGRE371HnpU****

mobile

String

是

接收短信的手机号码，格式为“国际区号+号码”。

63123456

status

String

是

短信发送状态。

  • Delivered：短信发送成功。
  • DeliveryFailed：短信发送失败。

Delivered

smsNum

int

是

用于计费的短信条数，详见计费说明。

1

sendDate

String

是

短信发送时间。

2025-06-30T16:35:46+08:00

deliveredDate

String

否

运营商成功发送短信的回执时间。

说明：仅当status设置为Delivered时该参数才生效。

2025-06-30T16:40:56+08:00

回调示例

copy
{
    "deliveredDate": "2025-06-30T16:40:56+08:00", 
    "mobile": "63123456", 
    "sendDate": "2025-06-30T16:35:46+08:00", 
    "smsNum": 1, 
    "status": "Delivered", 
    "transactionId": "G0062000011MT20250630eowLGRE371HnpU****"
}

响应内容

为了确认您已成功接收到回调通知，您的服务器接口必须返回以下响应。

成功响应

HTTP状态码200 OK表示回调成功，且ZOLOZ系统仅以HTTP状态码200作为回调成功的唯一判断标准。响应体内容不用于任何判定，仅供您调试使用。

失败响应

如果您的接口返回任何非200的HTTP状态码或发生网络超时，ZOLOZ系统将判定为回调失败并触发重试机制。

重试机制

为确保回调消息的可靠送达，系统将在回调失败时自动进行重试，具体机制如下：

参数

值

说明

最大重试次数

10次

总共尝试推送10次，包含1次首次请求和9次重试请求。

重试间隔

5秒

每次重试的间隔时间，每间隔5秒重试一次。

请求超时时间

3秒

连接和读取您的接口的超时时间。

当满足以下任一条件时，系统将停止重试：

  • 您的接口成功返回200 OK状态码。
  • 已达到最大重试次数（10次），系统将停止推送该状态报告。

幂等校验

受网络等因素影响，可能导致重复回调，建议接收方根据transactionId字段进行幂等校验处理。