NAV
http shell php

Giaohangtiemkiem RESTful API v1.6.3

Log thay đổi GHTK

Version 1.6.3

Version 1.6.2

Version 1.6.1

Version 1.6

Version 1.5.5

Version 1.5.4

Version 1.5.3

Version 1.5.2

Version 1.5.1

Version 1.5

Version 1.4.5

Version 1.4.4

Version 1.4.3

Version 1.4.2

Version 1.4.1

Version 1.3

Version 1.2

Cấu hình chung

Môi trường

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-urlencodedaplication/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:

Đơ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  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  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ị gramkilogram, 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ị codpost, 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

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

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

Nhãn đơn hàng A5 khổ ngang

Ví dụ: Label A5 khổ dọc

Nhãn đơn hàng 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ô 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ô 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ô 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ô 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ô 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

  1. 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

  2. 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.
    Nhược điểm:
    • 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
email 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ả
email 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

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