物流查询插件简介 | 微信开放文档

# 物流查询插件简介

「物流查询组件」是微信官方提供的商家经营工具。通过调用该组件，商家可以在小程序中展示订单物流信息，当物流状态发生改变时，给用户下发消息通知。组件权限开通：小程序MP-功能-物流服务-申请开通「查询组件」。开通权限后，按照下面的使用说明接入，在你的小程序中引入「物流查询组件」即可实现。使用过程中如遇到问题，可在微信开放社区发帖交流。 #50%

# 申请资质及监管处罚

满足以下所有条件的小程序才可进行申请使用：
1，需要开通了微信支付的小程序
2，过去30 天有交易
3，类目（内测暂不需要）
频次限制
1，一个 appid 最多调用10w 次/日
2，一个用户最多调用 100次/日
监管及处罚
1）仅支持查询「引用查询组件的小程序」产生的购物订单的物流运单。
2）仅支持给「已订阅微信快递服务」且订单实际购买者下发消息。
若违反监管条理，进行相应处罚，包括但不限于降低调用频次、禁用插件能力等。

# 插件引入说明

当服务商调用时请使用第三方平台接口调用令牌authorizer_access_token以调用接口。

# 1. 「物流查询插件」如何引入

在小程序的app.json中声明

"logisticsPlugin": {
      "version": "2.1.5",
      "provider": "wx9ad912bf20548d92"
}

# 2. 「物流查询插件」如何使用

然后在需要使用插件api的js文件中引入插件包，如test.js

插件API 名： openWaybillTracking 参数为waybillToken：通过后台接口(- ：https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/trace_waybill?access_token=XXX)返回的 waybill_token（开发者进行存储，后续用这个token来进行查询物流单）

必须用预览才能测试这个功能，无法在工具端模拟

调用示例：

var plugin = requirePlugin("logisticsPlugin")

Page({
	data:{
		waybillToken: '', //通过后台接口获取到的值
	},

	searchDetail:(){
		const {waybillToken} = this.data;
    // 在此通过调用api来查询微信快递服务详情
    //必须用预览才能测试这个功能，无法在工具端模拟
 		plugin.openWaybillTracking({
     			waybillToken: waybillToken
		});
	}
})

# 后台API 接口说明

已引用「物流查询」插件的商家，才可调用后台 API。

# 1. 接口鉴权

微信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的生成与管理方法见：后台接口调用凭证说明

# 2.接口列表

# 传运单接口 trace_waybill

描述：商户使用此接口向微信提供某交易单号对应的运单号。微信后台会跟踪运单的状态变化
请求方法： POST application/json
请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/trace_waybill?access_token=XXX
请求参数

参数名称	类型	必选	备注
openid	string	是	用户openid
sender_phone	string	否	寄件人手机号
receiver_phone	string	是	收件人手机号，部分运力需要用户手机号作为查单依据
delivery_id	string	否	运力id（运单号所属运力公司id），该字段从 get_delivery_list 获取。该参数用于提高运单号识别的准确度；特别是对非主流快递公司，建议传入该参数，确保查询正确率。
waybill_id	string	是	运单号
goods_info	object	是	商品信息
trans_id	string	是	交易单号（微信支付生成的交易单号，一般以420开头）
order_detail_path	string	否	点击落地页商品卡片跳转路径（建议为订单详情页path），不传默认跳转小程序首页。

*本次更新点：sender_phone，receiver_phone。

其中goods_info的内容如下：

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

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

参数名称	类型	必选	备注
goods_name	string	是	商品名称
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" ,
  "delivery_id":"KYSY",
  "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"
}

# 查询运单接口 query_trace

描述：商户在调用完trace_waybill接口后，可以使用本接口查询到对应运单的详情信息
请求方法： POST application/json
请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/query_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	是	商品名称(最大长度为utf-8编码下的60个字符）
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"
                }
            ]
        }
    }
}

# 获取运力id列表get_delivery_list

描述：商户使用此接口获取所有运力id的列表
请求方法： POST application/json
请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/get_delivery_list?access_token=XXX
请求参数 {}
返回参数

参数名称	类型	必选	备注
errcode	number	是	返回码
delivery_list	array	是	运力公司列表
count	number	是	运力公司个数

示例请求参数

{}

返回参数

{
    "errcode": 0,
    "delivery_list": [
      {
          "delivery_id": "(AU)",
          "delivery_name": "Interparcel"
      },
      {
          "delivery_id": "BDT",
          "delivery_name": "八达通"
      },
      {
          "delivery_id": "YD",
          "delivery_name": "韵达速递"
      },
      ...
    ],
    "count": 1379
}

# 更新物流信息接口 update_waybill_goods

描述：更新物品信息
请求方法： POST application/json
请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/open_msg/update_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"
}

# 3. 接口错误码

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

# 4. 运单状态

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