Korea Yunda Express Order Interface Document

Korea Yunda Express API is designed based on restful standard.

Call Entry

To invoke the service URL of the API, the open platform currently provides two environments for intervenors:the testing environment，the formal environment.

• Testing environment
  http://tapi.suyoda.cn/v1

• Formal environment
  http://api.suyoda.cn/v1

Public Parameter

Calling any API must pass in parameters. The public parameters currently supportedare:

Name of parameter	Type of parameter	Required	Description
method	String	Yes	API interface name.
app_key	String	Yes	System allocation, please contact the administrator to get it.
session	String	Yes	System allocation, please contact the administrator to get it.
timestamp	String	Yes	The time stamp format is displayed in yyyy-MM-ddHH:mm:ss, and the timezone is GMT+8, for example: 2016-01-01 12:00:00. The maximum time error Korea Yunda Express API Server allows clients to request is 5 minutes.
format	String	Yes	Response format, defaults to json format, and currently only supports json format.
v	String	Yes	API protocol version, optional value: 1.0
sign	String	Yes	API input parameter signature results,signature algorithm please refer to the following introduction for
sign_method	String	Yes	Digest algorithm of signature, with optional values: hmac,md5.

Business Parameter

In addition to the public parameters, if the API itself has business-level parameters,they also need to be passed in.Please consult the API documentation for each API business-level parameters. API documentation Instructions.

Signature Algorithm

In order to prevent malicious tampering by hackers during API calls, calling any API requires signature.The server will verify the signature according to the request parameters, and the illegal signature request will be rejected.There are two kinds of signature algorithms currently supported：MD5(sign_method=md5)，HMAC_MD5(sign_method=hmac). The general process of signature is as follows.

• All API request parameters (including public parameters and business parameters, except parameters of sign and byte[] types),are sorted in ascending order according to the order of the parameter names in ASCII code table. ASCII code table order AscendingSorting.Such as:foo:1, bar:2, foo_bar:3, foobar:4The order after sorting is.bar:2, foo:1, foo_bar:3, foobar:4

• Combining the sorted parameter names with the parameter values, the result based on the above example: isbar2foo1foo_bar3foobar4.

• The assembled string is encoded in utf-8 and then the encoded byte stream is digested by using the signature algorithm. If you use the MD5 algorithm, you need to add appsecret before and after the assembled string and then make an abstract of it.Such as:PHP encryption is as follows

• MD5

md5(secret+bar2foo1foo_bar3foobar4+secret)

• HMAC

HASH_HMAC('md5',bar2foo1foo_bar3foobar4,secret,false)

Interface List

1. The information may be submitted several times a day, or the customers need to be grouped. We introduce the concept of batch management.
2. Before creating an order, it is recommended to create a batch first, and the batch numbers can be reused. The batch number can survive 24 hours.
3. If the delivery address is the same: In principle, we do not recommend that you create one batch for each order, because if you do that, the batch will lose its original value. (except that the delivery address is different)

Batch Creation

All request and response data should be encoded in utf-8 format. All parameter names and values in URL must be encoded by URL. If the requested Content-Type is application/x-www-form-urlencoded, all parameter values in the HTTP Body should also be URL encoded; if the format is multipart/form-data, the parameter values of each field in every form do not need to be encoded, but the charset part of each field in the form needs to be specified as utf-8

• Interface name：hjd.batch.add

• Request address：http://api.huijiedan.com/v1/batch

• Request type：post

Request Parameter

Name of parameter	Type of parameter	Required	Description
batch_name	String	Yes	The order number of submitter. Uniqueness in your system.
sender	json	Yes	Sender Information. When an order is created, there is no need to fill out sender information.

Return Parameter

{
　　"error":0,
　　"message":"success",
　　"data":{
　　　　"batch_no":"2018019",
　　　　"start_time":"2018-04-15 20:55:38",
　　　　"end_time":"2018-04-16 20:55:38",
　　　　"batch_name":"20170131The first order"
　　}
}

