开放平台事件回调接口文档

一、简介

当您的应用接入我们的开放平台后，可以联系客服开发人员配置回调地址。当特定业务事件发生时，平台会以 HTTP POST 请求的方式，主动将事件数据推送到您配置的地址，实现业务数据的实时同步。

本文档描述了所有支持推送的事件类型、回调请求格式、响应规范以及注意事项。

二、支持的事件类型

平台目前支持推送以下 10 种事件：

2.1 活动相关事件

事件类型（event）	说明	推送时机
`ACTIVITY_PUBLISH`	活动发布	团长发布新活动时
`ACTIVITY_RESTART`	活动重启	已结束的活动重新启动时
`ACTIVITY_TERMINATE`	活动结束	活动到期或手动终止时

2.2 订单相关事件

事件类型（event）	说明	推送时机
`ORDER_PAY_SUCCESS_EVENT`	订单支付成功	用户完成订单支付时
`ORDER_SIGN_EVENT`	订单签收	买家签收商品时（支持部分签收）

2.3 售后/退款事件

事件类型（event）	说明	推送时机
`AS_CREATE`	售后申请创建	用户发起售后/退款申请时
`REVOKE`	售后撤销	用户主动撤销售后申请时
`REJECT`	退款被拒绝	商家拒绝退款申请时
`REFUND_SUCCESS`	退款成功	退款流程完成、资金到账时

三、回调请求格式

3.1 基本信息

项目	说明
请求方式	`POST`
数据格式	`application/json`
字符编码	`UTF-8`
协议支持	HTTP / HTTPS

3.2 通用请求体结构

所有回调请求的 Body 均为 JSON 格式，结构如下：

{
    "event": "事件类型",
    "actInfo": { },
    "orderInfo": { }
}

字段名	类型	必传	说明
`event`	String	是	事件类型，取值见第二节
`actInfo`	Object	否	活动信息，活动类事件时必传
`orderInfo`	Object	否	订单信息，订单/售后类事件时必传

说明：actInfo 和 orderInfo 同一时刻只有一个有值，另一个为 null。

四、数据字段详细说明

4.1 活动信息（actInfo）

当 event 为 ACTIVITY_PUBLISH、ACTIVITY_RESTART、ACTIVITY_TERMINATE 时，actInfo 字段结构如下：

{
    "actId": 123456
}

字段名	类型	说明
`actId`	Long	活动 ID

4.2 订单信息（orderInfo）

当 event 为订单或售后类事件时，orderInfo 字段结构如下：

{
    "orderNo": "20240101123456789",
    "returnOrderId": 987654321,
    "asOrderNo": 123456789,
    "partialSignItemList": [ ]
}

字段名	类型	说明
`orderNo`	String	订单号
`returnOrderId`	Long	退款单 ID
`asOrderNo`	Long	售后单号
`partialSignItemList`	Array	部分签收商品列表（见 4.3，签收事件时必传）

4.3 部分签收商品列表（partialSignItemList）

当 event 为 ORDER_SIGN_EVENT 且为部分签收时，partialSignItemList 字段结构如下：

[
    {
        "goodsId": 1001,
        "itemId": 2001,
        "goodsName": "商品名称",
        "signCount": 2
    }
]

字段名	类型	说明
`goodsId`	Long	商品 ID
`itemId`	Long	商品规格 ID
`goodsName`	String	商品名称
`signCount`	Integer	签收数量

五、响应规范

您的服务在收到回调请求后，需要按以下规范返回响应：

5.1 成功响应

项目	要求
HTTP 状态码	`200`
响应体	可选，建议返回 JSON 格式

建议的响应体格式：

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

5.2 失败响应

若您的服务返回 非 200 的 HTTP 状态码，平台会认为本次推送失败，并根据重试策略重新推送（详见第六节）。

六、重试与幂等

6.1 重试策略

项目	说明
最大重试次数	3 次
重试间隔	平台自动控制，采用退避策略
重试上限行为	超过 3 次后不再重试，消息丢弃

6.2 幂等性建议

由于网络波动或重试机制，您的服务可能会收到重复的回调请求。建议您：

根据 orderNo（订单号）或 returnOrderId（退款单 ID）做去重处理

使用数据库唯一索引或 Redis 缓存实现幂等控制

收到重复请求时直接返回成功（HTTP 200），避免平台反复重试

七、性能要求

为了保证回调的实时性和成功率，您的服务应尽量快速响应。平台的默认超时配置如下：

阶段	超时时间
建立连接	500 ms
获取响应数据	1000 ms

⚠️ 建议：您的服务应在 500ms 内完成处理并返回响应，避免因超时导致推送失败和反复重试。

八、回调地址配置

联系客服或者开发同学填写您的回调地址（支持 HTTP 和 HTTPS）

保存后生效，后续事件将自动推送到该地址

注意：请确保回调地址公网可访问，且支持 POST 请求接收 JSON 格式的 Body。

九、回调示例

9.1 活动发布

9.2 支付成功

9.3 退款成功

9.4 订单签收（部分签收）

十、常见问题

Q：如何判断回调请求的来源是否安全？
A：建议您在管理后台配置回调地址时，同时配置 Token，平台会在请求 Header 中携带签名，您的服务可以校验签名以确保请求来源可信。（如已支持签名机制，请补充校验方式）

Q：测试环境如何验证回调是否正常？
A：建议使用 webhook.site 或类似工具临时接收回调，确认数据格式符合预期后，再部署到正式环境。

Q：退款事件中的金额字段从哪里获取？
A：退款金额请通过 returnOrderId 调用平台查询接口获取，回调数据中不包含退款金额字段。

文档版本：v1.0 | 更新日期：2026-04-27

回调事件

开放平台事件回调接口文档#

一、简介#

二、支持的事件类型#

2.1 活动相关事件#

2.2 订单相关事件#

2.3 售后/退款事件#

三、回调请求格式#

3.1 基本信息#

3.2 通用请求体结构#

四、数据字段详细说明#

4.1 活动信息（actInfo）#

4.2 订单信息（orderInfo）#

4.3 部分签收商品列表（partialSignItemList）#

五、响应规范#

5.1 成功响应#

5.2 失败响应#

六、重试与幂等#

6.1 重试策略#

6.2 幂等性建议#

七、性能要求#

八、回调地址配置#

九、回调示例#

9.1 活动发布#

9.2 支付成功#

9.3 退款成功#

9.4 订单签收（部分签收）#

十、常见问题#