推送与回调机制
本文件定义开放平台主动推送(开放平台 → 开发者)与异步任务回调的通用规范:响应格式、推送机制与重试策略。订单消息推送、商品库存变更查询等接口均遵循本文件。
1. 响应要求
接收方收到推送/回调后,需在响应时满足以下要求,不符合的均会被认为推送/回调失败:
- HTTP 状态码为 200
- Header 中指定
Content-Type: application/json - Body 响应内容为如下 JSON 报文:
{
"status": "success"
}
接口响应时间不能超过 3 秒,否则开放平台会认为失败。
2. 推送机制
| 项目 | 说明 |
|---|---|
| 重试策略 | 推送失败后按递增间隔自动重试,间隔逐步拉长,最多重试 15 次(含首次共推送 16 次),全程最晚约 24 小时,具体间隔见第 3 节 |
| 幂等处理 | 若接收方已收到数据但未及时响应,平台也会认为失败并重试。再次重试时,接收方需要根据消息ID (msgId) 来应对不可接收重推消息的场景,完成幂等处理 |
| 消息兼容 | 为了方便未来消息升级,应用需要兼容消息中当前尚未定义但未来可能会新增的字段 |
3. 重试策略
推送失败后按如下递增间隔重试,间隔从短到长逐步拉大;最后一次重试结束后停止推送,全程最晚约 24 小时:
| 第几次重试 | 重试间隔 |
|---|---|
| 第 1 次 | 10 秒 |
| 第 2 次 | 15 秒 |
| 第 3 次 | 30 秒 |
| 第 4 次 | 3 分钟 |
| 第 5 次 | 10 分钟 |
| 第 6 次 | 20 分钟 |
| 第 7 次 | 30 分钟 |
| 第 8 次 | 30 分钟 |
| 第 9 次 | 30 分钟 |
| 第 10 次 | 1 小时 |
| 第 11 次 | 3 小时 |
| 第 12 次 | 3 小时 |
| 第 13 次 | 3 小时 |
| 第 14 次 | 6 小时 |
| 第 15 次 | 6 小时 |