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