物流查询插件简介

「物流查询插件」是微信官方提供的商家经营工具。通过调用该插件,商家可以在小程序中展示订单物流信息,当物流状态发生改变时,给用户下发消息通知。 按照下面的使用说明接入,在你的小程序中引入「物流查询组件」即可实现。使用过程中如遇到问题,可在微信开放社区 发帖交流。 #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: '', //通过后台接口获取到的值
	},
	// 在此通过调用api来查询微信快递服务详情
	searchDetail:(){
		const {waybillToken} = this.data;
 		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 收件人手机号,部分运力需要用户手机号作为查单依据
waybill_id string 运单号
goods_info object 商品信息
trans_id string 交易单号

*本次更新点: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" ,
  "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 商品名称
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"
                }
            ]
        }
    }
}

更新物流信息接口 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 商品名称
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 代签收