# 物流查询插件简介

「物流查询插件」是微信官方提供的商家经营工具。通过调用该插件,商家可以在小程序中展示订单物流信息,当物流状态发生改变时,给用户下发消息通知。 按照下面的使用说明接入,在你的小程序中引入「物流查询组件」即可实现。使用过程中如遇到问题,可在微信开放社区 发帖交流。 #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
  • 返回参数
参数名称 类型 必选 备注
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 代签收