hi,欢迎来到转单宝! 您好,请登录 免费注册

消息推送

消息推送是开放平台主动调用开发者服务的一个通道,用于向应用推送订单状态变更等相关消息。开发者需要在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 店铺报价回调 订单类 订单有用户报价的时候触发

 

订单状态改变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 报价门店数量

 

消息签名验证规则

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);    
}