Order Interface

All request and response data should be encoded in utf-8 format. All parameter names and values in URL must be encoded by URL. If the requested Content-Type is application/x-www-form-urlencoded, all parameter values in the HTTP Body should also be URL encoded; if the format is multipart/form-data, the parameter values of each field in every form do not need to be encoded, but the charset part of each field in the form needs to be specified as utf-8

• Interface name：hjd.order.add

• Request address：http://api.huijiedan.com/v1/order

• Request type：post

Request Parameter

Name of parameter	Type of parameter	required	Description
order_no	String	Yes	The order number of submitter. Uniqueness in your system.
batch_no	String	No	Order batch number.by Create batch interface the numbers can be obtained by batch interface creation and can be reused. The batch number can survive 24 hours.
sender	json	No	Sender information. If you have already filled in the batch number, sender information can be omitted. We will call the delivery address of the batch number as the address of this order. If both the sender information and batch number are filled .the sender information will be prioritized.
receiver	json	Yes	Recipient Information. Please check the recipient information sheet.
goods	json	Yes	The commodity information of the order
weight	number	No	Total weight of goods kg Unit: g
count	number	Yes	Pieces/Packages
length	Float	No	The total length of the customer's order goods, in centimeters, accurate to 2 decimal places, including letters.
width	Float	No	The total width of the customer's order goods, in centimeters, accurate to 2 decimal places, including letters.
heigh	Float	No	The total height of the customer's order goods, in centimeters, accurate to 2 decimal places, including letters.
total_amount	Float	Yes	The total amount of orders
currency	String	No	Currency unit currency code table Cross-border business needs to be filled out, if it isempty ,the default is: CNY
tax_fee	Double	No	Tariff amount
buyer_nick	String	Yes	Buyer’sname :same to the real name of recipient.
sender_country	String	Yes	Sender’s country or region. Country and region code table
receiver_country	String	Yes	Recipient’s country or region. Country and region code table

The sender information, recipient information, and commodity information combination all need to follow the order rules of the parameter names in ASCII code table After they are converted to the json string, the url needs to be performed.

1. The format of the mobile phone number of recipient/sender: +country or region code xxx-xxxx-xxx
2. The format of the telephone number of recipient/sender: +country or region code xxx-xxxx
3. Note: There is a space between the country or region code and the next digit
4. For ease of reading: when you convert PHP to json format,please add: JSON_UNESCAPED_UNICODE

Sender Information Combination

Name of parameter	Type of parameter	Required	Description
name	String	Yes	Sender’s name
zip	String	No	The zip code of sender
mobile	String	Yes	The mobile phone number of sender For example:if the number is+82 138-000-000 of the mainland of China, you can add +86 in front of it Either phone number or mobile number should be provided.
tel	String	Yes	The phone number of sender. For example +82 02-966-8899 Either phone number or mobile number should be provided.
country	String	Yes	Country or region of sender note:this is not the abbreviation of code.
state	String	Yes	The sender’s province
city	String	Yes	The sender’s city
district	String	No	The sender’s district of the city
town	String	No	The street, or town of the sender, such as Sanguo Town
address	String	Yes	The sender's detailed address:If the street and address cannot be completely distinguished, please combine it with the detailed address.

Recipient Information Combination

Name of parameter	Type of parameter	Required	Description
name	String	Yes	Recipient’s name
idcard_type	number	No	Type of certificate of the recipient, please refer to the Type of Certificatefor their codes.
idcard	String	No	Identification number of recipient
zip	String	No	The zip code of recipient
mobile	String	Yes	The mobile phone number of recipient.For example, if the number is+82 138-000-000 of the mainland of China, you can add+86 in front of it. Either phone number or mobile number should be provided.
tel	String	Yes	The phone number of sender. For example +82 02-966-8899 Either phone number or mobile number should be provided.
country	String	Yes	Country or region of recipient note:this is not the abbreviation of code.
state	String	Yes	The recipient’s province
city	String	Yes	The recipient’s city
district	String	No	The recipient’s district of the city
town	String	No	The street, or town of the recipient, such as Sanguo Town
address	String	Yes	The recipient's detailed address:If the street and address cannot be completely distinguished, please combine it with the detailed address.

