3. Submit Order API

This API is to submit an order to GHTK system.

Endpoint

POST /services/shipment/order

Headers

Token: {API_TOKEN}
X-Client-Source: {PARTNER_CODE}

HTTP
CURL
PHP

POST /services/shipment/order/?ver=1.5 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
X-Client-Source: S308157
Content-Type: application/json
{
  "products": [{
  "name": "bút",
  "weight": 0.1,
  "quantity": 1,
  "product_code": 1241
}, {
  "name": "tẩy",
  "weight": 0.2,
  "quantity": 1,
  "product_code": 1254
}],
  "order": {
  "id": "a4",
  "pick_name": "HCM-nội thành",
  "pick_address": "590 CMT8 P.11",
  "pick_province": "TP. Hồ Chí Minh",
  "pick_district": "Quận 3",
  "pick_ward": "Phường 1",
  "pick_tel": "0911222333",
  "tel": "0911222333",
  "name": "GHTK - HCM - Noi Thanh",
  "address": "123 nguyễn chí thanh",
  "province": "TP. Hồ Chí Minh",
  "district": "Quận 1",
  "ward": "Phường Bến Nghé",
  "hamlet": "Khác",
  "is_freeship": "1",
  "pick_date": "2016-09-30",
  "pick_money": 47000,
  "note": "Khối lượng tính cước tối đa: 1.00 kg",
  "value": 3000000,
  "transport": "fly",
  "pick_option":"cod" ,// Đơn hàng xfast yêu cầu bắt buộc pick_option là COD
  "deliver_option" : "xteam", // nếu lựa chọn kiểu vận chuyển xfast
  "pick_session" : 2 // Phiên lấy xfast
}
}

curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
-H "X-Client-Source: S308157" \
-H "Content-Type: application/json" \
-d '{"products":[{"name":"bút","weight":0.1,"quantity":1,"product_code": 1241},{"name":"tẩy","weight":0.2,"quantity":1,"product_code": 1254}],"order":{"id":"a4","pick_name":"HCM-nội thành","pick_address":"590 CMT8 P.11","pick_province":"TP. Hồ Chí Minh","pick_district":"Quận 3","pick_ward":"Phường 1","pick_tel":"0911222333","tel":"0911222333","name":"GHTK - HCM - Noi Thanh","address":"123 nguyễn chí thanh","province":"TP. Hồ Chí Minh","district":"Quận 1","ward":"Phường Bến Nghé","hamlet":"Khác","is_freeship":"1","pick_date":"2016-09-30","pick_money":47000,"note":"Khối lượng tính cước tối đa: 1.00 kg","value":3000000,"transport":"fly","pick_option":"cod","deliver_option" : "xteam","pick_session" : 2}}' "https://services.giaohangtietkiem.vn/services/shipment/order"

<?php
$order = '{"products":[{"name":"bút","weight":0.1,"quantity":1,"product_code":"23304A3MHLMVMXX625"},{"name":"tẩy","weight":0.2,"quantity":1,"product_code":""}],"order":{"id":"a4","pick_name":"HCM-nội thành","pick_address":"590 CMT8 P.11","pick_province":"TP. Hồ Chí Minh","pick_district":"Quận 3","pick_ward":"Phường 1","pick_tel":"0911222333","tel":"0911222333","name":"GHTK - HCM - Noi Thanh","address":"123 nguyễn chí thanh","province":"TP. Hồ Chí Minh","district":"Quận 1","ward":"Phường Bến Nghé","hamlet":"Khác","is_freeship":"1","pick_date":"2016-09-30","pick_money":47000,"note":"Khối lượng tính cước tối đa: 1.00 kg","value":3000000,"transport":"fly","pick_option":"cod","deliver_option":"xteam","pick_session":2,"tags":[1]}}';

$curl = curl_init();

