# logistics.onAddOrder

> 本文档描述服务器端接收的消息或事件，详细说明参见[消息推送](/miniprogram/dev/framework/server-ability/message-push.md)。

请求下单事件。

### 消息参数

### Object

| 属性 | 类型 | 说明 |
| ---- | ---- | ---- |
| ToUserName  | string | 快递公司小程序 UserName |
| FromUserName  | string | 微信团队的 OpenID （固定值） |
| CreateTime  | number | 事件时间，Unix时间戳 |
| MsgType  | string | 消息类型，固定为 event |
| Event  | string | 事件类型，固定为 add_waybill，不区分大小写 |
| Token  | string | 订单 Token。请保存该 Token，调用[更新运单轨迹](/miniprogram/dev/server/API/express/express-by-provider/api_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，详见[已经支持的快递公司基本信息](/miniprogram/dev/platform-capabilities/industry/express/business/qa.md) |
| ServiceName  | string | 服务名称，详见[已经支持的快递公司基本信息](/miniprogram/dev/platform-capabilities/industry/express/business/qa.md) |

### 消息返回

| 属性 | 类型 | 默认值 | 必填 | 说明 |
| ---- | ---- | ------ | -------- | ---- |
| 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
<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 格式
```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
<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 格式
```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##"
}
```