# 一、物流消息能力简介
物流消息是微信官方为小程序提供的免费物流消息通知接口。
接入后,你可以使用本接口传入小程序订单发货信息,微信后台会跟踪运单的状态变化,在「已揽件」、「派件中」、「已签收」这三个关键物流节点给下单用户推送消息通知,同时用户可以通过消息回访商家小程序,提升购物体验。
应用举例:
A小程序业务为美妆自营,需向用户邮寄对应订单商品。接入消息开放能力前,用户常反馈下单之后找不到订单信息,不清楚物流状态;接入消息开放能力后,用户在该小程序下的单,会收到微信下发的快件已揽件、派件中、已签收的服务通知,订单信息和物流状态一目了然。
服务通知/落地页样式:
# 二、准入要求及监管处罚
满足以下所有条件的小程序才可进行申请使用
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 | 代签收 |