API文档中心

开发文档

概念术语 获取access_token 计算签名 响应与限制 示例与SDK

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": "adc7a8960911564e89ce69fd92546aaa",
    "type": 10,
    "timestamp": 1514881277,
    "message": "{\"orderId\":\"2017110247588788\",\"out_order_sn\":\"2318382138218321\",\"status\":\"PROCESSING\"}",
    "requestId": "500de32715fcbd646ab02e807c7a840d",
    "sig": "df9991499abc3ce575ef1778c970de22"
}

参数说明

字段 类型 描述
requestId string 推送消息ID
type Number 消息类型,参加下方【消息类型】
message String JSON格式字符串,每种类型消息的结构体内容不一样,具体以对应类型定义的消息体为准。当消息结构体的字段增加时,开放平台不会主动通知,请开发者在进行JSON反序列化时做好未知字段解析兼容。
app_key string 应用APP Key
timestamp Number 消息发送的时间戳,每次推送时生成,单位毫秒
sig string 消息签名,32位

 

 

消息类型

type 名称 分类 说明
10 订单状态改变 订单类 订单状态扭转改变

订单状态改变message参数说明

字段 类型 描述
orderId string 转单宝订单ID
out_order_sn string 外部订单编号(应用商家自由订单编号)
status String 订单状态:WAIT_PAY 待支付,WAIT_CONFIRM 待接单,WAIT_DELIVERY 待配送,WAIT_SIGNED 配送中,WAIT_CHECKOUT 已送达,FINISHED 已结算, CANCELED 已取消, REFUND 已退款,RETURN_GOODS 已退货,EXCHANGE_GOODS 已换货

 

 

消息签名验证规则

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

 

新手指南
咨询建议
在线客服