API đăng đơn hàng

Đối tác gửi danh sách đơn hàng sang hệ thống của Giaohangtietkiem thông qua APIs. Sau khi các đơn hàng được lưu thành công vào hệ thống của GHTK, hệ thống sẽ trả về danh sách đơn hàng tương ứng chứa các thông tin liên quan của mỗi đơn hàng.

Đường dẫn

POST /services/shipment/order

Headers

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

HTTP

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
}
}

CURL

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

<?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;
?>

Các tham số

Tham số	Bắt buộc	Mô tả
order	yes	Object - thông tin đơn hàng gửi sang GHTK
products	yes	Array - Danh sách các sản phẩm, mô tả tham số của từng sản phẩm xem trong bảng tiếp theo
order.id	yes	String - mã đơn hàng thuộc hệ thống của đối tác
Thông tin điểm lấy hàng
order.pick_name	yes	String - Tên người liên hệ lấy hàng hóa
order.pick_money	yes	Integer - Số tiền CoD. Nếu bằng 0 thì không thu tiền CoD. Tính theo VNĐ
order.pick_address_id	no	String - ID địa điểm lấy hàng của shop trong trang quản lý đơn hàng dành cho khách hàng. Nếu trường này khác rỗng sẽ được ưu tiên sử dụng
order.pick_address	yes	String - Địa chỉ ngắn gọn để lấy nhận hàng hóa. Ví dụ: nhà số 5, tổ 3, ngách 11, ngõ 45
order.pick_province	yes	String - Tên tỉnh/thành phố nơi lấy hàng hóa
order.pick_district	yes	String - Tên quận/huyện nơi lấy hàng hóa
order.pick_ward	no	String - Tên phường/xã nơi lấy hàng hóa
order.pick_street	no	String - Tên đường/phố nơi lấy hàng hóa
order.pick_tel	yes	String - Số điện thoại liên hệ nơi lấy hàng hóa
order.pick_email	no	String - Email liên hệ nơi lấy hàng hóa
Thông tin điểm giao hàng
order.name	yes	String - tên người nhận hàng
order.address	yes	String - Địa chỉ chi tiết của người nhận hàng, ví dụ: Chung cư CT1, ngõ 58, đường Trần Bình
order.province	yes	String - Tên tỉnh/thành phố của người nhận hàng hóa
order.district	yes	String - Tên quận/huyện của người nhận hàng hóa
order.ward	yes	String - Tên phường/xã của người nhận hàng hóa (Bắt buộc khi không có đường/phố)
order.street	yes	String - Tên đường/phố của người nhận hàng hóa (Bắt buộc khi không có phường/xã)
order.hamlet	yes	String - Tên thôn/ấp/xóm/tổ/... của người nhận hàng hóa. Nếu không có, vui lòng điền "Khác"
order.tel	yes	String - Số điện thoại người nhận hàng hóa
order.note	no	String - Ghi chú đơn hàng. Vd: Khối lượng tính cước tối đa: 1.00 kgTừ 24/2/2020 ghi chú tối đa cho phép là 120 kí tự
order.email	yes	String - Email người nhận hàng hóa
Thông tin điểm trả hàng
order.use_return_address	no	Integer - mặc định là 0. Field này có thể truyền vào một trong hai giá trị 0 hoặc 1. Bằng 0 nghĩa là địa chỉ trả hàng giống địa chỉ lấy hàng nên các field địa chỉ trả hàng không cần truyền qua. Bằng 1 nghĩa là sử dụng địa chỉ trả hàng khác địa chỉ lấy hàng và cần truyền vào giá trị cho các field tiếp theo
order.return_name	yes	String - tên người nhận hàng trả
order.return_address	yes	String - Địa chỉ chi tiết của người nhận hàng, ví dụ: nhà A, ngõ 100
order.return_province	yes	String - Tên tỉnh/thành phố của người nhận hàng hóa
order.return_district	yes	String - Tên quận/huyện của người nhận hàng hóa
order.return_ward	no	String - Tên phường/xã của người nhận hàng hóa
order.return_street	no	String - Tên đường/phố của người nhận hàng hóa
order.return_tel	yes	String - Số điện thoại người nhận hàng hóa
order.return_email	yes	String - Email người nhận hàng hóa
Các thông tin thêm
order.is_freeship	no	Integer - Freeship cho người nhận hàng. Nếu bằng 1 COD sẽ chỉ thu người nhận hàng số tiền bằng pick_money, nếu bằng 0 COD sẽ thu tiền người nhận số tiền bằng pick_money + phí ship của đơn hàng, giá trị mặc định bằng 0
order.weight_option	no	String - nhận một trong hai giá trị gram và kilogram, mặc định là kilogram, đơn vị khối lượng của các sản phẩm có trong gói hàng
order.total_weight	no	Double - Tổng khối lượng của đơn hàng, mặc định sẽ tính theo products.weight nếu không truyền giá trị này.
order.pick_work_shift	no	Integer - Nếu set bằng 3 đơn hàng sẽ lấy vào buổi tối. 2: buồi chiều. 1: buổi sáng. Giá trị mặc định GHTK set theo ca tự tính.
order.deliver_work_shift	no	Integer - Nếu set bằng 3 đơn hàng sẽ được giao vào buổi tối. 2: buồi chiều. 1: buổi sáng. Giá trị mặc định GHTK set theo ca tự tính.
order.label_id	no	String - Mã vận đơn được cấp trước cho đối tác - mặc định không sử dụng được field này, cấu hình riêng cho từng gói dịch vụ
order.pick_date	no	String YYYY/MM/DD - Hẹn ngày lấy hàng - mặc định không sử dụng được field này, cấu hình riêng cho từng gói dịch vụ
order.deliver_date	no	String YYYY/MM/DD - Hẹn ngày giao hàng - mặc định không sử dụng được field này, cấu hình riêng cho từng gói dịch vụ
order.expired	no	String YYYY/MM/DD hh:mm:ss - thời gian tự động - mặc định không sử dụng được field này, cấu hình riêng cho từng gói dịch vụ
order.value	yes	Interger (VNĐ) - Giá trị đóng bảo hiểm, là căn cứ để tính phí bảo hiểm và bồi thường khi có sự cố.
order.opm	no	Interger (VNĐ) - 1. đơn chỉ thu tiền, 0. default
order.pick_option	no	String - Nhận một trong hai giá trị cod và post, mặc định là cod, biểu thị lấy hàng bởi COD hoặc Shop sẽ gửi tại bưu cục
order.actual_transfer_method	no	String - Trường này lưu đường vận chuyển của đơn hàng, mặc định là đường bay (fly). Nếu đơn hàng được chuyển bằng đường bộ (road), bạn sẽ nhận được thông báo của GHTK.
order.transport	no	String - Phương thức vâng chuyển road ( bộ ) , fly (bay). Nếu phương thức vận chuyển không hợp lệ thì GHTK sẽ tự động nhảy về PTVC mặc định
order.deliver_option	no	String - Gía trị là xteam nếu lựa chọn phương thức vận chuyển xfast
order.tags	no	Array - Gắn nhãn cho đơn hàng, truyền lên mảng, mô tả nhãn đơn hàng trong bảng tiếp theo
order.sub_tags	no	Array - Array - Chi tiết nhãn đơn hàng, truyền lên mảng (Bắt buộc gửi lên khi gán nhãn hàng cây cối cho đơn hàng)

