3. API đăng đơn
Đố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
"gam_solutions": [
{ "solution_id": 12365478 },
{ "solution_id": 12365479 },
{ "solution_id": 12365470 }
]
}
}
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","pick_session":2,"gam_solutions":[{"solution_id":12365478},{"solution_id":12365479},{"solution_id":12365470}]}}' "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","pick_session":2,"tags":[1],"gam_solutions":[{"solution_id":12365478},{"solution_id":12365479},{"solution_id":12365470}]}}';
$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_ext_tel | no | String - Số máy lẻ của số điện thoại chính tại nơi lấy hàng |
| 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 |
| order.street | yes if no order.hamlet | String - Tên đường/phố của người nhận hàng hóa (Bắt buộc khi không có thôn/ấp/xóm/tổ/...) |
| order.hamlet | yes if no order.street | 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" (Bắt buộc khi không có đường/phố) |
| order.tel | yes | String - Số điện thoại người nhận hàng hóa |
| order.ext_tel | no | String - Số máy lẻ của số điện thoại chính của người nhận hàng |
| 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 | no | 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 | no | String - Email người nhận hàng hóa |
| Các thông tin thêm | ||
| order.is_freeship | no | Integer - Thông tin người trả phí ship. Nếu bằng 1 thì shop trả ship, shipper sẽ chỉ thu người nhận hàng số tiền bằng pick_money, nếu bằng 0 thì người nhận trả ship, shipper 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 - Ca lấy hàng mong muốn. Nếu bằng 1 là lấy buổi sáng, 2 là lấy buổi chiều. GHTK sẽ tính toán theo từng gói dịch vụ nếu không truyền field này |
| order.deliver_work_shift | no | Integer - Ca giao hàng mong muốn. Nếu bằng 1 là giao buổi sáng, 2 là giao buổi chiều. GHTK sẽ tính toán theo từng gói dịch vụ nếu không truyền field này |
| 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 - Ngày lấy hàng mong muốn. GHTK sẽ tính toán theo từng gói dịch vụ nếu không truyền field này |
| order.deliver_date | no | String YYYY/MM/DD - Ngày giao hàng mong muốn. GHTK sẽ tính toán theo từng gói dịch vụ nếu không truyền field này |
| 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.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 - 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) |
| order.total_box | no | Integer - Tổng số lượng kiện hàng trong đơn |
| order.gam_solutions | no | Array - Danh sách ID giải pháp Gam |
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 |
| height | no | Double - Chiều cao của sản phẩm (đơn vị: cm) |
| width | no | Double - Chiều rộng của sản phẩm (đơn vị: cm) |
| length | no | Double - Chiều dài của sản phẩm (đơn vị: cm) |
Mô tả nh ãn đơn hàng tags
| Nhãn đơn hàng | Mô tả | Chi tiết |
|---|---|---|
| 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. |
| 10 | Cho xem hàng | Khách hàng được xem sản phẩm trước khi nhận hàng |
| 13 | Gọi shop khi khách không nhận hàng | 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ợ giao 1 sản phẩm đến cho KH và mang phần hàng còn lại trả về shop. Phí ship của đơn h àng sẽ do shop và KH thỏa thuận (mặc định bằng phí ship). 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đ |
| 62 | Giao hàng 1 phần thu hồi chứng từ | Hỗ trợ giao sản phẩm đến cho khách hàng và mang chứng từ (hóa đơn, giấy tờ) kèm theo phần hàng còn lại về cho shop. |
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 |
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 - Các trường trong response trả về có thể bị ẩn đi