1、背景 | 微信开放文档

1、背景
2、流程
- 2.1查模式流程
- 2.2推模式流程
3、运力侧接入需要提供的内容
4、运力侧需要开发的内容
- 4.1、主调
- 4.2、被调
5、接口

[toc]

# 1、背景

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

# 2、流程

# 2.1查模式流程

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

# 2.2推模式流程

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

每次用户的绑定情况有更新时（绑定/解绑）会通过接口通知运力方
运力方自己需要维护用户的绑定数据，在轨迹有变化且此手机号有绑定时向绑定的微信号推送物流轨迹此外微信会定时查询运力方的绑定数据，并对数据不一致情况进行通知（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	反查运单获取到的运单数据异常