Tham số products

Tham số	Bắt buộc	Mô tả
name	yes	String - Tên hàng hóa
price	no	Integer - Giá trị hàng hóa
weight	yes	Double - Khối lượng hàng hóa Tính theo đơn vị KG
quantity	no	Integer - Số lượng hàng hóa
product_code	no	String - Mã sản phẩm được lấy từ api lấy danh sách thông tin sản phẩm

Mô tả nhãn đơn hàng tags

Nhãn đơn hàng	Mô tả	Chi tiết
1	Dễ vỡ	Những mặt hàng bằng chất liệu dễ bị hư hỏng, đổ vỡ trong quá trình vận chuyển. Phụ phí hàng dễ vỡ bằng 20% tổng phí dịch vụ (phí ship + phí bảo hiểm nếu có). Nếu có hư hại, GHTK sẽ chịu toàn bộ trách nhiệm với đơn hàng được tích Dễ vỡ.
2	Giá trị cao/Đặc biệt	Những mặt hàng có giá trị hàng hoá > 3,000,000đ (với shop B2C) và > 1,000,000đ (với shop C2C). Các hàng hoá giá trị cao sẽ tính thêm phí bảo hiểm là khoản bảo hiểm cho các rủi ro trong quá trình vận chuyển hoặc lưu kho. Phí bảo hiểm bằng 0.5% giá trị hàng hoá. GHTK sẽ bồi hoàn 100% giá trị bảo hiểm khi mất hàng (tối đa 20,000,000 VNĐ) nếu có giấy tờ chứng minh nguồn gốc và giá trị hàng hoá (hoá đơn nhập hàng, hoá đơn mua hàng hợp lệ và khớp với thông tin sản phẩm trên hệ thống GHTK,...). Trong trường hợp shop không thể chứng minh nguồn gốc và giá trị hàng hoá, bồi thường tối đa 04 lần cước phí vận chuyển.
7	Nông sản/thực phẩm khô	Mặt hàng thực phẩm khô (không yêu cầu điều kiện bảo quản đặc biệt), phụ phí 10% tổng phí dịch vụ (phí ship + bảo hiểm nếu có). Đối với hàng thực phẩm khô có hạn sử dụng ngắn (< 30 ngày), thời gian hẹn giao không quá 7 ngày kể từ thời điểm lấy hàng thành công. Quá thời hạn trên, đơn hàng sẽ không được tự động lưu kho, GHTK sẽ trả lại hàng về shop.
10	Cho xem hàng	Khách hàng được xem sản phẩm trước khi nhận hàng
11	Cho thử hàng/ đồng kiểm	Hỗ trợ người nhận kiểm đếm số lượng hoặc kiểm tra tình trạng của từng sản phẩm (không bao gồm mở niêm phong của sản phẩm), phụ phí 2,000đ/ đơn hàng.
13	Gọi shop khi khách không nhận hàng, không liên lạc được, sai thông tin	Nhân viên GHTK sẽ liên hệ với shop nếu gặp vấn đề như: sai thông tin người nhận, không liên lạc được, KH từ chối nhận hàng
17	Giao hàng 1 phần chọn sản phẩm	Hỗ trợ khách chỉ nhận và trả tiền 1 phần hàng. Phần còn lại sẽ được trả về shop với mức phí nội tỉnh = 5.000đ/đơn, liên tỉnh = 50% phí ship
18	Giao hàng 1 phần đổi trả hàng	Hỗ trợ KH không nhận sản phẩm nhưng thu một phần phí cho shop. Phí cần thu mặc định bằng phí ship, shop có thể sửa giá trị tiền cần thu theo mong muốn của mình. Phần hàng mang về cho shop được xem như đơn hàng trả với mức phí nội tỉnh = 5.000đ/đơn, liên tỉnh = 50% phí ship
19	Không giao được thu phí	Hỗ trợ KH không nhận sản phẩm nhưng thu một phần phí cho shop. Phí cần thu mặc định bằng phí ship, shop có thể sửa giá trị tiền cần thu theo mong muốn của mình. Phần hàng mang về cho shop được xem như đơn hàng trả với mức phí nội tỉnh = 5.000đ/đơn, liên tỉnh = 50% phí ship, Lưu ý: Đối tác cần truyền thêm trường not_delivered_fee với giá trị 0 < not_delivered_fee <= 20,000,000đ
20	Hàng nguyên hộp	Mặt hàng được đóng hộp của nhà sản xuất, yêu cầu được bảo quản nguyên vẹn trong quá trình vận chuyển, phụ phí 1,000đ/ đơn hàng.
22	Thư tín, tài liệu	Hồ sơ, tài liệu, thư từ được đóng gói cẩn thận để không làm hư hại sản phẩm
39	Thực phẩm tươi	Những mặt hàng thực phẩm tươi và đông lạnh có hạn sử dụng trong ngày. Đối với những sản phẩm này nếu không giao thành công cho khách, GHTK sẽ hoàn hàng ngay trong ngày
40	Hàng nhỏ	Hàng hóa có khối lượng ≤ 300gr và tổng kích thước 3 chiều ≤ 20cm. Đơn hàng nhỏ cần được đóng gói tối thiểu trong phong bì có kích thước 110x120mm.
41	Hàng không xếp chồng	Hàng hóa có đặc tính dễ hư hỏng, móp méo, yêu cầu không cho phép hàng hóa khác đặt chồng lên.
42	Hàng yêu cầu xếp đúng chiều	Hàng hoá khi vận chuyển phải sắp đặt theo đúng phương/ chiều của sản phẩm nếu không sẽ ảnh hưởng đến tính an toàn, chất lượng của hàng hóa
75	Hàng cây cối	Đơn hàng được gán tag "Hàng cây cối" sẽ được GHTK vận chuyển luồng hàng riêng biệt đảm bảo cho loại sản phẩm này, tăng thời gian lưu trữ và giảm thiểu ảnh hưởng ngoại quan