Order Commodity Data Combination

Name of parameter	Type of parameter	Required	Description
code	String	Yes	Commodity codingIf there are multiple specifications for the customer's commodity code, please fill in the code of SKU，It will have uniqueness. For example: E351840
name	String	Yes	Commodityname For example: Moville shirt
price	Double	Yes	Commodity price: fill in the unit price here
count	Int	Yes	Commodity quantity
unit	String	No	Commodity unit: pairs, pieces, strips, tables, books, etc. Application unit
spec	String	No	Commodity specifications, such as: Moville ShirtMBlack
hscode	String	No	Customs declaration code (tax code)
currency	String	No	Currency unit currency code table Cross-border business needs to be filled out, if it isempty ,the default is: CNY

Code Table Appendix

This code table is the corresponding value in cardinal data, and the ID and code corresponding to different systems during the process of docking with a third-party system are not the same. Therefore, data providers need to perform data conversion.

Country or Region Code Table

Country or Region		Currency		district code of telephone
Name	Abbreviation	Chinese	English
China	CN	RMB	CNY	+86
Taiwan, China	TW	NT dollar	NTD	+886
HongKong, China	HK	Hong Kong Dollar	HKD	+852
Macao, China	MO	Macau Pataca	MOP	+853
Korea	KR	Korean Won	KRW	+82
Australia	AU	Australian Dollar	AUD	+61
Malaysia	MY	Malaysian Ringgit	MYR	+60
United States	US	American dollar	USD	+1
Japan	JP	yen	JPY	+81

Type of Certificate Code

Type	code	Description
Identification Card	7	The recipient of Mainland China with Chinese nationality, please select this item for customs inspection.
Passport	8	Non-Chinese customers can provide passport numbers.

Error CodesQuery

code	Description
10001	The current request type is wrong, please confirm the request type
10002	Interface Error：Interface name does not exist
10003	Signature error, please check the signature ways and signature method.
10004	JSON format data is not the correct JSON string format. Please check.
20001	method：Please check whether the value of method is empty
20002	method：Please check if the interface name of the method exists.
20010	app_key：Please check if app_key is empty.
20011	app_key：Please check if the length of app_key is correct.
20012	app_key：The app_key does not exist, please go to the management background to query the real app_key.
20020	appSecret:Please check whether the value of appSecret is empty.
20021	appSecret:Please check if the value of appSecret is correct or exceed the validity period.
20030	v:The version number of the interface cannot be null.
20031	v:Please fill in the correct interface version number.
20040	sign：Please check whether to fill in the corresponding value
20041	sign：Please check the signature is correct, fixed length: 32 characters
20050	sign_method：Please check whether to fill in the corresponding value
20051	sign_method：At present, the signature format only supports two encryption methods: MD5 and HMAC.
20060	timestamp：Please check if timestamp is filled in.
20061	timestamp：timestamp is not a valid date.
20062	timestamp：The date format of timestamp should be: "2018-04-13 12:01:02".
20063	timestamp：Request date and current server date: plus or minus 5 minutes.
20070	format：Please check whether to input.
20071	format：this value should be json

code	Error Description
20100	batch_name：Please confirm whether the batch name is filled in and the batch name cannot be empty.
20101	batch_name：Please confirm that the batch name is at least 10 characters.
20102	batch_name：Please confirm that the length of batch name is 100 characters at most.
20110	sender：Please bring the sending information collection when creating batch.
20111	sender：Please carefully check the sender information collection.Shipment information collection

• Sender Information Error Code

