# logistics.onAddOrder

This documentation describes messages or events received on the server. For details, see Message Push.

Triggers an order placement request event.

# Message Parameters

# Object

Property	Type	Description
ToUserName	string	The UserName of the express company's Mini Program.
FromUserName	string	The OpenID of WeChat Team. It is a fixed value.
CreateTime	number	The time of the event. It is a Unix timestamp.
MsgType	string	The type of the message. It is event.
Event	string	The type of the event. It is add_waybill and is case-insensitive.
Token	string	The token of the order. Save this token carefully. It is required when logistics.updatePath is called.
OrderID	string	The ID that uniquely identifies the order. It is generated by the merchant. The express company must ensure that the same waybill ID is generated for the same OrderID.
BizID	string	The ID of the merchant. It is the customer code or monthly statement account of the merchant in the express company.
BizPwd	string	The password of the BizID.
ShopAppID	string	The AppID of the merchant's Mini Program.
WayBillID	string	The ID of the waybill. It is generated based on the WeChat account segment. "0" indicates that the express company needs to generate the waybill ID.
Remark	string	Remarks on express delivery. It will be printed on the waybill, for example, Fragile.
Sender	Array.<Object>	Sender information.
Receiver	Array.<Object>	Receiver information.
Cargo	Array.<Object>	Parcel information.
Insured	Array.<Object>	Parcel insurance information.
Service	Array.<Object>	Service type.

Sender is composed as follows

Property	Type	Description
Name	string	The name of the sender.
Tel	string	The telephone number of the sender.
Mobile	string	The mobile number of the sender.
Company	string	The company name of the sender.
PostCode	string	The postal code of the sender's address.
Country	string	The country where the sender is located. It is "China" by default.
Province	string	The province where the sender is located, for example, "Guangdong Province".
City	string	The region/city where the sender is located, for example, "Guangzhou".
Area	string	The district/county where the sender is located, for example, "Haizhu District".
Address	string	The detailed address of the sender, for example, "xx on xx Building, No. xx, xx Road".

Receiver is composed as follows

Property	Type	Description
Name	string	The name of the receiver.
Tel	string	The telephone number of the receiver.
Mobile	string	The mobile number of the receiver.
Company	string	The company name of the receiver.
PostCode	string	The postal code of the receiver's address.
Country	string	The country where the receiver is located. It is "China" by default.
Province	string	The province where the receiver is located, for example, "Guangdong Province".
City	string	The region/city where the receiver is located, for example, "Guangzhou".
Area	string	The district/county where the receiver is located, for example, "Haizhu District".
Address	string	The detailed address of the receiver, for example, "xx on xx Building, No. xx, xx Road".

Cargo is composed as follows

Property	Type	Description
Weight	number	The total weight of cargoes (in kg), for example, "1.2".
Space_X	number	The length of the cargo (in cm), for example, "20.5".
Space_Y	number	The width of the cargo (in cm), for example, "15.0".
Space_Z	number	The height of the cargo (in cm), for example, "10.0".
Count	number	The quantity of cargoes. It is usually "1".

Insured is composed as follows

Property	Type	Description
UseInsured	number	Specifies whether to insure the cargo. " 0" indicates that the cargo is not insured, and "1" indicates that the cargo is insured.
InsuredValue	number	The insured value (in fen). For example, "10000" indicates 100 CNY.

Service is composed as follows

Property	Type	Description
ServiceType	number	The ID of the service type. For details, see Basic Information of Supported Express Companies.
ServiceName	string	The name of the service. For details, see Basic Information of Supported Express Companies.

# Message Responses

Property	Type	Required	Description
ToUserName	string	Yes	The FromUserName in the request is returned as it is.
FromUserName	string	Yes	The UserName of the express company's Mini Program.
CreateTime	number	Yes	The time of the event. It is a Unix timestamp.
MsgType	string	Yes	The type of the message. It is event.
Event	string	Yes	The type of the event. It is add_waybill.
Token	string	Yes	The token. It is returned as is.
OrderID	string	Yes	The ID that uniquely identifies the order. It is generated by the merchant and is returned as is.
BizID	string	Yes	The ID of the merchant. It is returned as is.
WayBillID	string	Yes	The ID of the waybill.
ResultCode	number	Yes	The error code for the result.
ResultMsg	string	Yes	Details about the result.
WaybillData	string	Yes	Information such as the parcel gathering location, three-section code, and marker pen writing. It is used to generate the waybill information. For details, see the description of return values in the following content.

Valid values of ResultCode

