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