小程序
取消
开发
中文
EN
取消
  • 服务端

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