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

# 物流查询插件简介

「物流查询插件」是微信官方提供的商家经营工具。通过调用该插件，商家可以在小程序中展示订单物流信息，当物流状态发生改变时，给用户下发消息通知。按照下面的使用说明接入，在你的小程序中引入「物流查询组件」即可实现。使用过程中如遇到问题，可在微信开放社区发帖交流。 #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接口的delivery_id。该参数用于增加识别的正确率，比如对于一些市面上小众的运力公司以及国外的运力公司可以填这个参数。
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

返回参数

参数名称	类型	必选	备注
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	代签收