# 手机号物流消息推送

微信物流服务开放「手机号物流消息推送」功能,接入该能力的快递公司可对绑定了微信快递服务的用户推送物流变更消息,用户收到物流变更的消息后,进入消息详情页可收藏、分享,或跳转该快递公司的小程序。

# 产品优势

1、授权微信快递服务的用户,可查收该用户手机号名下快递运单详情和变更消息;

2、快递公司可以节省快递状态变更通知用户的短信成本。


# 接入流程

# 1.邮件申请

发送申请邮件至wxwuliu@tencent.com

【邮件标题】 快递公司名称 - 手机号物流消息推送接入申请

【邮件内容】 每日运单量、小程序appid(小程序需要完成微信认证)

【邮件附件】《营业执照》、《快递业务经营许可证》扫描件

我们会在收到邮件后的1个工作日内进行反馈。

# 2.协议签署

符合接入要求的快递公司,会收到邮件回复,包含接入指引和《合作协议》。

# 3.开发调试

  • 按照本接口文档设计和开发,其中部分信息需要由微信协助配置
  • 以邮件和微信群形式沟通

# 4.审核发布

接口开发完成,微信侧确认,通过性能和安全审核后发布,发布后的页面所有用户可以扫码查看。


# 接入前准备

# 1.快递信息查询接口

用以微信前端通过JsonP 方式获取运单的信息

# 2.落地页 Cell 信息

快递公司需要提供一组 Cell 的信息,每个 Cell 包括:

  • “Key”:Cell 的标识码,快递公司自定义, 不超过 20 字符
  • “Name”:Cell 展示的名称,如“支付运单”
  • “Link”:Cell 点击外跳的 url 地址

# 接口开发文档

# 1.流程

# 1.1查模式流程

运力侧的主要逻辑为3-8步骤。首先用户可以在推送物流消息前对用户绑定状态进行查询,在存在绑定关系的情况下可以对轨迹变化进行通知。调用通知接口后微信会先进行一次反查,在确定状态无误的情况下微信会将物流轨迹推送至用户手机。


# 2.运力侧接入需要提供的内容

  • 运力小程序appid(用于调用微信API,并接收微信回调)

# 3.运力侧需要开发的内容

# 3.1、主调

  • 查询用户绑定关系(必需)
  • 推送物流轨迹通知(必需)

# 3.2、被调

  • 微信反查运单接口(必需)

# 4.接口

# 4.1、action_type定义

说明
90001 揽件前阶段 - 网点接单
90002 揽件前阶段 - 分配业务员
90003 揽件前阶段 - 重新分配业务员
90010 揽件前阶段 - 待支付
90011 揽件前阶段 - 已支付
100001 揽件阶段 - 揽件成功
100002 揽件阶段 - 揽件失败
200001 运输阶段 - 更新运输轨迹
300002 派送阶段 - 派送中
300003 派送阶段 - 签收成功
300004 派送阶段 - 签收失败
300005 派送阶段 - 第三方代收入库
300006 派送阶段 - 第三方代收快递员取出
300007 派送阶段 - 代签收
400001 异常阶段 - 订单取消
400002 异常阶段 - 订单滞留
400003 异常阶段 - 订单退回
400004 异常阶段 - 订单拒收
400005 异常阶段 - 问题件
500001 兜底状态 - 其他未分类状态纳入本action_type

# 4.2、callback接口

消息推送说明 https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/message-push.html 推荐选择加密模式

# 查询订单状态
  • 描述:微信在收到运力方的消息推送请求后会反查一次当前单的状态,如果与请求一致时则会推送
  • 请求参数
参数名称 类型 必选 备注
ToUserName string 快递公司小程序UserName
FromUserName string 微信团队的OpenID(固定值)
CreateTime number 事件时间,Unix时间戳如1599823049
MsgType string 消息类型,固定为event
Event string 事件类型,固定为waybill_notify_query,不区分大小写
WaybillId string 运单号
SenderPhone string 寄件人手机号
ReceiverPhone string 收件人手机号

具体数据格式可能是json,也可能是xml,由小程序在 mp 平台配置的情况决定。 示例:

<xml>
<ToUserName>gh_ea48699fb159</ToUserName>
<FromUserName>oHt_80DRclK4qjKfdYnPg6RxxsNI</FromUserName>
<MsgType>event</MsgType>
<Event>waybill_notify_query</Event>
<CreateTime>1600152165</CreateTime>
<WaybillId>557007127498128</WaybillId>
<SenderPhone>13763357711</SenderPhone>
<ReceiverPhone>13763357711</ReceiverPhone>
</xml>
  • 返回参数:
参数名称 类型 必选 备注
ToUserName string 原样返回请求中的FromUserName
FromUserName string 快递公司小程序UserName
CreateTime number 事件时间,Unix时间戳
MsgType string 消息类型,固定为event
Event string 事件类型,固定为waybill_notify_query,不区分大小写
ResultCode number 处理结果错误码,成功时返回0,异常时由运力自定义
ResultMsg string 处理结果的详细信息,错误提示
Path array 所有物流轨迹
WaybillCreateTime number 运单创建时间,秒级时间戳如1599823049

其中 path 的每一项的内容如下