curl_setopt_array($curl, array(
   CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/order",
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => "POST",
   CURLOPT_POSTFIELDS => $order,
   CURLOPT_HTTPHEADER => array(
       "Content-Type: application/json",
       "Token: APITokenSample-ca441e70288cB0515F310742",
       "Content-Length: " . strlen($order),
   ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Input parameters:

Parameter	Datatype	Mandatory (Y)/(N)	Description
order	Object	Y	Detailed information of order sent to GHTK.
products	Array	Y	List of products in the order.
order.id	String	Y	Partner’s reference ID.
Order picking information
order.pick_name	String	Y	Name of the contact person to pick up the order.
order.pick_money	Integer	Y	Cash amount which needs to be collected at delivery (in VND).
order.pick_address_id	String	N	Address ID to pick up the order. This input takes precedence in identifying the pick up address if not null/empty. These ID can be find in tab "Edit shop information". If pick_address_id is valid, province name, district name,… of pick up address will be following this ID.
order.pick_address	String	Y	Address string to pick up the order. E.g: nhà số 5, tổ 3, ngách 11, ngõ 45
order.pick_province	String	Y	Province to pick up the order. E.g: Hà Nội
order.pick_district	String	Y	District to pick up the order. E.g: Cầu Giấy
order.pick_ward	String	N	Ward to pick up the order. E.g: Mai Dịch
order.pick_street	String	N	Street to pick up the order. E.g: Nguyễn Chí Thanh
order.pick_tel	String	Y	Phone number of the contact person to pick up the order.
order.pick_email	String	N	Email contact to pick up the order.
Order delivery information
order.name	String	Y	Name of the contact person to deliver the order.
order.address	String	Y	Detailed address to deliver the order. Eg: Chung cư CT1, ngõ 58, đường Trần Bình
order.province	String	Y	Province to deliver the order.
order.district	String	Y	District to deliver the order.
order.ward	String	Y	Ward to deliver the order. (Required if street is none)
order.street	String	Y	Street to deliver the order.(Required if ward is none)
order.hamlet	String	Y	Hamlet to deliver the order. If it is non-information, please fill "Khác".
order.tel	String	Y	Phone number of the contact person to deliver the order.
order.note	String	N	Note of the order. The maximum length of note is 120 characters. E.g: Khối lượng tính cước tối đa: 1.00 kg.
order.email	String	Y	Email contact to deliver the order.
Order return information
order.use_return_address	Integer (0/1)	N	This is to indicate if the return address should be different from pick up address. -"0" means return address is the same as pick up address hence the subsequence params (order.return_*) can be ignored. -"1" means return address is different from pick up address and GHTK should consider the subsequence params for order return. Default value is "0".
order.return_name	String	Y if order.use_return_address=1	Name of the contact person to return the order.
order.return_address	String		Detailed address to return the order.
order.return_province	String		Province to return the order.
order.return_district	String		District to return the order.
order.return_ward	String	N	Ward to return the order.
order.return_street	String	N	Street to return the order.
order.return_tel	String	Y if order.use_return_address=1	Phone number of the contact person to return the order.
order.return_email	String	Y	Email contact to return the order.
Other information	order.is_freeship	Integer	N
order.weight_option	String	N	Weighing unit (gram/kilogram). Default value is kilogram.
order.total_weight	Double	N	Total weight of the order.Default value is sum amount of products.weight.
order.pick_work_shift	Integer	N	To indicate the order will be picked up at which time. "3" is in the evening. "2" is in the afternoon and "1" is in the morning. Default value is set automatically by GHTK.
order.deliver_work_shift	Integer	N	To indicate the order will be delivered at which time. "3" is in the evening. "2" is in the afternoon and "1" is in the morning. Default value is set automatically by GHTK.
order.pick_date	String YYYY/MM/DD	N	Booking the picking-up date of the order. This field is enabled for certain service levels.
order.deliver_date	String YYYY/MM/DD	N	Booking the delivering date of the order. This field is enabled for certain service levels.
order.value	Integer	Y	Declared monetary value of the order package. The insurance fee is calculated based on this value. (in VND)
order.pick_option	String	N	Possible value is "cod" (Carrier picks up parcels at shop’s pick up address) or "post" (shop drops the parcels at GHTK’s service points). Default value is cod
order.transport	String	N	This is the transportation method to deliver the parcel. Possible value is "fly" or "road". If the transportation method is invalid, GHTK will switch automatically to default transportation method.
order.deliver_option	String	N	is ‘xteam’ when the delivery method is XFAST service
order.booking_id	String	Option	Booking id from the response of API get pick time (in case has XFAST service)
order.tags	Array	N	Possible value is [1] : Display a glass shape on the label if the order has fragile product. Possible value is [7]: if the order has farm product, dry food.
order.pending_order	Number	N	Order for reserve flow
order.total_box	Number	N	Total box of order
order.height	Number	N	Order's height (cm)
order.length	Number	N	Order's length (cm)
order.width	Number	N	Order's width (cm)
order.sub_tags	Array	N	Detail options when you pick some services such as plant goods

Product parameters

name	String	Y	Name of the product
price	Integer	N	Product’s price
weight	Double	Y	Product’s weight
quantity	Integer	N	Product’s quantity
height	Integer	N	Product’s Height (cm )
length	Integer	N	Product’s Length (cm)
width	Integer	N	Product’s Width (cm)
product_code	String	N	Product’s code. This value is taken from product information list API

Tags description

Tag ID	Tag	Nhãn đơn hàng	Description
1	Fragile	Dễ vỡ	The items made of fragile materials are prone to damage and breakage during transportation. If any damage occurs, GHTK will take full responsibility for orders marked as Fragile. Cost 1,000 VND per order.
2	High-value items	Giá trị cao	Items valued at > 3,000,000 VND (for Pro Shop) and > 1,000,000 VND (for Standard Shop) will have an additional insurance fee, which is the insurance amount for risks during transportation or storage. The insurance fee is equal to 0.5% of the value of the goods. GHTK will reimburse 100% of the value when lost (maximum of 20,000,000 VND) if there is documentation proving the origin and value of the goods (import invoices, valid purchase invoices matching the product information on the GHTK system, etc.). If the shop cannot prove the origin and value of the goods, compensation will be a maximum of 04 times the shipping fee
7	Agricultural Products	Hàng nông sản	For agricultural products with a short shelf life (`< 30 days`), the scheduled delivery time will not exceed 7 days from the successful pickup. Beyond this deadline, the order will not be automatically stored, and GHTK will return the items to shop.
10	Allowed to inspect the product	Cho xem hàng	Customers are allowed to inspect the product before accepting delivery.
11	Crosscheck	Cho thử hàng/ đồng kiểm	Customers are allowed to count the quantity or check the condition of each item (excluding breaking seals on the products). Cost 2,000 VND per order.
13	Call the shop when the customer does not receive the goods, cannot be contacted, or the information is incorrect.	Gọi cho shop khi không giao được, //Gọi cho shop khi khách không nhận được hàng, không liên lạc được, sai thông tin	GHTK staff will contact the shop in case of issues such as incorrect information, inability to contact the customer, or the customer refuses to receive the goods.
17	Partial Delivery - Customer Selects Products	Giao hàng 1 phần chọn sản phẩm	Customers are allowed to only accept and pay for a partial of the order. The remaining will be returned to shop with an intra-province fee of 5,000 VND per order and an interprovincial fee equal to 50% of the shipping fee.
18	Partial Delivery - Product Return	Giao hàng 1 phần đổi trả hàng	Assistance in delivering one item to the customer and returning the remaining portion to the shop. The returned portion is treated as a return order with an intra-province fee of 5,000 VND per order and an inter-province fee equal to 50% of the shipping fee.
19	Fee for unsuccessful delivery attempt.	Không giao được thu phí	Supporting customers who do not accept the product but collecting a partial fee for the shop. The fee to be collected defaults to the shipping fee, but the shop can adjust the amount they wish to collect. The returned portion for the shop is treated as a return order with an intra-province fee of 5,000 VND per order and an inter-province fee equal to 50% of the shipping fee. Note: Partners need to include an additional field "not_delivered_fee" with a value `0 < not_delivered_fee <= 20,000,000 VND`.
20	Whole box	Hàng nguyên hộp	Items packed in the manufacturer's box, requiring intact preservation during transportation. Cost 1,000 VND per order.
22	Mail and documents	Thư tín	Documents and files are carefully packaged to prevent damage to the products.
39	Fresh food	Thực phẩm tươi	For fresh and frozen food items with a same-day expiration date, if delivery to the customer is unsuccessful, GHTK will refund the order on the same day.
40	Small goods	Hàng nhỏ	Items with a weight of ≤ 300 grams.Small orders need to be packaged minimally in envelopes with dimensions of at least 110x120mm.
42	Items requiring proper orientation.	Hàng yêu cầu xếp đúng chiều	Goods must be arranged according to the correct orientation/direction of the product during transportation; otherwise, it will affect the safety and quality of the goods.
52	Liquid goods	Hàng chất lỏng	Liquid goods are items with physical characteristics in liquid, adhesive, or viscous form. Liquid goods need to be contained in specialized bottles or sealed bags.
75	Plant goods	Hàng cây cối	Orders tagged with ‘plants’ will be transported by GHTK through a separate shipping channel to ensure extended storage time and minimize external impact

Sub Tags description

Sub Tag ID	Description
1	Seed
2	Young plants
3	Plant with root ball
4	Plant in a fragile pot
5	Others

Response

Response for confirmed order:

{
  "success": true,
  "message": "",
  "order": {
    "partner_id": "123123a",
    "label": "S1.A1.1737345",
    "area": "1",
    "fee": "30400",
    "insurance_fee": "15000",
    "estimated_pick_time": "Sáng 2017-07-01",
    "estimated_deliver_time": "Chiều 2017-07-01",
    "products": [],
    "status_id": 2
  }
}

Response for failed order:

{
  "success": false,
  "message": "{ERROR_MESSAGE}",
  "error_code": "{ERROR_CODE}",
  "log_id": "{LOG_ID}"
}

warning

Once an order is successfully submitted to GHTK system, it could not be reversed. In case the "order.id" already exists, shop will receive error response including

code: "ORDER_ID_EXIST"
partner_id: Partner ID
ghtk_label: GHTK tracking number with alias
created: created time of order
status: the current status of order

{
  "success": false,
  "message": "Mã đơn hàng của bạn đã tồn tại trên hệ thống GHTK",
  "error": {
      "code" : "ORDER_ID_EXIST",
      "partner_id" : "a4",
      "ghtk_label": "S1.A1.1737345",
      "created": "2016-11-02T12:18:39+07:00",
      "status": 5
  }
}

Note

info

Note: GHTK uses kilograms (KG) as the unit of weight for each product.

warning

Note: The initial shipping fee will be calculated based on the total weight of the products in the order.

warning

Note:

If the order is set to is_freeship = 1, COD (Cash on Delivery) will only collect the amount specified in pick_money from the recipient.
If the value is set to 0 (default), COD will collect the amount specified in pick_money plus the shipping fee of the order from the recipient.

3. Submit Order API

Endpoint​

Headers​

Response​

Note​

Endpoint

Headers

Response

Note