微信小程序开发文档微信小程序运力方使用·onAddOrder

2024-02-25 开发教程微信小程序开发文档匿名 1℃

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": "标准快递"
  }
}

返回数据包示例