请求下单事件 ¶

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

一、HTTPS 调用¶

消息参数 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##"
}

目录

本页

请求下单事件 ¶

一、HTTPS 调用¶

请求下单事件¶

一、HTTPS 调用¶

请求下单事件 ¶