code	Error Description
20200	name：Please confirm the sender's real name, and this item cannot be empty
20201	name：Please confirm that the sender's real name and official name length do not meet the standard
20206	zip：Please confirm the entered postcode.Postcode should be digital
20207	zip：Please confirm the entered postcode.The length of the postcode does not meet the standard. Six digit numbers general.
20210	Either the sender's mobile number or phone number must be filled in.
20211	mobile：Please confirm the entered mobile number. The format should be: + country(region) code 138-xxxx-xxxx such as:+82 138-000-000 Pay attention to the space after the country(region) code
20212	tel：Please confirm the entered mobile number. The format should be: + country (region) code - xxxx-xxxxeg:+82 02-966-8899 Pay attention to the space after the country(region) code
20220	country：Please check that the entered country name is correct. This item cannot be empty
20221	country：Please check that the entered country name is correct. At least 2 characters, such as: China
20230	state： Please check the name of the secondary administrative area you entered. This can be understood as the "province" that corresponds to China's administrative region. This item cannot be empty. The municipality input regulations are, for example, Shanghai city, fill in Shanghai here.
20231	state： Please check whether the length of the secondary administrative area name entered is in line with the range. The minimum character length is 2 characters.
20240	city：Please check the name of the three-level administrative area that you entered, which can be understood as the "city" that corresponds to China's administrative region. This item cannot be blank. Enter rules for the municipality is, for example, Shanghai city, fill in Shanghai here.
20241	city：Please check whether the length of the three-level administrative area entered is within the range. The minimum character length is 2 characters.
20250	district：Please select the four-tier administrative district where the sender is located: for example: Chengyang District, xx County
20260	town：Please select the five-tier administrative district where the sender is located: for example: Chengyang Street, xx Town
20270	address：Please enter the detailed address of the sender's area, specific to the number of the house. This item cannot be empty
20271	address：Please enter the detailed address of the sender's area for the corresponding length, at least 6 characters.

• Recipient Information Error Code

code	Error Description
20400	name：Please confirm the real name of the recipient, and this item cannot be empty
20401	name：Please confirm the real name of the recipient. The length of the name does not meet the standard.
20406	zip：Please confirm the entered postcode. The postcode should be in digital format.
20407	zip：Please confirm the entered postcode.The length of the postcode does not meet the standard. Six digit numbers in general.
20410	Either the sender's mobile number or phone number must be filled in.
20411	mobile：Please confirm the entered mobile number. The format should be: + country(region) code 138-xxxx-xxxx, eg:+82 138-000-000 Note that there are spaces after the country (region).
20412	tel：Please confirm the entered mobile number. The format should be: + country (region) code -xxxx-xxxx, eg:+82 02-966-8899 note that there are spaces after the country (region).
20420	country：Please check if the country name entered is correct. This item cannot be empty.
20421	country：Please check whether the country's name is correct. At least 2 characters, for example: China
20430	state： Please check the name of the secondary administrative area you entered. This can be understood as the "province" that corresponds to China's administrative region. This item cannot be empty. The municipality input regulations are, for example, Shanghai city, fill in Shanghai here.
20431	state： Please check whether the length of the secondary administrative area name entered is in line with the range. The minimum character length is 2 characters.
20440	city： Please check the name of the three-level administrative area that you entered, which can be understood as the "city" that corresponds to China's administrative region. This item cannot be empty, the entering rule of municipality is, for example, Shanghai city, fill inShanghai here.
20441	city： Please check whether the length of the three-level administrative area name entered meets the scope. The minimum character length should be 2 characters.
20450	district：Please select the four-level administrative district where the sender is located: For example: Chengyang District, xx County
20460	town：Please select the recipient's five-level administrative district, such as: Chengyang Street, xx Town.
20470	address：Please enter the detailed address of the recipient's area, specific to the number of the house. This cannot be empty
20471	address：Please enter the detailed address of the recipient's area in accordance with the corresponding length, at least 6 characters.
20475	address：Please confirm whether the type of certificate entered is digital type or certificate type
20476	address：Please confirm whether the type of the entered certificate existscertificate type List

