回调通知消息说明

一、推送方式

1.1 推送说明

开放平台向接入商推送实时的业务变更消息，保持数据的一致性以及同步，满足接入商业务需求，避免轮询。推送的数据消息，将以 HTTP POST 的方式向该推送地址发起调用，把数据推送给接入商。接入商接收消息，需要回执（参见回执）。接收失败时，消息中心会自动重发（参见生命周期）。

1.2 生命周期

一般情况下，1小时以内完成4次通知，通知的间隔频率一般是：每分钟2次。超过最大重试次数（5次）后将停止推送。

重试次数	间隔时间
第 1 次	立即
第 2 次	2 分钟后
第 3 次	2 分钟后
第 4 次	2 分钟后
第 5 次	2 小时后

1.3 回执

如果收到消息，并处理成功，需返回如下 JSON 字符串：

{ "code": 20000, "msg": "success" }

除此之外，都会判定为失败。当失败时，会根据生命周期，重新通知。

1.4 幂等处理

由于消息存在重试机制，同一消息（相同 X-Message-ID）可能多次发送（网络原因、商户服务器原因、或者商户接受处理成功但并未按要求回执等），消息接收方需要对同一个 X-Message-ID 的多次消息投递实现幂等。若之前相同的 X-Message-ID 已处理成功，直接返回成功回执即可。

1.5 安全处理

上线后需要通过传递的签名是否正确来判断推送安全。我方推送的消息会在 Header 中携带以下签名信息：

Header 参数	说明	示例
X-Message-ID	消息唯一 ID（用于幂等性处理）	1234567890123456789
Signature-Data	消息签名（Base64 编码）	a1b2c3d4e5f6g7h8...

签名计算规则：

将回调的 JSON 数据拼接 secretKey（渠道密钥）

对拼接后的字符串进行 MD5 加密

将 MD5 值进行 Base64 编码

接入商收到消息后，使用相同的算法计算签名，与 Header 中的 X-Sign 进行比对，验证消息的真实性。

验签示例代码：

1.6 建议处理方式

接收消息后，先验证签名是否合法

检查 X-Message-ID 是否已处理过，避免重复处理

处理业务逻辑（更新订单状态、发送通知等）

处理成功后，返回标准成功响应 {"code":200,"msg":"success"}

记录处理日志，便于问题排查

二、推送格式

2.1 消息模板参数说明

所有回调消息都遵循统一的格式：

字段	类型	必填	说明
id	Long	是	消息 ID（与 X-Message-ID 一致）
pushTime	Long	是	推送时间戳（毫秒）
type	String	是	消息类型（见下方类型说明）
data	Object	是	业务数据，具体结构见各类型说明

消息类型说明：

类型值	说明	触发时机
order.create	订单创建	订单创建成功后
order.cancel	订单取消	订单被取消时
order.delivery	订单已发货	供应商发货后
order.delivered	订单已收货	订单确认收货后
afterSale.agree	售后同意	售后申请被同意时
afterSale.success	售后退款到账	售后退款完成后
goods.onSale	商品上架	商品开启售卖后
goods.stopSale	商品下架	商品停止售卖后
goods.update	商品修改	商品信息被修改时
goods.stockChange	商品库存变更	商品库存变更时
goods.storehouseChange	选品库商品变更	添加或移除选品库商品时

2.2 订单消息模板 JSON 示例

触发时机：订单创建成功后

{
    "id": 1234567890123456789,
    "pushTime": 1716364800000,
    "type": "order.create",
    "data": {
        "orderSn": "ORD20260522001",
        "sn": "THIRD20260522001",
        "status": 2
    }
}

字段说明：

字段	类型	说明
data.orderSn	String	系统订单号
data.sn	String	第三方订单号
data.status	Integer	订单状态（1-待支付，2-待发货）

三、常见问题

3.1 未收到回调通知

排查步骤：

检查回调地址是否配置正确

检查服务器防火墙是否放行

检查回调接口是否正常响应（必须返回 {"code":20000,"msg":"success"}）

查看我方系统的回调日志

3.2 签名验证失败

排查步骤：

检查 secretKey 是否正确

检查签名计算顺序是否正确（JSON + secretKey → MD5 → Base64）

检查 JSON 字符串是否与接收的一致（注意空格、换行等）

3.3 消息重复处理

排查步骤：

检查是否正确实现了幂等性处理

检查是否使用 X-Message-ID 进行去重

检查 Redis 或数据库缓存是否正常工作

四、技术支持

4.1 联系方式

技术支持邮箱：tech-support@example.com

技术支持电话：400-xxx-xxxx

工作日：周一至周五 9:00-18:00

4.2 问题反馈

遇到问题时，请提供以下信息：

businessId

消息 ID（X-Message-ID）

接收时间

回调地址

错误信息或截图

问题描述

文档维护：技术团队
最后更新：2026-05-22
文档版本：v1.0

消息说明

回调通知消息说明#

一、推送方式#

1.1 推送说明#

1.2 生命周期#

1.3 回执#

1.4 幂等处理#

1.5 安全处理#

1.6 建议处理方式#

二、推送格式#

2.1 消息模板参数说明#

2.2 订单消息模板 JSON 示例#

三、常见问题#

3.1 未收到回调通知#

3.2 签名验证失败#

3.3 消息重复处理#

四、技术支持#

4.1 联系方式#

4.2 问题反馈#

回调通知消息说明

一、推送方式

1.1 推送说明

1.2 生命周期

1.3 回执

1.4 幂等处理

1.5 安全处理

1.6 建议处理方式

二、推送格式

2.1 消息模板参数说明

2.2 订单消息模板 JSON 示例

三、常见问题

3.1 未收到回调通知

3.2 签名验证失败

3.3 消息重复处理

四、技术支持

4.1 联系方式

4.2 问题反馈