---

Mô tả nhãn đơn hàng sub_tags

Chi tiết nhãn đơn hàng	Mô tả
1	Hạt giống
2	Cây non
3	Cây non
4	Cây có chậu dễ vỡ
5	Các loại cây khác

Phản hồi

Kết quả trả về khi đăng đơn thành công:

{
  "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
  }
}

Trường hợp có lỗi

{
  "success": false,
  "message": "Chưa có thông tin order"
}

warning

Quy trình của GHTK không cho phép một mã đơn được đẩy lại nếu trước đấy đã đăng thành công trên hệ thống GHTK Trường hợp lỗi order.id đã có trên hệ thống GHTK, API sẽ trả về lỗi, kèm các thông tin

• partner_id: mã đơn hàng của đối tác
• ghtk_label: nhãn đơn của GHTK
• created: thời gian đơn hàng được tạo
• status: trạng thái hiện tại của đơn hàng

{
  "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", // id trong request đẩy sang của bạn
      "ghtk_label": "S1.A1.1737345", // nhãn đơn GHTK, tương ứng với id của bạn
      "created": "2016-11-02T12:18:39+07:00",
      "status": 5  // trạng thái đơn hàng hiện tại trên hệ thống GHTK, tra bảng mã trạng thái đơn trong phần webhook
  }
}

Lưu ý

thông tin

Lưu ý: Đơn vị khối lượng GHTK sử dụng cho từng sản phẩm là KG

warning

Lưu ý: Phí ship ban đầu sẽ được tính theo tổng khối lượng các sản phẩm có trong đơn hàng

warning

Lưu ý:

• Nếu đơn hàng được set is_freeship = 1, COD sẽ chỉ thu người nhận hàng số tiền bằng pick_money
• Nếu giá trị được set bằng 0, COD sẽ thu tiền người nhận số tiền bằng pick_money + phí ship của đơn hàng, giá trị mặc định bằng 0