• Order Interface Error Query

code	Order Interface Error Description
20300	order_no：Please check whether the order number is filled in. This item cannot be empty.
20301	order_no：Please confirm whether the length of the input order number is correct. The minimum length cannot be less than 8 characters and the maximum length cannot exceed 20 characters.
20303	The recipient and batch number need to fill in at least one item.
20304	This order number already exists. Please re-order.
20305	batch_no：Please confirm the length of the batch number is correct, and the minimum cannot be less than 7 and not more than 10 digits.
20306	batch_no：The entered batch number does not exist. Please check.
20307	batch_no：batch number is inaccurate. Please enter the batch number of the number type.
20310	sender：Please check whether the input sender information is the correct JSON string format.
20312	receiver：Please check whether the recipient information is filled in, and this item cannot be empty
20313	receiver：Please check whether the input sender information is the correct JSON string format.
20316	goods：Please check whether the order's commodity information is filled in. This item cannot be empty.
20317	goods：Please check whether the order's commodity information is in the correct JSON format.
20320	weight：Please input the weight of the goods accurately, and the unit is g. If the third party data is Kg, please convert it.
20321	weight：If g is the unit of measurement, the number is at least three digits, for example: 200.
20325	count：Please enter the quantity of the order goods accurately. The order quantity should be the sum of the quantity of the suborder items.
20326	count：The number of items for the order should be in numeric type.
20327	count：The number of goods ordered is at least 1 digit
20330	length：length：Please enter the exact length of the goods, unit: CM. Accurate to 2 digits, such as: 12.12
20333	width：Please enter the width of the goods accurately, unit: CM. Accurate to 2 digits such as: 12.12.
20336	heigh：Please input the height of the goods accurately, unit: CM. Accurate to 2 digits such as: 12.12.
20340	total_amount：Please enter the exact amount of the order. This item cannot be empty.
20341	total_amount：The type of order amount should be floating-point type. Accurate to 2 digits such as: 12.12.
20345	currency：Please enter the currency unit of the transaction, such as: CNY. Currency code table
20350	tax_fee：The type of tariff should be floating-point type. Accurate to 2 digits such as: 12.12.
20351	buyer_nick：Please fill in the name of the buyer. This item can't be empty.
20352	buyer_nick：The name of the buyer is the same as the recipient name. Please check the input.
20355	sender_country：Please fill in the sending country or region. This item cannot be empty.
20356	sender_country：Please fill in the information according to the opened country code table. This error will occur if there is no country information in the code table. Such as: KR country code list
20360	receiver_country：Please fill in the destination country or region. This item cannot be empty.
20361	receiver_country：Please fill in the information according to the opened country code table. This error will occur if there is no country information in the code table. Such as: CN country code list

• Commodity Combination ErrorQuery

code	Commodity Combination ErrorQuery
20500	code：Commodity code cannot be empty, please fill in third-party commodity SKU. (uniqueness)
20501	code：In order to guarantee uniqueness, the commodity SKU has at least five strings. please confirm.
20505	name：Please confirm the entered commodity name. This item cannot be empty.
20506	name：Please confirm the name of the commodity name you entered，and the input cannot be less than 5 strings.
20510	price：Please confirm the input commodity price (unit price), this item cannot be empty
20511	price：Please confirm the price of the input commodity, it should be a floating point type, such as: 12.02
20515	count：Please enter the quantity of commodity.
20516	count：The number of commodity should be digital type, such as: 2
20520	unit：Please enter the unit corresponding to the commodity, such as: pair, bar, piece, etc.
20525	spec：Please enter the corresponding specifications for the commodity, such as: Moville Shirt M Black
20530	hscode：Please input the customs declaration code (tax code) accurately
20535	currency：Please fill in the corresponding country (region) currency code