logistics.onAddOrder

本文档描述服务器端接收的消息或事件,详细说明参见消息推送

请求下单事件。

消息参数

Object

属性类型说明
ToUserNamestring快递公司小程序 UserName
FromUserNamestring微信团队的 OpenID (固定值)
CreateTimenumber事件时间,Unix时间戳
MsgTypestring消息类型,固定为 event
Eventstring事件类型,固定为 add_waybill,不区分大小写
Tokenstring订单 Token。请保存该 Token,调用logistics.updatePath时需要传入
OrderIDstring唯一标识订单的 ID,由商户生成。快递需要保证相同的 OrderID 生成相同的运单ID。
BizIDstring商户 ID,即商户在快递注册的客户编码或月结账户名
BizPwdstringBizID 对应的密码
ShopAppIDstring商户的小程序 AppID
WayBillIDstring运单 ID,从微信号段中生成。若为 0,则表示需要快递来生成运单 ID。
Remarkstring快递备注,会打印到面单上,比如"易碎物品"
SenderArray.<Object>发件人信息
ReceiverArray.<Object>收件人信息
CargoArray.<Object>包裹信息
InsuredArray.<Object>保价信息
ServiceArray.<Object>服务类型

Sender 的结构

属性类型说明
Namestring发件人姓名
Telstring发件人座机号码
Mobilestring发件人手机号码
Companystring发件人公司名
PostCodestring发件人邮编
Countrystring发件人所在国家,默认为"中国"
Provincestring发件人省份,比如"广东省"
Citystring发件人地区/市,比如"广州市"
Areastring发件人区/县,比如"海珠区"
Addressstring发件人详细地址,比如"XX路XX号XX大厦XX"

Receiver 的结构

属性类型说明
Namestring收件人姓名
Telstring收件人座机号码
Mobilestring收件人手机号码
Companystring收件人公司名
PostCodestring收件人邮编
Countrystring收件人所在国家,默认为"中国"
Provincestring收件人省份,比如"广东省"
Citystring收件人地区/市,比如"广州市"
Areastring收件人区/县,比如"海珠区"
Addressstring收件人详细地址,比如"XX路XX号XX大厦XX"

Cargo 的结构

属性类型说明
Weightnumber货物总重量,比如1.2,单位是千克(kg)
Space_Xnumber货物长度,比如20.5,单位是厘米(cm)
Space_Ynumber货物宽度,比如15.0,单位是厘米(cm)
Space_Znumber货物高度,比如10.0,单位是厘米(cm)
Countnumber货物数量,一般为1

Insured 的结构

属性类型说明
UseInsurednumber是否保价,0 表示不保价,1 表示保价
InsuredValuenumber保价金额,单位是分,比如: 10000 表示 100 元

Service 的结构

属性类型说明
ServiceTypenumber服务类型ID,详见已经支持的快递公司基本信息
ServiceNamestring服务名称,详见已经支持的快递公司基本信息

消息返回

属性类型默认值必填说明
ToUserNamestring原样返回请求中的 FromUserName
FromUserNamestring快递公司小程序 UserName
CreateTimenumber事件时间,Unix 时间戳
MsgTypestring消息类型,固定为 event
Eventstring事件类型,固定为 add_waybill
Tokenstring传入的 Token,原样返回
OrderIDstring传入的唯一标识订单的 ID,由商户生成,原样返回
BizIDstring商户 ID,原样返回
WayBillIDstring运单 ID
ResultCodenumber处理结果错误码
ResultMsgstring处理结果的详细信息
WaybillDatastring集包地、三段码、大头笔等信息,用于生成面单信息。详见后文返回值说明

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 格式

  1. <xml>
  2. <ToUserName><![CDATA[gh_abcdefg]]></ToUserName>
  3. <FromUserName><![CDATA[oABCD]]></FromUserName>
  4. <CreateTime>1533042556</CreateTime>
  5. <MsgType><![CDATA[event]]></MsgType>
  6. <Event><![CDATA[add_waybill]]></Event>
  7. <Token>1234ABC234523451</Token>
  8. <OrderID><![CDATA[012345678901234567890123456789]]></OrderID>
  9. <BizID><![CDATA[xyz]]></BizID>
  10. <BizPwd><![CDATA[xyz123]]></BizPwd>
  11. <ShopAppID><![CDATA[wxABCD]]></ShopAppID>
  12. <WayBillID><![CDATA[123456789]]></WayBillID>
  13. <Remark><![CDATA[易碎物品]]></Remark>
  14. <Sender>
  15. <Name><![CDATA[张三]]></Name>
  16. <Tel><![CDATA[020-88888888]]></Tel>
  17. <Mobile><![CDATA[18666666666]]></Mobile>
  18. <Company><![CDATA[公司名]]></Company>
  19. <PostCode><![CDATA[123456]]></PostCode>
  20. <Country><![CDATA[中国]]></Country>
  21. <Province><![CDATA[广东省]]></Province>
  22. <City><![CDATA[广州市]]></City>
  23. <Area><![CDATA[海珠区]]></Area>
  24. <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>
  25. </Sender>
  26. <Receiver>
  27. <Name><![CDATA[王小蒙]]></Name>
  28. <Tel><![CDATA[029-77777777]]></Tel>
  29. <Mobile><![CDATA[18610000000]]></Mobile>
  30. <Company><![CDATA[公司名]]></Company>
  31. <PostCode><![CDATA[654321]]></PostCode>
  32. <Country><![CDATA[中国]]></Country>
  33. <Province><![CDATA[广东省]]></Province>
  34. <City><![CDATA[广州市]]></City>
  35. <Area><![CDATA[天河区]]></Area>
  36. <Address><![CDATA[XX路XX号XX大厦XX栋XX]]></Address>
  37. </Receiver>
  38. <Cargo>
  39. <Weight>1.2</Weight>
  40. <Space_X>20.5</Space_X>
  41. <Space_Y>15.0</Space_Y>
  42. <Space_Z>10.0</Space_Z>
  43. <Count>2</Count>
  44. <DetailList>
  45. <Name><![CDATA[一千零一夜钻石包]]></Name>
  46. <Count>1</Count>
  47. </DetailList>
  48. <DetailList>
  49. <Name><![CDATA[爱马仕柏金钻石包]]></Name>
  50. <Count>1</Count>
  51. </DetailList>
  52. </Cargo>
  53. <Insured>
  54. <UseInsured>1</UseInsured>
  55. <InsuredValue>10000</InsuredValue>
  56. </Insured>
  57. <Service>
  58. <ServiceType>0</ServiceType>
  59. <ServiceName><![CDATA[标准快递]]></ServiceName>
  60. </Service>
  61. </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##"
}