API文档中心
开发文档
API文档
店铺服务
订单管理
转单售后
消息服务
字典服务
消息推送
消息推送是开放平台主动调用开发者服务的一个通道，用于向应用推送订单状态变更等相关消息。开发者需要在API应用设置中填写有效的回调地址，当有消息产生时，开发平台会向设置的URL发送HTTP POST数据，达到通知应用的目的。
推送流程
1、首先要注册为平台的API应用，获取对应的KEY等信息
2、设置API消息回调地址
3、通过API应用下单或者转单宝平台下单后，接单店铺接单订单状态发生改变，如应用设置了回调地址(设置回调地址)，则平台会向应用设置的推送URL推送这个新订单消息
推送协议及规范
当有开通API应用的店铺有订单状态改变等对应的消息产生时，开放平台会通过请求应用设置的消息回调地址进行消息的投递。
1、开放平台以HTTP POST 的方式进行消息推送请求
2、开放平台消息推送请求的HTTP Header中的Content-Type:application/json; charset=utf-8
3、推送请求的HTTP Body为JSON格式，具体数据格式参见下方文档。
4、为了防止推送消息被篡改，开放平台进行推送的时候会有简单签名，签名规则见下方【签名规则】，应用需要自行校验消息数据
5、应用在消息处理完成后，需要回复HTTP Response的code 200 以及body为{“data”:“ok”}，表示此次推送消息接收成功。
6、推送请求如果10s内没有收到响应头为200响应，平台认为此次推送不成功，不管因为什么原因，平台都会在一分钟后重新发起推送（总推送次数不超过2次（<=2））
7、应用收到推送HTTP请求后，必须在10s内完成响应，否则平台认为超时响应，会重复推送，造成双方资源浪费
8、应用需要自行处理重复推送造成的消息重复，要求幂等，每个消息都有一个唯一的requestId，方便消息去重
9、为了方便未来的消息内容升级，应用需要兼容处理当前消息中不存在的字段。
10、应用需要支持推送地址的GET访问，当GET请求访问时，请直接返回{“data”:“ok”}，用于推送地址的可用性测试
推送消息结构示例：
{
"app_key":"1234566789000765433333",
"message":{"order_no":"20230920755127813","out_order_sn":"6921955445912245872","quote_store_num":1,"order_status":"WAIT_CONFIRM","status":"WAIT_CONFIRM"},
"requestId":"a1f12dd6-e1c3-4460-a183-ec5fd4e616cd",
"timestamp":1695183315,
"type":30,
"sig":"86f1f869849477e8a1a937bfdf656c66"
}
参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| requestId | string | 推送消息ID |
| type | Number | 消息类型，参加下方【消息类型】 |
| message | String | JSON格式字符串，每种类型消息的结构体内容不一样，具体以对应类型定义的消息体为准。当消息结构体的字段增加时，开放平台不会主动通知，请开发者在进行JSON反序列化时做好未知字段解析兼容。 |
| app_key | string | 应用APP Key |
| timestamp | Number | 消息发送的时间戳，每次推送时生成，单位毫秒 |
| sig | string | 消息签名，32位 |
消息类型
| type | 名称 | 分类 | 说明 |
|---|---|---|---|
| 10 | 订单状态改变 | 订单类 | 订单状态改变 |
| 20 | 订单售后回调 | 售后类 | 订单售后状态变更 |
| 30 | 店铺报价回调 | 订单类 | 订单有用户报价的时候触发 |
| 40 | 实物照上传回调 | 订单类 | 接单方上传实物照后触发 |
订单状态改变message参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| order_sn | string | 转单宝订单编号 |
| out_order_sn | string | 外部订单编号(应用商家自由订单编号) |
| order_status | String | 订单状态：WAIT_PAY 待支付，WAIT_CONFIRM 待接单，WAIT_DELIVERY 待配送，WAIT_SIGNED 配送中，WAIT_CHECKOUT 已送达，FINISHED 已结算， CANCELED 已取消， REFUND 已退款，RETURN_GOODS 已退货，EXCHANGE_GOODS 已换货 |
| order_amount | int | 转单价格 |
转单售后message参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| order_sn | string | 转单宝订单编号 |
| out_order_sn | string | 外部订单编号(应用商家自由订单编号) |
| order_status | String | 订单状态：WAIT_PAY 待支付，WAIT_CONFIRM 待接单，WAIT_DELIVERY 待配送，WAIT_SIGNED 配送中，WAIT_CHECKOUT 已送达，FINISHED 已结算， CANCELED 已取消， REFUND 已退款，RETURN_GOODS 已退货，EXCHANGE_GOODS 已换货 |
| refund_amount | int | 转单售后退赔总金额 |
| status | int | 转单售后状态：0 待受理，10 已驳回，20 仲裁待受理，30 仲裁待申诉， 40 申诉待处理， 60 达成售后， 65 仲裁成立， 70 已撤销售后， 75 仲裁不成立 |
门店报价message参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| order_sn | string | 转单宝订单编号 |
| out_order_sn | string | 外部订单编号(应用商家自由订单编号) |
| order_status | String | 订单状态：WAIT_PAY 待支付，WAIT_CONFIRM 待接单，WAIT_DELIVERY 待配送，WAIT_SIGNED 配送中，WAIT_CHECKOUT 已送达，FINISHED 已结算， CANCELED 已取消， REFUND 已退款，RETURN_GOODS 已退货，EXCHANGE_GOODS 已换货 |
| quote_store_num | int | 报价门店数量 |
实物照message参数说明
| 字段 | 类型 | 描述 |
|---|---|---|
| order_sn | string | 转单宝订单编号 |
| out_order_sn | string | 外部订单编号(应用商家自由订单编号) |
| order_status | String | 订单状态：WAIT_PAY 待支付，WAIT_CONFIRM 待接单，WAIT_DELIVERY 待配送，WAIT_SIGNED 配送中，WAIT_CHECKOUT 已送达，FINISHED 已结算， CANCELED 已取消， REFUND 已退款，RETURN_GOODS 已退货，EXCHANGE_GOODS 已换货 |
| physical_photos | array | 接单门店上传的实物照数据 |
消息签名验证规则
1、应用将接收到的POST Body，进行json反序列化解析转换成数组
2、将解析得数组，移除sig字段
3、将上一步得到的数组的key，按照字母序进行排序
4、将上一步排序后的数组，遍历拼接字符串，格式如：key1=value1&key2=value2&key3=...
5、将上一步得到的字符串前拼接app_secret?
6、将上一步得到的字符串后拼接app_secret
7、将上一步得到的字符进行MD5哈希
8、校验签名是否正确
PHP示例代码
计算签名示例：
| 函数 | 作用 |
|---|---|
| concatParams | 将输入参数排序并用&连接 |
| genSig | 通过给定的app_secret, params计算出sig |
function concatParams($params) {
ksort($params);
$pairs = [];
foreach($params as $key=>$val) {
$pairs[] = $key . '=' . $val;
}
return implode('&',$pairs);
}
function genSig($app_secret, $params) {
$params = self::concatParams($params);
$str = $app_secret.'?'.$params.$app_secret;
return md5($str);
}