[toc]

# 1、背景

用户授权手机号后,物流公司将物流状态同步给微信,用户可以在「微信快递服务」中查看收件的物流详细信息,并在关键物流节点收到对应动态通知。

# 2、 流程

# 2.1查模式流程

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

# 2.2推模式流程

推模式下运力无需在每次运单有轨迹变化的时候来微信查询用户绑定状态,由微信主动地将用户绑定数据推送给运力方。 主流程为1-10步骤

  1. 每次用户的绑定情况有更新时(绑定/解绑)会通过接口通知运力方
  2. 运力方自己需要维护用户的绑定数据,在轨迹有变化且此手机号有绑定时向绑定的微信号推送物流轨迹 此外微信会定时查询运力方的绑定数据,并对数据不一致情况进行通知(11-13)

# 3、运力侧接入需要提供的内容

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

# 4、运力侧需要开发的内容

# 4.1、主调

  • 调用查询接口(查模式下必需)
  • 已绑定调用绑定推送接口(必需)

# 4.2、被调

  • 批量推送绑定/解绑数据(推模式下必需)
  • 批量查询绑定/解绑数据(推模式下必需)
  • 微信反查运单接口,需要校验收件人手机号与运单是否匹配(必需)

# 5、接口

# 5.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

# 5.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>
# 批量手机号绑定数据查询
  • 描述:查询运力方系统内的绑定数据
  • 请求参数
参数名称 类型 必选 备注
ToUserName string 快递公司小程序UserName
FromUserName string 微信团队的OpenID(固定值)
CreateTime number 事件时间,Unix时间戳如1599823049
MsgType string 消息类型,固定为event
Event string 事件类型,固定为express_push_batch_bind_query,不区分大小写
Phone array 查询的手机号,每一项的内容为字符串

具体数据格式可能是json,也可能是xml,由小程序在 mp 平台配置的情况决定。
示例: ```xml gh_ea48699fb159 oHt_80DRclK4qjKfdYnPg6RxxsNI event express_push_batch_bind_query 1600152165 123456789 123456778 123456777 ```
  • 返回参数:
参数名称 类型 必选 备注
ToUserName string 原样返回请求中的FromUserName
FromUserName string 快递公司小程序UserName
CreateTime number 事件时间,Unix时间戳
MsgType string 消息类型,固定为event
Event string 事件类型,固定为express_push_batch_bind_query,不区分大小写
ResultCode number 处理结果错误码,成功时返回0,异常时由运力自定义
ResultMsg string 处理结果的详细信息,错误提示
PhoneData array 绑定手机号数据
参数名称 类型 必选 备注
Phone string 手机号
Status number 当前状态 1-绑定 2-解绑
Timestamp number 绑定解绑时间戳
  • 示例:
<xml>
<ToUserName>gh_ea48699fb159</ToUserName>
<FromUserName>oHt_80DRclK4qjKfdYnPg6RxxsNI</FromUserName>
<MsgType>event</MsgType>
<Event>express_push_batch_bind_query</Event>
<CreateTime>1600152165</CreateTime>
<ResultCode>0</ResultCode>
<ResultMsg>OK</ResultMsg>
<PhoneData>
<Phone>123456789</Phone>
<Status>1</Status>
</PhoneData>
<PhoneData>
<Phone>123456778</Phone>
<Status>2</Status>
</PhoneData>
<PhoneData>
<Phone>123456777</Phone>
<Status>1</Status>
</PhoneData>
</xml>
# 批量手机号绑定数据推送
  • 描述:当手机号数据有变动的时候通过本接口来进行推送\
  • 请求参数
参数名称 类型 必选 备注
ToUserName string 快递公司小程序UserName
FromUserName string 微信团队的OpenID(固定值)
CreateTime number 事件时间,Unix时间戳如1599823049
MsgType string 消息类型,固定为event
Event string 事件类型,固定为express_push_batch_bind_notify,不区分大小写
PhoneData array 推送手机号的绑定/解绑信息

其中 PhoneData 的每一项内容如下:

参数名称 类型 必选 备注
Phone string 手机号
Status number 动作类型1-绑定 2-解绑
Timestamp number 绑定/解绑时间,秒级时间戳
Source number 来源 0-微信绑定 2-运力方绑定 ,不存在时默认为微信来源绑定

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

<xml>
<ToUserName>gh_ea48699fb159</ToUserName>
<FromUserName>oHt_80DRclK4qjKfdYnPg6RxxsNI</FromUserName>
<MsgType>event</MsgType>
<Event>express_push_batch_bind_notify</Event>
<CreateTime>1600152165</CreateTime>
<PhoneData>
<Phone>123456789</Phone>
<Type>1</Type>
</PhoneData>
<PhoneData>
<Phone>123456</Phone>
<Type>2</Type>
</PhoneData>
</xml>
  • 返回参数:
参数名称 类型 必选 备注
ToUserName string 原样返回请求中的FromUserName
FromUserName string 快递公司小程序UserName
CreateTime number 事件时间,Unix时间戳
MsgType string 消息类型,固定为event
Event string 事件类型,固定为express_push_batch_bind_notify,不区分大小写
ResultCode number 处理结果错误码,成功时返回0,异常时由运力自定义
ResultMsg string 处理结果的详细信息,错误提示

示例:

<xml>
<ToUserName>gh_ea48699fb159</ToUserName>
<FromUserName>oHt_80DRclK4qjKfdYnPg6RxxsNI</FromUserName>
<MsgType>event</MsgType>
<Event>express_push_batch_bind_notify</Event>
<CreateTime>1600152165</CreateTime>
<ResultCode>0</ResultCode>
<ResultMsg>OK</ResultMsg>

# 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"
 }

# 6、测试流程

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

# 7、API错误码定义

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