# 一、物流消息能力简介

物流消息是微信官方为小程序提供的免费物流消息通知接口。
接入后,你可以使用本接口传入小程序订单发货信息,微信后台会跟踪运单的状态变化,在「已揽件」、「派件中」、「已签收」这三个关键物流节点给下单用户推送消息通知,同时用户可以通过消息回访商家小程序,提升购物体验。

应用举例:
A小程序业务为美妆自营,需向用户邮寄对应订单商品。接入消息开放能力前,用户常反馈下单之后找不到订单信息,不清楚物流状态;接入消息开放能力后,用户在该小程序下的单,会收到微信下发的快件已揽件、派件中、已签收的服务通知,订单信息和物流状态一目了然。

服务通知/落地页样式:

#70%

# 二、准入要求及监管处罚

满足以下所有条件的小程序才可进行申请使用
1、小程序有发布上线
2、小程序有开通微信支付,且近90天线上交易笔数大于0

频次限制
1、同一 appid 最多调用10w 次/日
2、同一用户最多被调用 50次/日
3、同一用户最多同时绑定100 个运单号,有效绑定判定逻辑:运单号处于「揽件中、运输中、派送中、待签收」状态时,算作有效绑定。

监管及处罚
1、仅支持传入合法合规的商品图片、商品信息,禁止广告/色情/政治等内容。
2、仅支持传入小程序真实订单信息,仅支持给订单实际下单人下发消息。
若违反监管条理,微信官方将进行相应处罚,包括但不限于降低接口调用频次、禁用接口能力等。

# 三、接口鉴权

微信api接口默认使用access_token进行接口鉴权。因此需要在所有的api接口地址后加上参数access_token。
例如:
原始调用地址为:https://api.weixin.qq.com/cgi-bin/test/api
最终实际的调用地址需要加上access_token参数,即:https://api.weixin.qq.com/cgi-bin/test/api?access_token=xxxxxx
其中access_token的生成与管理方法见:后台接口调用凭证说明

# 四、接口列表

# 4.1、传运单接口 follow_waybill

  • 描述:商户使用此接口向微信提供某交易单号对应的运单号。微信后台会跟踪运单的状态变化,在关键物流节点给下单用户推送消息通知。
  • 请求方法: POST application/json
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/follow_waybill?access_token=XXX
  • 请求参数
参数名称 类型 必选 备注
openid string 用户openid
sender_phone string 寄件人手机号
receiver_phone string 收件人手机号,部分运力需要用户手机号作为查单依据
waybill_id string 运单号
goods_info object 商品信息
trans_id string 交易单号(微信支付生成的交易单号,一般以420开头)
order_detail_path string 点击落地页商品卡片跳转路径(建议为订单详情页path),不传默认跳转小程序首页。

其中goods_info的内容如下:

参数名称 类型 必选 备注
detail_list array 商品信息

其中goods_info.detail_list的每一项的内容如下:

参数名称 类型 必选 备注
goods_name string 商品名称(最大长度为utf-8编码下的60个字符)
goods_img_url string 商品图片url
goods_desc string 商品详情描述,不传默认取“商品名称”值,最多40汉字
  • 返回参数
参数名称 类型 必选 备注
errcode number 返回码
errmsg string 错误信息
waybill_token string 查询id
  • 示例

请求参数

{
  "openid":"ovtZW4yB7DIj3CxOb6ii-nk4HhFo",
  "waybill_id":"WXTESTEXPRESS0000014",
  "sender_phone":"12345678901" ,
  "receiver_phone":"123456566" ,
  "goods_info":{
  	"detail_list":[
     {
       "goods_name":"测试名字",
       "goods_img_url":"www.qq.com"
     },
     {
       "goods_name":"测试名字2",
       "goods_img_url":"www.qq.com"
     }
    ]
  }
}

返回参数

{
    "errcode": 0,
    "errmsg": "ok",
    "waybill_token": "o_ARWHaxIxzWHmdui-AIw9KBr8qNnbmc08V0KhDyXE-IMLo6AcOqJkPsNLcLzfTb"
}

# 4.2、查运单接口 query_follow_trace

  • 描述:商户在调用完trace_waybill接口后,可以使用本接口查询到对应运单的详情信息
  • 请求方法: POST application/json
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/query_follow_trace?access_token=XXX
  • 请求参数
参数名称 类型 必选 备注
waybill_token string 查询id
  • 返回参数
参数名称 类型 必选 备注
errcode number 返回码
errmsg string 错误信息
waybill_info object 运单信息
shop_info object 商品信息
delivery_info object 运力信息

其中waybill_info内容如下:

参数名称 类型 必选 备注
status number 运单状态,见运单状态
waybill_id string 运单号

其中shop_info的内容如下:

参数名称 类型 必选 备注
goods_info object 商品信息

其中shop_info.goods_info的内容如下:

参数名称 类型 必选 备注
detail_list array 商品详情

其中shop_info.goods_info.detail_list的每一项内容如下:

参数名称 类型 必选 备注
goods_name string 商品名称
goods_img_url string 商品图片url

其中delivery_info的内容如下:

参数名称 类型 必选 备注
delivery_id string 运力公司 id
delivery_name string 运力公司名称
  • 示例

请求参数

{
  "waybill_token":"o_ARWHaxIxzWHmdui-AIw8SuE1QtaUZK8aUnZguAn1nsZ72ZjWlq8btV8j-wAc94",
  "openid":"ovtZW4yB7DIj3CxOb6ii-nk4HhFo"
}

返回参数

{
    "errcode": 0,
    "errmsg": "ok",
    "waybill_info": {
        "status": 0,
        "waybill_id": "WXTESTEXPRESS0000014"
    },
    "shop_info": {
        "goods_info": {
            "detail_list": [
                {
                    "goods_name": "测试名字",
                    "goods_img_url": "www.qq.com"
                },
                {
                    "goods_name": "测试名字2",
                    "goods_img_url": "www.qq.com"
                }
            ]
        }
    }
}

# 4.3、更新物品信息接口 update_follow_waybill_goods

  • 描述:更新物品信息
  • 请求方法: POST application/json
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/update_follow_waybill_goods?access_token=XXX
  • 请求参数
参数名称 类型 必选 备注
waybill_token string 查询id
goods_info object 商品信息

其中goods_info的内容如下:

参数名称 类型 必选 备注
detail_list array 商品信息

其中goods_info.detail_list的每一项的内容如下:

参数名称 类型 必选 备注
goods_name string 商品名称(最大长度为utf-8编码下的60个字符)
goods_img_url string 商品图片url
  • 返回参数
参数名称 类型 必选 备注
errcode number 返回码
errmsg string 错误信息
  • 示例

请求参数

{
  "waybill_token":"o_ARWHaxIxzWHmdui-AIw8SuE1QtaUZK8aUnZguAn1nsZ72ZjWlq8btV8j-wAc94",
  "openid":"ovtZW4yB7DIj3CxOb6ii-nk4HhFo",
  "goods_info":{
     "detail_list":[
        {
         "goods_name":"测试更新商品" ,
         "goods_img_url":"www.qq.com"
        }
     ]
  }
}

返回参数

{
    "errcode": 0,
    "errmsg": "ok"
}

# 五、接口错误码

错误码 释义
-1 系统错误
9300560 达到修改次数上限
40003 openid参数错误
9300534 access_token与openid参数不匹配
9300513 调用次数达到上限
9300507 waybill_token参数错误
9300559 运单不存在

# 六、运单状态

运单状态 释义
0 运单不存在或者未揽收
1 已揽件
2 运输中
3 派件中
4 已签收
5 异常
6 代签收