阅读(2865)
赞(0)
微信小程序 运力方使用·onAddOrder
2020-07-29 11:45:21 更新
logistics.onAddOrder
本文档描述服务器端接收的消息或事件,详细说明参见消息推送。
请求下单事件。
消息参数
Object
属性 | 类型 | 说明 |
---|---|---|
ToUserName | string | 快递公司小程序 UserName |
FromUserName | string | 微信团队的 OpenID (固定值) |
CreateTime | number | 事件时间,Unix时间戳 |
MsgType | string | 消息类型,固定为 event |
Event | string | 事件类型,固定为 add_waybill,不区分大小写 |
Token | string | 订单 Token。请保存该 Token,调用logistics.updatePath时需要传入 |
OrderID | string | 唯一标识订单的 ID,由商户生成。快递需要保证相同的 OrderID 生成相同的运单ID。 |
BizID | string | 商户 ID,即商户在快递注册的客户编码或月结账户名 |
BizPwd | string | BizID 对应的密码 |
ShopAppID | string | 商户的小程序 AppID |
WayBillID | string | 运单 ID,从微信号段中生成。若为 0,则表示需要快递来生成运单 ID。 |
Remark | string | 快递备注,会打印到面单上,比如"易碎物品" |
Sender | Array.<Object> | 发件人信息 |
Receiver | Array.<Object> | 收件人信息 |
Cargo | Array.<Object> | 包裹信息 |
Insured | Array.<Object> | 保价信息 |
Service | Array.<Object> | 服务类型 |
Sender 的结构
属性 | 类型 | 说明 |
---|---|---|
Name | string | 发件人姓名 |
Tel | string | 发件人座机号码 |
Mobile | string | 发件人手机号码 |
Company | string | 发件人公司名 |
PostCode | string | 发件人邮编 |
Country | string | 发件人所在国家,默认为"中国" |
Province | string | 发件人省份,比如"广东省" |
City | string | 发件人地区/市,比如"广州市" |
Area | string | 发件人区/县,比如"海珠区" |
Address | string | 发件人详细地址,比如"XX路XX号XX大厦XX" |
Receiver 的结构
属性 | 类型 | 说明 |
---|---|---|
Name | string | 收件人姓名 |
Tel | string | 收件人座机号码 |
Mobile | string | 收件人手机号码 |
Company | string | 收件人公司名 |
PostCode | string | 收件人邮编 |
Country | string | 收件人所在国家,默认为"中国" |
Province | string | 收件人省份,比如"广东省" |
City | string | 收件人地区/市,比如"广州市" |
Area | string | 收件人区/县,比如"海珠区" |
Address | string | 收件人详细地址,比如"XX路XX号XX大厦XX" |
Cargo 的结构
属性 | 类型 | 说明 |
---|---|---|
Weight | number | 货物总重量,比如1.2,单位是千克(kg) |
Space_X | number | 货物长度,比如20.5,单位是厘米(cm) |
Space_Y | number | 货物宽度,比如15.0,单位是厘米(cm) |
Space_Z | number | 货物高度,比如10.0,单位是厘米(cm) |
Count | number | 货物数量,一般为1 |
Insured 的结构
属性 | 类型 | 说明 |
---|---|---|
UseInsured | number | 是否保价,0 表示不保价,1 表示保价 |
InsuredValue | number | 保价金额,单位是分,比如: 10000 表示 100 元 |
Service 的结构
属性 | 类型 | 说明 |
---|---|---|
ServiceType | number | 服务类型ID,详见已经支持的快递公司基本信息 |
ServiceName | string | 服务名称,详见已经支持的快递公司基本信息 |
消息返回
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
ToUserName | string | 是 | 原样返回请求中的 FromUserName | |
FromUserName | string | 是 | 快递公司小程序 UserName | |
CreateTime | number | 是 | 事件时间,Unix 时间戳 | |
MsgType | string | 是 | 消息类型,固定为 event | |
Event | string | 是 | 事件类型,固定为 add_waybill | |
Token | string | 是 | 传入的 Token,原样返回 | |
OrderID | string | 是 | 传入的唯一标识订单的 ID,由商户生成,原样返回 | |
BizID | string | 是 | 商户 ID,原样返回 | |
WayBillID | string | 是 | 运单 ID | |
ResultCode | number | 是 | 处理结果错误码 | |
ResultMsg | string | 是 | 处理结果的详细信息 | |
WaybillData | string | 是 | 集包地、三段码、大头笔等信息,用于生成面单信息。详见后文返回值说明 |
ResultCode 的合法值
值 | 说明 | 最低版本 |
---|---|---|
0 | 下单成功 | |
-1 | 其他错误 | |
10001 | 客户编码或者月结账户不存在 | |
10002 | 客户密码不正确 | |
20001 | 运单 ID 不正确(仅适用于微信生成运单 ID 的情况) | |
20002 | 发件人信息不完整(包括姓名、电话、地址等不完整) | |
20003 | 发件人地址不可达或者发货地址不在服务范围 | |
20004 | 收件人信息不完整(包括姓名、电话、地址等不完整) | |
20005 | 收件人地址不可达或者收货地址不在服务范围 | |
20006 | 货物数量、重量、尺寸不正确或者不合理 | |
20007 | 商户余额不足,需要充值后再进行下单 | |
20008 | 保价信息不正确(金额不合理或者快递不支持) | |
20009 | 服务信息不正确 |
消息参数说明
- 各字段均为商家提供,不保证完整,不保证正确,需要快递侧做好参数合法性和正确性检查。
- 当网络环境不稳定时,下单事件可能会重复推送。对于相同的 BizID+OrderID,要返回相同的运单 ID。
- 不支持子母单、代收货款。
返回值说明
WaybillData 字段用于生成面单,结构为##(key##value##)*。key可以写到面单模板中,value是实际值。
比如样例##ZTO_bagAddr##广州##ZTO_mark##888-666-666##中,"ZTO_markAddr"表示中通的集包地代号,"广州"是实际的集包地值;"ZTO_mark"表示中通三段码代号,"888-666-666"是实际的三段码值。
消息数据包示例
XML 格式
<xml>
<ToUserName><![CDATA[gh_abcdefg]]></ToUserName>
<FromUserName><![CDATA[oABCD]]></FromUserName>
<CreateTime>1533042556</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[add_waybill]]></Event>
<Token>1234ABC234523451</Token>
<OrderID><![CDATA[012345678901234567890123456789]]></OrderID>
<BizID><![CDATA[xyz]]></BizID>
<BizPwd><![CDATA[xyz123]]></BizPwd>
<ShopAppID><![CDATA[wxABCD]]></ShopAppID>
<WayBillID><![CDATA[123456789]]></WayBillID>
<Remark><![CDATA[易碎物品]]></Remark>
<Sender>
<Name><![CDATA[张三]]></Name>
<Tel><![CDATA[020-88888888]]></Tel>
<Mobile><![CDATA[18666666666]]></Mobile>
<Company><![CDATA[公司名]]></Company>
<PostCode><![CDATA[123456]]></PostCode>
<Country><![CDATA[中国]]></Country>
<Province><![CDATA[广东省]]></Province>
<City><![CDATA[广州市]]></City>
<Area><![CDATA[海珠区]]></Area>
<Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>
</Sender>
<Receiver>
<Name><![CDATA[王小蒙]]></Name>
<Tel><![CDATA[029-77777777]]></Tel>
<Mobile><![CDATA[18610000000]]></Mobile>
<Company><![CDATA[公司名]]></Company>
<PostCode><![CDATA[654321]]></PostCode>
<Country><![CDATA[中国]]></Country>
<Province><![CDATA[广东省]]></Province>
<City><![CDATA[广州市]]></City>
<Area><![CDATA[天河区]]></Area>
<Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>
</Receiver>
<Cargo>
<Weight>1.2</Weight>
<Space_X>20.5</Space_X>
<Space_Y>15.0</Space_Y>
<Space_Z>10.0</Space_Z>
<Count>2</Count>
<DetailList>
<Name><![CDATA[一千零一夜钻石包]]></Name>
<Count>1</Count>
</DetailList>
<DetailList>
<Name><![CDATA[爱马仕柏金钻石包]]></Name>
<Count>1</Count>
</DetailList>
</Cargo>
<Insured>
<UseInsured>1</UseInsured>
<InsuredValue>10000</InsuredValue>
</Insured>
<Service>
<ServiceType>0</ServiceType>
<ServiceName><![CDATA[标准快递]]></ServiceName>
</Service>
</xml>
JSON 格式
{
"ToUserName": "gh_abcdefg",
"FromUserName": "oABCD",
"CreateTime": 1533042556,
"MsgType": "event",
"Event": "add_waybill",
"Token": "1234ABC234523451",
"OrderID": "012345678901234567890123456789",
"BizID": "xyz",
"BizPwd": "xyz123",
"ShopAppID": "wxABCD",
"WayBillID": "123456789",
"Remark": "易碎物品",
"Sender": {
"Name": "张三",
"Tel": "020-88888888",
"Mobile": "18666666666",
"Company": "公司名",
"PostCode": "123456",
"Country": "中国",
"Province": "广东省",
"City": "广州市",
"Area": "海珠区",
"Address": "XX路XX号XX大厦XX栋XX"
},
"Receiver": {
"Name": "王小蒙",
"Tel": "029-77777777",
"Mobile": "18610000000",
"Company": "公司名",
"PostCode": "654321",
"Country": "中国",
"Province": "广东省",
"City": "广州市",
"Area": "天河区",
"Address": "XX路XX号XX大厦XX栋XX"
},
"Cargo": {
"Weight": 1.2,
"Space_X": 20.5,
"Space_Y": 15,
"Space_Z": 10,
"Count": 2,
"DetailList": [
{
"Name": "一千零一夜钻石包",
"Count": 1
},
{
"Name": "爱马仕柏金钻石包",
"Count": 1
}
]
},
"Insured": {
"UseInsured": 1,
"InsuredValue": 10000
},
"Service": {
"ServiceType": 0,
"ServiceName": "标准快递"
}
}
返回数据包示例
XML 格式
<xml>
<ToUserName><![CDATA[oABCD]]></ToUserName>
<FromUserName><![CDATA[gh_abcdefg]]></FromUserName>
<CreateTime>1533042556</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[add_waybill]]></Event>
<Token>1234ABC234523451</Token>
<OrderID><![CDATA[012345678901234567890123456789]]></OrderID>
<BizID><![CDATA[xyz]]></BizID>
<WayBillID><![CDATA[123456789]]></WayBillID>
<ResultCode>0</ResultCode>
<ResultMsg><![CDATA[success]]></ResultMsg>
<WaybillData><![CDATA[##ZTO_bagAddr##广州##ZTO_mark##888-666-666##]]></WaybillData>
</xml>
JSON 格式
{
"ToUserName": "oABCD",
"FromUserName": "gh_abcdefg",
"CreateTime": 1533042556,
"MsgType": "event",
"Event": "add_waybill",
"Token": "1234ABC234523451",
"OrderID": "012345678901234567890123456789",
"BizID": "xyz",
"WayBillID": "123456789",
"ResultCode": 0,
"ResultMsg": "success",
"WaybillData": "##ZTO_bagAddr##广州##ZTO_mark##888-666-666##"
}