参数名称 类型 必选 备注
ActionTime number 轨迹变化 Unix 时间戳,如1599823049
ActionType number 轨迹变化类型,与普通单保持一致,参见action_type定义
ActionMsg string 轨迹变化具体信息说明,展示在快递轨迹详情页中。若有手机号码,则直接写11位手机号码。使用UTF-8编码。
PickupCourierName string 取件员姓名,当分配取件员成功时返回
PickupCourierPhone string 取件员电话,当分配取件员成功时返回
DeliveryCourierName string 派件员姓名,当分配派件员成功时返回
DeliveryCourierPhone string 派件员电话,当分配派件员成功时返回

示例:

<xml>
<ToUserName>gh_ea48699fb159</ToUserName>
<FromUserName>oHt_80DRclK4qjKfdYnPg6RxxsNI</FromUserName>
<MsgType>event</MsgType>
<Event>waybill_notify_query</Event>
<CreateTime>1600152165</CreateTime>
<ResultCode>0</ResultCode>
<ResultMsg>OK</ResultMsg>
<WaybillCreateTime>1600000000</WaybillCreateTime>
<Path>
<ActionType>300001</ActionType>
<ActionTime>1600000000</ActionTime>
<ActionMsg>派送中</ActionMsg>
<DeliveryCourierName>张三</DeliveryCourierName>
<DeliveryCourierPhone>10086</DeliveryCourierPhone>
</Path>
<Path>
<ActionType>100001</ActionType>
<ActionTime>1600000000</ActionTime>
<ActionMsg>已取件</ActionMsg>
</Path>
</xml>

# 5.3、api接口

# 接口鉴权

微信 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的生成与管理方法见:后台接口调用凭证说明 https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/access-token/auth.getAccessToken.html

# 用户手机状态查询
  • 描述:运力方可以调用此接口来获取某手机号是否绑定
  • 请求方法: POST application/json
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/userquery?access_token=XXX
  • 请求参数
参数名称 类型 必选 备注
phone string 手机号
  • 返回参数
参数名称 类型 必选 备注
errcode number 返回码
errmsg string 错误信息
exist number 用户是否绑定 0-未绑定 1-已绑定
  • 示例
{
"phone":"13800138000"
}
# 推送已绑定物流轨迹信息
  • 描述:运力方可以调用此接口来推送物流轨迹消息
  • 请求方法: POST application/json
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/pathnotify?access_token=XXX
  • 请求参数
参数名称 类型 必选 备注
sender object 寄件人
receiver object 收件人
waybill_id string 运单号
path object 当前需要推送消息的轨迹
create_time int 运单创建时间,unix时间戳(秒)

其中 sender 与receiver的内容如下:

参数名称 类型 必选 备注
name string 姓名(收件人必传,寄件人非必传)
phone string 电话(收件人必传,寄件人非必传)
province string
city string
area string 区/县
street string 街道
address string 地址
id string 地址id

其中 path 的内容如下

参数名称 类型 必选 备注
action_time number 轨迹变化 Unix 时间戳
action_type number 轨迹变化类型,与普通单保持一致,参见action_type定义
action_msg string 轨迹变化具体信息说明,展示在快递轨迹详情页中
pickup_courier_name string 取件员姓名,当分配取件员成功时返回
pickup_courier_phone string 取件员电话,当分配取件员成功时返回
delivery_courier_name string 派件员姓名,当分配派件员成功时返回
delivery_courier_phone string 派件员电话,当分配派件员成功时返回
  • 返回参数
参数名称 类型 必选 备注
errcode number 返回码
errmsg string 错误信息
exist number 用户是否绑定 0-未绑定 1-已绑定
  • 示例
{
"path": {
  "action_time": 1597396101,
  "action_type": 200001,
  "action_msg": "快件到达 【泉州磁灶集散中心】",
  "pickup_courier_name":"",
  "pickup_courier_phone":"",
  "delivery_courier_name":"",
  "delivery_courier_phone":""
 },
 "receiver": {
  "area": "晋江市",
  "address": "庄宅北区158-6",
  "province": "福建省",
  "city": "泉州市",
  "phone": "13800138000",
  "name": "李四"
 },
 "sender": {
  "area": "柯桥区",
  "address": "纺都路137号",
  "province": "浙江省",
  "city": "绍兴市",
  "phone": "13800138001",
  "name": "张三"
 },
 "waybill_id": "1234567890"
 }

# 5、测试流程

  • 绑定(测试阶段微信号+手机号提供给微信进行绑定,项目上线后可以直接通过微信侧的小程序绑定)
  • 调用查询API
  • 已绑定时调用绑定推送API,确认返回 errcode 为0 1、检查是否收到微信消息(目前只有派件300002及签收300003两个 actiontype 会下发消息通知) 2、点击消息确认能够跳到轨迹详情页,查看详情页的轨迹信息是否正确
  • 未绑定时调用未绑定推送API,确认返回 errcode 为0

# 6、API错误码定义

错误码 含义 备注
40014/40001 无效accesstoken
41001 accesstoken不存在
42001 accesstoken过期
40097 参数错误
150004 运力配置不存在
932001 反查运单系统错误
932002 反查运单逻辑错误
932003 反查运单获取到的运单数据异常