Value	Description	Minimum Version
0	Order placed.
-1	Other errors.
10001	The customer code or monthly statement account does not exist.
10002	Incorrect customer password.
20001	Incorrect waybill ID (This error code is applicable only to scenarios where the waybill ID is generated by WeChat.)
20002	Incomplete sender information (including the name, the phone number, and the address).
20003	The sender's address is unreachable or the shipping address is not within the service scope.
20004	Incomplete receiver information (including the name, the phone number, and the address).
20005	The receiver's address is unreachable or the delivery address is not within the service scope.
20006	The quantity, weight, or size of the cargoes is incorrect or improper.
20007	The merchant's balance is insufficient and needs to be topped up before order placement.
20008	The insurance information is incorrect (the amount is improper or the express company does not support the insurance.
20009	Incorrect service information.

# Message Parameters

All the fields are provided by the merchant. We will not guarantee the integrity or accuracy. The express company should verify that the parameters are valid and correct.
When the network environment is unstable, order placement events may be pushed repeatedly. The same waybill ID needs to be returned for the same BizID and OrderID.
One-waybill-for-multiple-orders and Collect on Delivery (COD) services are not supported.

# Return Values

The WaybillData field is used to generate a waybill. It is in the structure of ##(key##value##)*. "key" can be written to the waybill template, and "value" is the real value.

For example, in the example ##ZTO_bagAddr##Guangzhou##ZTO_mark##888-666-666##, "ZTO_markAddr" indicates the code name of the parcel gathering location of ZTO Express, "Guangzhou" indicates the real value of the parcel gathering location, "ZTO_mark" indicates the code name of three-section code of ZTO Express, and "888-666-666" is the real value of three-section code.

# Example of the Message Data Packet

In XML format

<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[Fragile]]></Remark>
  <Sender>
      <Name><![CDATA[Jim]]></Name>
      <Tel><![CDATA[020-88888888]]></Tel>
      <Mobile><![CDATA[18666666666]]></Mobile>
      <Company><![CDATA[Company name]]></Company>
      <PostCode><![CDATA[123456]]></PostCode>
      <Country><![CDATA[China]]></Country>
      <Province><![CDATA[Guangdong Province]]></Province>
      <City><![CDATA[Guangzhou]]></City>
      <Area><![CDATA[Haizhu District]]></Area>
      <Address><![CDATA[XXBlock XX, XX Building, No. XX, Road xxXX]]></Address>
  </Sender>
  <Receiver>
      <Name><![CDATA[Wang Xiaomeng]]></Name>
      <Tel><![CDATA[029-77777777]]></Tel>
      <Mobile><![CDATA[18610000000]]></Mobile>
      <Company><![CDATA[Company name]]></Company>
      <PostCode><![CDATA[654321]]></PostCode>
      <Country><![CDATA[China]]></Country>
      <Province><![CDATA[Guangdong Province]]></Province>
      <City><![CDATA[Guangzhou]]></City>
      <Area><![CDATA[Tianhe District]]></Area>
      <Address><![CDATA[XXBlock XX, XX Building, No. XX, Road xxXX]]></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[1001 Nights Diamond Purse]]></Name>
          <Count>1</Count>
      </DetailList>
      <DetailList>
          <Name><![CDATA[Hermes Birkin Bag]]></Name>
          <Count>1</Count>
      </DetailList>
  </Cargo>
  <Insured>
      <UseInsured>1</UseInsured>
      <InsuredValue>10000</InsuredValue>
  </Insured>
  <Service>
      <ServiceType>0</ServiceType>
      <ServiceName><![CDATA[Standard express delivery]]></ServiceName>
  </Service>
</xml>

In JSON format

{
  "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": "Fragile",
  "Sender": {
    "Name": "Jim",
    "Tel": "020-88888888",
    "Mobile": "18666666666",
    "Company": "Company name",
    "PostCode": "123456",
    "Country": "China",
    "Province": "Guangdong Province",
    "City": "Guangzhou",
    "Area": "Haizhu District",
    "Address": "XXBlock XX, XX Building, No. XX, Road xxXX"
  },
  "Receiver": {
    "Name": "Wang Xiaomeng",
    "Tel": "029-77777777",
    "Mobile": "18610000000",
    "Company": "Company name",
    "PostCode": "654321",
    "Country": "China",
    "Province": "Guangdong Province",
    "City": "Guangzhou",
    "Area": "Tianhe District",
    "Address": "XXBlock XX, XX Building, No. XX, Road xxXX"
  },
  "Cargo": {
    "Weight": 1.2,
    "Space_X": 20.5,
    "Space_Y": 15,
    "Space_Z": 10,
    "Count": 2,
    "DetailList": [
      {
        "Name": "1001 Nights Diamond Purse",
        "Count": 1
      },
      {
        "Name": "Hermes Birkin Bag",
        "Count": 1
      }
    ]
  },
  "Insured": {
    "UseInsured": 1,
    "InsuredValue": 10000
  },
  "Service": {
    "ServiceType": 0,
    "ServiceName": "Standard express delivery"
  }
}

# Example of the Returned Data Packet

In XML format

<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##Guangzhou##ZTO_mark##888-666-666##]]></WaybillData>
</xml>

In JSON format

{
  "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##Guangzhou##ZTO_mark##888-666-666##"
}