Giaohangtiemkiem RESTful API v1.6.3
Log thay đổi GHTK
Version 1.6.3
- Bổ sung gắn nhãn đơn hàng nông sản/thực phẩm khô cho đơn hàng
Version 1.6.2
- Cập nhật luồng đăng đơn XFAST
Version 1.6.1
- Bổ sung gắn nhãn đơn hàng dễ vỡ cho đơn hàng
Version 1.6
- Thay đổi môi trường thử nghiệm
- Bổ sung API Lấy mã sản phẩm
- Bổ sung mã sản phẩm vào API đăng đơn
- Tính năng đăng đơn Xfast
Version 1.5.5
- Bổ sung API lấy danh sách địa chỉ cấp 4 theo phường/xã hoặc địa chỉ chi tiết
Version 1.5.4
- Cập nhật API đăng đơn. Yêu cầu bắt buộc phải truyền đường hoặc phường địa chỉ người nhận hàng hóa
- Thêm yêu cầu bắt buộc địa cấp cấp 4 (thôn/ấp/xóm/tổ/khu/…)
Version 1.5.3
- Cập nhật API lấy danh sách địa chỉ lấy hàng
Version 1.5.2
- Cập nhật API đăng đơn mới, thêm phương thức ca lấy hàng
Version 1.5.1
- Cập nhật API đăng đơn mới, thêm phương thức vận chuyển
Version 1.5
- Cập nhật API đăng đơn mới, trả về thêm trường trạng thái đơn hàng
Version 1.4.5
- Cập nhật API đăng đơn mới, trường weight là bắt buộc khi đăng đơn hàng
Version 1.4.4
- Thêm trường cho đơn hàng chỉ thu tiền, cập nhật trong api đăng đơn
Version 1.4.3
- API tra cứu trạng thái đơn hàng, trả về thông tin người nhận hàng
- API in phiếu giao hàng
Version 1.4.2
- API B2C:
- Cập nhật API đăng đơn, chức năng quản lý đơn hàng nhiều tài khoản của B2C
Version 1.4.1
- API tính phí ship:
- Thêm tham số logic
delivery
cho biết điểm giao có được GHTK hỗ trợ hay không
- Thêm tham số logic
- Webhook:
- Thêm 6 thông tin mới khi shipper thao tác với đơn hàng trên đường
- API cho tài khoản sàn Thương mại Điện tử (B2C)
- API tạo tài khoản trên hệ thống GHTK
- API địa chỉ:
- Deprecated, sẽ xóa API này khi cập nhật version 1.5
- API lấy token
Version 1.3
- API Đăng đơn hàng:
- Báo lỗi chi tiết hơn trường hợp một đơn hàng bị đăng lại 2 lần trở lên
- Thêm thông tin địa chỉ trả hàng
Version 1.2
API tính phí vận chuyển
- Request gửi lên thêm trường
value
, thực giá của đơn hàng, áp dụng để tính bảo hiểm - Response trả về trường
fee
- phí ship - Response trả về có thêm trường
insurance_fee
- phí bảo hiểm
- Request gửi lên thêm trường
API đăng đơn
- Request gửi lên thêm trường
order.value
, thực giá của đơn hàng, áp dụng để tính bảo hiểm - Response trả về trường
fee
- phí ship - Response trả về có thêm trường
insurance_fee
- phí bảo hiểm
- Request gửi lên thêm trường
Cấu hình chung
Môi trường
URL môi trường thật, production: https://services.giaohangtietkiem.vn
URL môi trường thử nghiệm, sandbox:
- URL tích hợp API : https://services-staging.ghtklab.com
- URL dev khách hàng : https://khachhang-staging.ghtklab.com
Xác thực tài khoản
Request đến service API sẽ được xác thực theo giá trị
Token
trong header của request
GET /authentication-request-sample HTTP/1.1
Host: services.giaohangtietkiem.vn
Token: your-API-token-key
$ curl -H "Token: your-API-token-key" \
"https://services.giaohangtietkiem.vn/authentication-request-sample"
<?php
$curl = curl_init('https://services.giaohangtietkiem.vn/authentication-request-sample');
curl_setopt_array($curl, array(
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
"Token: your-API-token-key",
),
));
response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Lưu ý: thay giá trị
your-API-token-key
bằng token của bạn.
Sau khi đối tác đăng ký và kích hoạt tài khoản trên hệ thống của Giaohangietkiem, tài khoản đối tác sẽ được nhận được một chuỗi API token thông qua email.
Request format
application/x-www-form-urlencoded
POST /request-sample HTTP/1.1
Token: your-API-token-key
Content-Type: application/x-www-form-urlencoded
field1=value1&field2=value2
$ curl -X POST
-H "Token: your-API-token-key" \
-d "field1=value1&field2=value2" \
"https://services.giaohangtietkiem.vn/request-sample"
<?php
$data = array('field1' => 'value1', 'field2' => 'value2');
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/request-sample",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => array(
"content-type: application/x-www-form-urlencoded",
"token: your-API-token-key"
),
));
$response = curl_exec($curl);
curl_close($curl);
echo "Response: " . $response;
?>
application/json
POST /request-sample HTTP/1.1
Token: your-API-token-key
Content-Type: application/x-www-form-urlencoded
{"field1":value1,"field2":value2}
$ curl -X POST
-H "Token: your-API-token-key" \
-d "{"field1":value1,"field2":value2}" \
"https://services.giaohangtietkiem.vn/request-sample"
<?php
$data = array('field1' => 'value1', 'field2' => 'value2');
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/request-sample",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => array(
"content-type: application/json",
"token: your-API-token-key"
),
));
$response = curl_exec($curl);
curl_close($curl);
echo "Response: " . $response;
?>
GHTK hỗ trợ 2 định dạng dữ liệu là application/x-www-form-urlencoded
và aplication/json
. Các request cần set một trong hai giá trị trên cho header Content-Type
Response format
Xác thực không thành công
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=UTF-8
Content-Length: 0
Request thành công, không có lỗi xảy ra
{
"success": true,
"message": "",
"" : ""
}
Request thành công, có lỗi xảy ra
{
"success": false,
"message": "Mô tả lỗi",
"" : ""
}
Kết quả trả về sẽ có 3 định dạng:
- Xác thực không thành công, hay token không hợp lệ
- Request thành công và không có lỗi xảy ra, kết quả trả về ở dạng JSON
- Request thành công và có lỗi xảy ra, kết quả trả về ở dạng JSON
Đơn hàng
Đă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.
Các tham số
POST /services/shipment/order/?ver=1.5 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
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
"tags": [1,7]
}
}
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
-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 = <<<HTTP_BODY
{
"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]
}
}
HTTP_BODY;
$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;
?>
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"
}
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
}
}
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.pick_session | no | String - Giá trị lấy từ response của API check dịch vụ XFAST (phiên lấy xfast) | |||
order.tags | no | Array - Gắn nhãn cho đơn hàng, truyền lên mảng , mô tả tham số của 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) |
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 | yes | Integer - Mã sản phẩm được lấy từ api lấy danh sách thông tin sản phẩm |
Mô tả giá trị phiên lấy pick_session
Phiên lấy | Mô tả |
---|---|
2 | Lấy trước 8h30 & Giao trước 10h30 |
5 | Lấy trước 10h30 & Giao trước 12h30 |
8 | Lấy trước 13h30 & Giao trước 15h30 |
11 | Lấy trước 15h30 & Giao trước 17h30 |
2_mai | Lấy trước 8h30 & Giao trước 10h30 ngày mai |
5_mai | Lấy trước 10h30 & Giao trước 12h30 ngày mai |
8_mai | Lấy trước 13h30 & Giao trước 15h30 ngày mai |
11_mai | Lấy trước 15h30 & Giao trước 17h30 ngày mai |
Mô tả giá trị 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ợ giao 1 sản phẩm đến cho KH và mang phần hàng còn lại về cho shop. Phần hàng mang về đượ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 | 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ả giá trị chi tiế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 |
Tính phí vận chuyển
Tính phí vận chuyển đơn giao từ Hai Quận Bà Trưng đến Cầu Giấy Hà Nội, cân nặng 1 KG
{
"pick_province": "Hà Nội",
"pick_district": "Quận Hai Bà Trưng",
"province": "Hà nội",
"district": "Quận Cầu Giấy",
"address": "P.503 tòa nhà Auu Việt, số 1 Lê Đức Thọ",
"weight": 1000,
"value": 3000000,
"transport": "fly",
"deliver_option": "xteam",
"tags": [1,7]
}
Request
GET /services/shipment/fee?address=P.503%20t%C3%B2a%20nh%C3%A0%20Auu%20Vi%E1%BB%87t,%20s%E1%BB%91%201%20L%C3%AA%20%C4%90%E1%BB%A9c%20Th%E1%BB%8D&province=H%C3%A0%20n%E1%BB%99i&district=Qu%E1%BA%ADn%20C%E1%BA%A7u%20Gi%E1%BA%A5y&pick_province=H%C3%A0%20N%E1%BB%99i&pick_district=Qu%E1%BA%ADn%20Hai%20B%C3%A0%20Tr%C6%B0ng&weight=1000&value=3000000&deliver_option=xteam&tags%5B%5D=1 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742" \
"https://services.giaohangtietkiem.vn/services/shipment/fee?address=P.503%20t%C3%B2a%20nh%C3%A0%20Auu%20Vi%E1%BB%87t,%20s%E1%BB%91%201%20L%C3%AA%20%C4%90%E1%BB%A9c%20Th%E1%BB%8D&province=H%C3%A0%20n%E1%BB%99i&district=Qu%E1%BA%ADn%20C%E1%BA%A7u%20Gi%E1%BA%A5y&pick_province=H%C3%A0%20N%E1%BB%99i&pick_district=Qu%E1%BA%ADn%20Hai%20B%C3%A0%20Tr%C6%B0ng&weight=1000&value=3000000&deliver_option=xteam&tags%5B%5D=1"
<?php
$data = array(
"pick_province" => "Hà Nội",
"pick_district" => "Quận Hai Bà Trưng",
"province" => "Hà nội",
"district" => "Quận Cầu Giấy",
"address" => "P.503 tòa nhà Auu Việt, số 1 Lê Đức Thọ",
"weight" => 1000,
"value" => 3000000,
"transport" => "fly",
"deliver_option" => "xteam",
"tags" => [1]
);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/fee?" . http_build_query($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về
{
"success": true,
"message": "",
"fee": {
"name": "area1",
"fee": 30400,
"insurance_fee": 15000,
"delivery_type": "only_hanoi",
"a": 3,
"dt": "local",
"extFees": [
{
"display": "(+ 7,400 đ)",
"title": "Phụ phí hàng dễ vỡ",
"amount": 7400,
"type": "fragile"
}
{
"display": "(+ 13,400 đ)",
"title": "Phụ phí hàng nông sản/thực phẩm khô",
"amount": 13400,
"type": "food"
}
],
"delivery": true
}
}
Query parameters
Tham số | Bắt buộc | Mô tả |
---|---|---|
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 |
pick_address | no | 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 |
pick_province | yes | String - Tên tỉnh/thành phố nơi lấy hàng hóa |
pick_district | yes | String - Tên quận/huyện nơi lấy hàng hóa |
pick_ward | no | String - Tên phường/xã nơi lấy hàng hóa |
pick_street | no | String - Tên đường/phố nơi lấy hàng hóa |
address | no | 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 |
province | yes | String - Tên tỉnh/thành phố của người nhận hàng hóa |
district | yes | String - Tên quận/huyện của người nhận hàng hóa |
ward | no | String - Tên phường/xã của người nhận hàng hóa |
street | no | String - Tên đường/phố của người nhận hàng hóa |
weight | yes | Integer - Cân nặng của gói hàng, đơn vị sử dụng Gram |
value | no | Integer - Giá trị thực của đơn hàng áp dụng để tính phí bảo hiểm, đơn vị sử dụng VNĐ |
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 |
deliver_option | yes | String - Sử dụng phương thức vận chuyển xfast. Nhận 1 trong 2 giá trị xteam/none |
tags | no | array - Gắn nhãn cho đơn hàng. Truyền giá trị nhãn vào mảng tags |
Dữ liệu trả về
Tham số | Mô tả |
---|---|
fee.name | String - Tên gói cước được áp dụng, các giá trị có thể: area1 , area2 , area3 |
fee.fee | Integer - Cước vận chuyển tính theo VNĐ |
fee.insurance_fee | Integer - Giá bảo hiểm tính theo VNĐ |
fee.delivery | Boolean - Hỗ trợ giao ở địa chỉ này chưa, nếu điểm giao đã được GHTK hỗ trợ giao trả về true , nếu GTHK chưa hỗ trợ giao đến khu vực này thì trả về false |
Trạng thái đơn hàng
Version 2: trả về thêm các thông tin khác của đơn hàng
GET /services/shipment/v2/S1.A1.17373471 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742" \
"https://services.giaohangtietkiem.vn/services/shipment/v2/S1.A1.17373471"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/v2/S1.A1.17373471",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về
{
"success": true,
"message": "",
"order": {
"label_id": "S1.A1.17373471",
"partner_id": "1234567",
"status": "1",
"status_text": "Chưa tiếp nhận",
"created": "2016-10-31 22:32:08",
"modified": "2016-10-31 22:32:08",
"message": "Không giao hàng 1 phần",
"pick_date": "2017-09-13",
"deliver_date": "2017-09-14",
"customer_fullname": "Vân Nguyễn",
"customer_tel": "0911222333",
"address": "123 nguyễn chí thanh Quận 1, TP Hồ Chí Minh",
"storage_day": "3",
"ship_money": "16500",
"insurance": "16500",
"value": "3000000",
"weight": "300",
"pick_money": 47000,
"is_freeship": "1"
}
}
Sau khi danh sách các đơn hàng được gửi tới hệ thống của Giaohangtietkiem. Khách hàng có thể kiểm tra trạng thái các đơn hàng dựa vào mã đơn hàng.
Các tham số
Tham số | Bắt buộc | Mô tả |
---|---|---|
Mã đơn hàng | no | Mã đơn hàng của hệ thống GHTK |
Mã đơn đối tác | no | Mã đơn hàng trên hệ thống của đối tác |
Kết quả trả về
Hệ thống sẽ trả về kết quả dưới dạng JSON. Kết quả trả về được mô tả như sau:
Tham số | Mô tả |
---|---|
label_id | String - Mã đơn hàng của hệ thống GHTK |
partner_id | String - Mã đơn hàng thuộc hệ thống của đối tác |
status | String - Mã trạng thái đơn hàng. Tham khảo bảng mã trạng thái đơn hàng. |
status_text | String - Trạng thái đơn hàng. |
created | String - Thời gian tạo đơn hàng, định dạng YY-MM-DD hh:mm:ss |
modified | String - Thời gian cuối cùng cập nhật đơn hàng, định dạng YY-MM-DD hh:mm:ss |
message | String - Ghi chú của đơn hàng |
pick_date | String - Ngày hẹn lấy hàng của đơn hàng nếu có, nếu đơn hàng đã được lấy thành công thì là ngày lấy hàng |
deliver_date | String - Ngày hẹn giao đơn hàng nếu có, nếu đơn hàng đã được giao hàng thì là ngày giao hàng thành công |
customer_fullname | String - Họ tên người nhận hàng |
customer_tel | String - Số điện thoại người nhận hàng |
address | String - Địa chỉ người nhận hàng |
storage_day | Integer - Số ngày giữ đơn hàng tại kho GHTK trước khi trả hàng |
ship_money | Integer - Phí giao hàng |
insurance | Integer - Phí bảo hiểm |
value | Integer - Giá trị đóng bảo hiểm - căn cứ để bồi thường cho người gửi khi có sự cố xảy ra |
weight | Integer - Khối lượng đơn hàng tính theo gram |
pick_money | Integer - Số tiền CoD |
is_freeship | Integer - Freeship cho người nhận hàng |
Hủy đơn hàng
Sử dụng mã vận đơn của GHTK
POST /services/shipment/cancel/S1.17373471 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
"https://services.giaohangtietkiem.vn/services/shipment/cancel/S1.17373471"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/cancel/S1.17373471",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Sử dụng mã vận đơn của đối tác
POST /services/shipment/cancel/partner_id:1234567 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
"https://services.giaohangtietkiem.vn/services/shipment/cancel/partner_id:1234567"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/cancel/partner_id:1234567",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về ở dạng JSON
{
"success": true,
"message": ""
}
{
"success": false,
"message": "Đơn hàng đã đã ở trạng thái hủy"
}
Parameters
Tham số | Bắt buộc | Mô tả |
---|---|---|
Mã đơn hàng | no | Mã đơn hàng của hệ thống GHTK |
Mã đơn đối tác | no | Mã đơn hàng trên hệ thống của đối tác |
In nhãn đơn hàng
Gửi request theo định dạng
GET /services/label/{{alias_or_code}}
Token: APITokenSample-ca441e70288cB0515F310742
GET /services/label/S1.8663516?original=portrait&page_size=A6 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742"
"https://services.giaohangtietkiem.vn/services/label/S1.8663516?original=portrait&page_size=A6"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/label/S1.8663516?original=portrait&page_size=A6",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Response trả về định dạng PDF
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=""
Content-Transfer-Encoding: binary
Trường hợp có lỗi xảy ra kết quả sẽ trả về với định dạng JSON
{
"success": false,
"message": "Mã vận đơn không hợp lệ, không tìm thấy vận đơn"
}
Mô tả:
Nhãn đơn hàng là tem nhãn được dán lên kiện hàng, ghi rõ các thông tin quan trọng của đơn hàng gồm: mã vận đơn, mã vạch, thông tin sản phẩm, phương thức vận chuyển....
GHTK cung cấp 2 mẫu nhãn đơn hàng, gồm: khổ dọc và khổ ngang .
Ví dụ: Label A5 khổ ngang
Ví dụ: Label A5 khổ dọc
Query parameters
Tham số | Bắt buộc | Mô tả |
---|---|---|
alias_or_code | yes | String - Mã đơn hàng hoặc alias đơn hàng GHTK |
original | no | String - Kiểu in nhãn portrait (in dọc) hoặc landscape (in ngang) (mặc định là portrait) |
page_size | no | String - Khổ in của nhãn A5 , A6 (mặc định là A6) |
Lấy danh sách địa chỉ lấy hàng
GET /services/shipment/list_pick_add
Token: APITokenSample-ca441e70288cB0515F310742
GET /services/shipment/list_pick_add HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742"
"https://services.giaohangtietkiem.vn/services/shipment/list_pick_add"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/list_pick_add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về
{
"success": true,
"message": "",
"data": [
{
"pick_address_id": "88256",
"address": "Số nhà 105, ngõ 13 Lĩnh Nam, Phường Mai Động, Quận Hoàng Mai, Tp. Hà Nội, Lĩnh Nam, Hà Nội",
"pick_tel": "0987654321",
"pick_name": "Adayroi"
},
{
"pick_address_id": "88260",
"address": "1312, Phường 1, Quận Bình Thạnh, TP Hồ Chí Minh",
"pick_tel": "0987654321",
"pick_name": "Classical"
}
]
}
Lấy danh sách địa chỉ cấp 4
Request
GET /services/address/getAddressLevel4?province=h%C3%A0%20n%E1%BB%99i&district=ba%20%C4%91%C3%ACnh&ward_street=%C4%91%E1%BB%99i%20c%E1%BA%A5n&address=20 HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742"
"GET /services/address/getAddressLevel4?province=h%C3%A0%20n%E1%BB%99i&district=ba%20%C4%91%C3%ACnh&ward_street=%C4%91%E1%BB%99i%20c%E1%BA%A5n&address=20"
<?php
$data = array(
"province" => "Hà nội",
"district" => "Quận Ba Đình",
"ward_street" => "Đội Cấn",
"address" => "",
);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/address/getAddressLevel4?" . http_build_query($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về
{
"success": true,
"data": [
"IIG - 75 Giang Văn Minh",
"Vinapaco Building - 142 Đội Cấn",
"THCS Thống Nhất",
"Ngõ 47 Đội Cấn",
"Ngõ 46 Đội Cấn"
]
}
Query parameters
Tham số | Bắt buộc | Mô tả |
---|---|---|
address | no | String - Địa chỉ chi tiết cần lấy danh sách địa chỉ cấp 4, ví dụ: đường Đội Cấn, Ba Đình, Hà Nội |
province | yes | String - Tên tỉnh/thành phố cần lấy danh sách địa chỉ cấp 4 |
district | yes | String - Tên quận/huyện cần lấy danh sách địa chỉ cấp 4 |
ward_street | yes | String - Tên đường/phường cần lấy danh sách địa chỉ cấp 4 |
Lấy danh sách thông tin sản phẩm
Request
GET /services/kho-hang/thong-tin-san-pham?term=laptop HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742"
"GET /services/kho-hang/thong-tin-san-pham?term=laptop"
<?php
$data = array(
"term" => "laptop",
);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/kho-hang/thong-tin-san-pham?" . http_build_query($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả trả về
TH1 : Shop đã từng đăng sản phẩm trên hệ thống GHTK
{
"success": true,
"data" : [
{
"full_name": "Laptop Asus",
"product_code": "23304A3MHLMVMXX625",
"weigh": 2,
"cost": 8000000
},
{
"full_name": "Laptop Dell",
"product_code": "23304A3MHLMVMXX888",
"weigh": 2.5,
"cost": 12000000
}
]
}
TH2 : Sản phẩm chưa từng được đăng lên hệ thống GHTK
{
"success": true,
"data" : []
}
Với trường hợp này thì API đăng đơn phía đối tác gửi lên
product_code: ""
để hệ thống GHTK tạo mã sản phẩm mới
Tham số
Tham số | Bắt buộc | Mô tả |
---|---|---|
term | yes | String - Tên sản phẩm cần lấy thông tin |
API check dịch vụ XFAST
Request
GET /services/shipment/x-team?customer_district%3DQu%E1%BA%ADn+Ba+%C4%90%C3%ACnh%26customer_province%3DH%C3%A0+N%E1%BB%99i%26customer_ward%3DPh%C6%B0%E1%BB%9Dng+%C4%90%E1%BB%99i+C%E1%BA%A5n%26customer_first_address%3D12+TT%26pick_province%3DH%C3%A0+N%E1%BB%99i%26pick_district%3DQu%E1%BA%ADn+Ba+%C4%90%C3%ACnh%26pick_ward%3DPh%C6%B0%E1%BB%9Dng+C%E1%BB%91ng+V%E1%BB%8B HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
curl -X GET -H "Token: APITokenSample-ca441e70288cB0515F310742"
"GET /services/shipment/x-team?customer_district=Quận Ba Đình&customer_province=Hà Nội&customer_ward=Phường Đội Cấn&customer_first_address=12 TT&pick_province=Hà Nội&pick_district=Quận Ba Đình&pick_ward=Phường Cống Vị HTTP/1.1"
<?php
$data = array(
"customer_district" => "Quận Ba Đình",
"customer_province" => "Hà Nội",
"customer_ward" => "Phường Đội Cấn",
"customer_first_address" => "12",
"pick_province" => "Hà Nội",
"pick_district" => "Quận Ba Đình",
"pick_ward" => "Phường Cống Vị"
);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/x-team?" . http_build_query($data),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_HTTPHEADER => array(
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Kết quả thành công
{
"success": true,
"data": {
"2": {
"pick": "Lấy trước 8h30",
"session_val": "2",
"deliver": "Giao trước 10h30"
}
}
}
Kết quả thất bại
{
"success": false,
"message": "Xfast không khả dụng vào thời điểm này"
}
Query parameters
Tham số | Bắt buộc | Mô tả |
---|---|---|
pick_province | yes | String - Tỉnh địa chỉ lấy hàng |
pick_district | yes | String - Quận/ huyện địa chỉ lấy hàng |
pick_ward | no | String - Phường/xã địa chỉ lấy hàng |
pick_street | no | String - Đường phố địa chỉ lấy hàng * Phải có 1 trong 2 param : pick_street hoặc pick_ward |
customer_province | yes | String - Tỉnh địa chỉ giao hàng |
customer_district | yes | String - Quận/ huyện địa chỉ giao hàng |
customer_ward | no | String - Phường/xã địa chỉ giao hàng |
customer_street | no | String - Đường phố địa chỉ giao hàng * Phải có 1 trong 2 param : customer_street hoặc customer_ward |
customer_first_address | yes | String - Chi tiết địa chỉ giao hàng |
customer_hamlet | no | String - Địa chỉ cấp 4 giao hàng |
Webhooks
Giả sử đơn hàng mã “S1.A1.17373471” (mã trên hệ thống khách hàng là “1234567”) được cập nhật “"đã giao hàng thành công”.
Data GHTK sẽ gửi tới callback link của đối tác theo nội dung
{
"partner_id" : "1234567",
"label_id": "S1.A1.17373471",
"status_id": 5,
"action_time": "2016-11-02T12:18:39+07:00",
"reason_code": "",
"reason": "",
"weight": 2.4,
"fee": 15000,
"pick_money": 100000,
"return_part_package": 0
}
Giả sử callback link của đối tác là
https://doitac.example.com/updateShipment?hash=XXX
Request gửi từ máy chủ của GHTK gọi sang hệ thống của đối tác
POST /updateShipment?hash=XXX HTTP/1.1
Host: doitac.example.com
Content-type: application/x-www-form-urlencoded
label_id=S1.A1.17373471&partner_id=1234567&action_time=2016-11-02T12:18:39+07:00&status_id=5&reason_code=&reason=&weight=2.4&fee=1500&return_part_package=0
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d 'label_id=S1.A1.17373471&partner_id=1234567&action_time=2016-11-02T12:18:39+07:00&status_id=5&reason_code=&reason=&weight=2.4&fee=1500&return_part_package=0' \
"https://doitac.example.com/updateShipment?hash=XXX"
<?php
$data = array(
'label_id' => 'S1.A1.17373471',
'partner_id' => 1234567,
'action_time' => '2016-11-02T12:18:39+07:00',
'status_id' =>5,
'reason_code'=> '',
'reason'=> '',
'weight'=> 2.4,
'fee'=> 1500,
'return_part_package'=> 0
);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://doitac.example.com/updateShipment?hash=XXX",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_POSTFIELDS => $data,
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
GHTK sử dụng response HTTP Status code để xác định là có gửi cập nhật cho đối tác thành công hay không.
Nếu nhận được response code 200, GHTK ghi nhận đã cập nhật thành công cho đối tác
HTTP/1.1 200 OK
Nếu không nhận được response, hoặc code khác 200. GHTK sẽ gửi cập nhật lại một lần nữa
HTTP/1.1 500 Internal Server Error
Ngay khi đơn hàng có cập nhật mới, hệ thống GHTK sẽ tự động gửi cập nhật sang hệ thống của đối tác thông qua một URL(callback link) mà đối tác gửi cho kỹ thuật GHTK. Tham khảo thêm bảng mã trạng thái đơn hàng.
Các tham số
Tham số | Mô tả |
---|---|
label_id | String - Mã đơn hàng của hệ thống GHTK |
partner_id | String - Mã đơn hàng thuộc hệ thống của đối tác |
status_id | Integer - Mã trạng thái đơn hàng. Tham khảo bảng mã trạng thái đơn hàng. |
action_time | String ISO 8601 - Thời gian cập nhật trạng thái đơn hàng |
reason_code | String - Mã lý do cập nhật |
reason | String - Lý do chi tiết cập nhật |
weight | Float - khối lượng đơn hàng tính theo kilogram |
fee | Integer - phí ship của đơn hàng (VNĐ) |
return_part_package | Integer - Nếu bằng 1 là đơn giao hàng một phần |
Trạng thái đơn hàng
Các trạng thái chuyển của đơn hàng trên hệ thống GHTK.
Tham số | Mô tả |
---|---|
-1 | Hủy đơn hàng |
1 | Chưa tiếp nhận |
2 | Đã tiếp nhận |
3 | Đã lấy hàng/Đã nhập kho |
4 | Đã điều phối giao hàng/Đang giao hàng |
5 | Đã giao hàng/Chưa đối soát |
6 | Đã đối soát |
7 | Không lấy được hàng |
8 | Hoãn lấy hàng |
9 | Không giao được hàng |
10 | Delay giao hàng |
11 | Đã đối soát công nợ trả hàng |
12 | Đã điều phối lấy hàng/Đang lấy hàng |
13 | Đơn hàng bồi hoàn |
20 | Đang trả hàng (COD cầm hàng đi trả) |
21 | Đã trả hàng (COD đã trả xong hàng) |
123 | Shipper báo đã lấy hàng |
127 | Shipper (nhân viên lấy/giao hàng) báo không lấy được hàng |
128 | Shipper báo delay lấy hàng |
45 | Shipper báo đã giao hàng |
49 | Shipper báo không giao được giao hàng |
410 | Shipper báo delay giao hàng |
Lý do chậm lấy hàng
Các lý do lấy hàng chậm hơn dữ kiến mặc định
Bảng mã reason_code cho trường hợp chậm lấy hàng (status_id = 8)
Mã | Mô tả |
---|---|
100 | Nhà cung cấp (NCC) hẹn lấy vào ca tiếp theo |
101 | GHTK không liên lạc được với NCC |
102 | NCC chưa có hàng |
103 | NCC đổi địa chỉ |
104 | NCC hẹn ngày lấy hàng |
105 | GHTK quá tải, không lấy kịp |
106 | Do điều kiện thời tiết, khách quan |
107 | Lý do khác |
Lý do không lấy được hàng
Mã | Mô tả |
---|---|
110 | Địa chỉ ngoài vùng phục vụ |
111 | Hàng không nhận vận chuyển |
112 | NCC báo hủy |
113 | NCC hoãn/không liên lạc được 3 lần |
114 | Lý do khác |
115 | Đối tác hủy đơn qua API |
Lý do chậm giao hàng
Mã | Mô tả |
---|---|
120 | GHTK quá tải, giao không kịp |
121 | Người nhận hàng hẹn giao ca tiếp theo |
122 | Không gọi được cho người nhận hàng |
123 | Người nhận hàng hẹn ngày giao |
124 | Người nhận hàng chuyển địa chỉ nhận mới |
125 | Địa chỉ người nhận sai, cần NCC check lại |
126 | Do điều kiện thời tiết, khách quan |
127 | Lý do khác |
128 | Đối tác hẹn thời gian giao hàng |
129 | Không tìm thấy hàng |
1200 | SĐT người nhận sai, cần NCC check lại |
Lý do không giao được hàng
Mã | Mô tả |
---|---|
130 | Người nhận không đồng ý nhận sản phẩm |
131 | Không liên lạc được với KH 3 lần |
132 | KH hẹn giao lại quá 3 lần |
133 | Shop báo hủy đơn hàng |
134 | Lý do khác |
135 | Đối tác hủy đơn qua API |
Lý do delay trả hàng
Mã | Mô tả |
---|---|
140 | NCC hẹn trả ca sau |
141 | Không liên lạc được với NCC |
142 | NCC không có nhà |
143 | NCC hẹn ngày trả |
144 | Lý do khác |
B2C API
Mô tả chung
Các sàn thương mại điện tử (B2C) khi sử dụng dịch vụ Giao hàng tiết kiệm (GHTK) có thể tiếp cận theo 2 hướng sau
-
Sử dụng duy nhất 1 tài khoản để đăng đơn trên hệ thống GHTK:
Ưu điểm:
- Dễ kết nối vì chỉ cần quản lý một tài khoản, chỉ cần 1 token duy nhất là có thể đăng được đơn
Nhược điểm:
- GHTK chỉ đối soát và chuyển khoản cho tài khoản của shop B2C, shop B2C phải tự quản lý và đối soát công nợ với các shop của mình
-
Sử dụng nhiều tài khoản để đăng đơn trên hệ thống GHTK: khi đăng đơn phải dùng tài khoản cấp riêng cho từng shop khách hàng của Shop B2C, các tài khoản này được phân biệt bằng token khác nhau
Ưu điểm:
- GHTK sẽ đối soát trực tiếp với các shop khách hàng của Shop B2C, không mất công quản lý đối soát, chuyển khoản.
- Quản lý các đơn hàng của nhiều tài khoản có nguồn từ hệ thống của B2C bằng một tài khoản.
- Shop B2C cần lưu lại và quản lý thông tin xác thực (token) các shop khách hàng của mình.
- Tích hợp phức tạp hơn, cần sử dụng token riêng theo từng shop.
Nếu shop B2C tiếp cận theo hướng 2, thì chỉ cần sử dụng thêm API tạo tài khoản trên hệ thống GHTK, các bước tích hợp khác (đăng đơn, kiểm tra trạng thái, tính phí,…) thì sử dụng các API tương ứng như bình thường, chỉ cần thay đổi thông tin token
Tạo tài khoản
Ví dụ cần tạo một tài khoản trên GHTK với các thông tin như sau:
{
"name": "shop test",
"first_address": "ngõ 2, Phan Bá Vành, Cầu Diễn",
"province": "Hà Nội",
"district": "Bắc Từ Liêm",
"tel": "01234555666",
"email": "shoptest@email.com"
}
Request:
POST https://services.giaohangtietkiem.vn/services/shops/add HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
Host: services.giaohangtietkiem.vn
Content-length: 351
Content-Type: application/x-www-form-urlencoded
name=shop+test&first_address=ng%C3%B5+2%2C+Phan+B%C3%A1+V%C3%A0nh%2C+C%E1%BA%A7u+Di%E1%BB%85n&province=H%C3%A0+N%E1%BB%99i&district=B%E1%BA%AFc+T%E1%BB%AB+Li%C3%AAm&tel=01234555666&email=shoptest%40email.com
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
-H "Content-Type: application/json;" \
-d '{"name":"shop test","first_address":"ngõ 2, Phan Bá Vành, Cầu Diễn","province":"Hà Nội","district":"Bắc Từ Liêm","tel":"01234555666","email":"shoptest@email.com"}' \
"https://services.giaohangtietkiem.vn/services/shops/add"
<?php
$order = <<<HTTP_BODY
{
"name": "shop test",
"first_address": "ngõ 2, Phan Bá Vành, Cầu Diễn",
"province": "Hà Nội",
"district": "Bắc Từ Liêm",
"tel": "01234555666",
"email": "shoptest@email.com"
}
HTTP_BODY;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shops/add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $order,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"Content-Length: " . strlen($order),
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Response thành công:
{
"success": true,
"message": "Thành công",
"data": {
"code": "S55163",
"token": "93A7392A44c99e7Ca395eef1321D03731B844111"
}
}
Response trường hợp email hoặc số điện thoại đã được sử dụng cho tài khoản khác
{
"success": false,
"message": "Email shop này đã tồn tại",
"data": null
}
Response trường hợp tài khoản B2C không có quyền tạo tài khoản mới
{
"success": false,
"message": "Tài khoản của bạn không có quyền tạo tài khoản mới trên GHTK",
"data": null
}
Các tham số:
Tham số | Bắt buộc | Mô tả |
---|---|---|
name | yes | Tên hiển thị của tài khoản |
first_address | yes | Địa chỉ chi tiết của tài khoản (số nhà, ngõ, đường, phường,…) |
province | yes | Tên tỉnh/thành phố, ví dụ: Hà Nội , Thái Bình , |
district | yes | Tên huyện hoặc thành phố trực thuộc tỉnh, ví dụ: Cầu Giấy , Tp Thái Bình |
tel | yes | số điện thoại liên lạc của tài khoản |
yes | email của tài khoản |
Kết quả trả về khi tạo tài khoản thành công:
Tham số | Bắt buộc | Mô tả |
---|---|---|
data.code | yes | Mã tài khoản trên hệ thống GHTK |
data.token | yes | Token của tài khoản |
Tài khoản đã đăng ký trước
Ví dụ cần lấy token của tài khoản có thông tin đăng nhập như sau:
{
"email": "shoptest@email.com",
"password": "1S@fF#K2"
}
Request:
POST https://services.giaohangtietkiem.vn/services/shops/token HTTP/1.1
Host: services.giaohangtietkiem.vn
Token: APITokenSample-ca441e70288cB0515F310742
Content-Type: application/json
{
"email": "shoptest@email.com",
"password": "1S@fF#K2"
}
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742" \
-H "Content-Type: application/json;" \
-d '{"email": "shoptest@email.com", "password": "1S@fF#K2"}' \
"https://services.giaohangtietkiem.vn/services/shops/token"
<?php
$order = <<<HTTP_BODY
{
"email": "shoptest@email.com",
"password": "1S@fF#K2"
}
HTTP_BODY;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => " https://services.giaohangtietkiem.vn/services/shops/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $order,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"Content-Length: " . strlen($order),
"Token: APITokenSample-ca441e70288cB0515F310742",
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
Response thành công:
{
"success": true,
"message": "Thành công",
"data": {
"code": "S19159",
"token": "5568B780966147C0764EDD207af0233516E4c683"
}
}
Response trường hợp thông tin xác thực của tài khoản cần lấy token không đúng
{
"success": false,
"message": "Dữ liệu đăng nhập không hợp lệ"
}
Response trường hợp tài khoản B2C không có quyền lấy token của tài khoản khác
{
"success": false,
"message": "Tài khoản của bạn không có quyền sử dụng API này"
}
Một số shop có thể đã đăng ký sử dụng dịch vụ của GHTK từ trước, trong trường hợp này không cần tạo lại tài khoản mới chỉ cần lấy thông tin token của shop
Các tham số:
Tham số | Bắt buộc | Mô tả |
---|---|---|
yes | Email tài khoản cần lấy token | |
password | yes | Mật khẩu xác thực của tài khoản cần đăng nhập |
Kết quả trả về nếu xác thực thành công:
Tham số | Bắt buộc | Mô tả |
---|---|---|
data.code | yes | Mã tài khoản trên hệ thống GHTK |
data.token | yes | Token của tài khoản |
Đăng đơn
Request:
POST /services/shipment/order HTTP/1.1
Token: APITokenSample-ca441e70288cB0515F310742
X-Refer-Token: B2CToken-hlsheiwquhrksadlfkjahsdfjaaljh
Content-Type: application/json
{
"products": [{
"name": "bút",
"weight": 0.1
}, {
"name": "tẩy",
"weight": 0.2
}],
"order": {
"id": "123123a",
"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_tel": "0911222333",
"tel": "0911222333",
"name": "GHTK - HCM - Noi Thanh",
"address": "123 nguyễn chí thanh",
"province": "TP. Hồ Chí Minh",
"district": "Quận 1",
"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
"tags": [1,7]
}
}
curl -X POST -H "Token: APITokenSample-ca441e70288cB0515F310742X" \
-H "X-Refer-Token: B2CToken-hlsheiwquhrksadlfkjahsdfjaaljh" \
-H "Content-Type: application/json" \
-d '{"products":[{"name":"bút","weight":0.1},{"name":"tẩy","weight":0.2}],"order":{"id":"123123a","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_tel":"0911222333","tel":"0911222333","name":"GHTK - HCM - Noi Thanh","address":"123 nguyễn chí thanh","province":"TP. Hồ Chí Minh","district":"Quận 1","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}}' "https://services.giaohangtietkiem.vn/services/shipment/order"
<?php
$order = <<<HTTP_BODY
{
"products": [{
"name": "bút",
"weight": 0.1
}, {
"name": "tẩy",
"weight": 0.2
}],
"order": {
"id": "123123a",
"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_tel": "0911222333",
"tel": "0911222333",
"name": "GHTK - HCM - Noi Thanh",
"address": "123 nguyễn chí thanh",
"province": "TP. Hồ Chí Minh",
"district": "Quận 1",
"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
}
}
HTTP_BODY;
$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",
"X-Refer-Token: B2CToken-hlsheiwquhrksadlfkjahsdfjaaljh",
"Content-Length: " . strlen($order),
),
));
$response = curl_exec($curl);
curl_close($curl);
echo 'Response: ' . $response;
?>
API đăng đơn giống với API đăng đơn của tài khoản thường nhưng trong request cần gửi thêm thông tin token của tài khoản B2C trong header X-Refer-Token
Ví dụ: shop HappyShop bán hàng trên sàn điện tử SmileB2C
HappyShop có token là
APITokenSample-ca441e70288cB0515F310742
SmileB2C có token là
B2CToken-hlsheiwquhrksadlfkjahsdfjaaljh
Trong request đăng đơn cho tài khoản HappyShop gửi tới từ server SmileB2C cần set thêm header X-Refer-Token
với giá trị là token của tài khoản SmileB2C