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
- 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
}
}
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;
?>
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 khai giá, là căn cứ để tính phí khai giá 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í khai giá 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í khai giá là khoản khai giá cho các rủi ro trong quá trình vận chuyển hoặc lưu kho. Phí khai giá bằng 0.5% giá trị hàng hoá. GHTK sẽ bồi hoàn 100% giá trị khai giá 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 + khai giá 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 có bầu |
| 4 | Cây có chậu dễ vỡ |
| 5 | Các loại cây khác |
cảnh báo
Lưu ý: Kể từ 01/01/2026, GHTK sẽ ngừng hỗ trợ các trường dữ liệu order.tags và order.sub_tags trong đơn hàng. Để đảm bảo hệ thống vận hành ổn định, quý đối tác vui lòng cập nhật và sử dụng API để lấy danh sách các giải pháp thay thế cho việc gắn thẻ đơn hàng.
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.2001297581",
"area": "1",
"fee": "30400",
"insurance_fee": "15000",
"tracking_id": 2001297581,
"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ằngpick_money - Nếu giá trị được set bằng
0, COD sẽ thu tiền người nhận số tiền bằngpick_money+phí ship của đơn hàng, giá trị mặc định bằng0