NAV
http shell php

Giaohangtiemkiem RESTful API v1.3

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:

Log thay đổi

Version 1.3

Version 1.2

Đơ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 HTTP/1.1
Token: XXX
Content-Type: application/json

{
    "products": [{
        "name": "bút",
        "weight": 0.1
    }, {
        "name": "tẩy",
        "weight": 0.2
    }],
    "order": {
        "province": "TP. Hồ Chí Minh",
        "pick_address": "590 CMT8 P.11",
        "note": "Khối lượng tính cước tối đa: 1.00 kg",
        "tel": "0911222333",
        "pick_district": "Quận 3",
        "address": "123 nguyễn chí thanh",
        "pick_name": "HCM-nội thành",
        "id": "123123a",
        "pick_tel": "0911222333",
        "name": "GHTK - HCM - Noi Thanh",
        "district": "Quận 1",
        "pick_province": "TP. Hồ Chí Minh",
        "is_freeship": "1",
        "pick_date": "2016-09-30",
        "pick_money": 47000,
        "value": 3000000
    }
}
curl -X POST -H "Token: XXXX" \
 -H "Content-Type: application/json" \
 -d '{"products": [{"name":"bút","weight":0.1},{"name":"tẩy","weight": 0.2}],"order": {"province": "TP. Hồ Chí Minh", "pick_address": "590 CMT8 P.11", "note": "Khối lượng tính cước tối đa: 1.00 kg", "tel": "0911222333", "pick_district": "Quận 3", "address": "123 nguyễn chí thanh", "pick_name": "HCM-nội thành", "id": "123123a", "pick_tel": "0911222333", "name": "GHTK - HCM - Noi Thanh", "district": "Quận 1", "pick_province": "TP. Hồ Chí Minh", "is_freeship": "1", "pick_date": "2016-09-30", "pick_money": 47000, "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": {
        "province": "TP. Hồ Chí Minh",
        "pick_address": "590 CMT8 P.11",
        "note": "Khối lượng tính cước tối đa: 1.00 kg",
        "tel": "0911222333",
        "pick_district": "Quận 3",
        "address": "123 nguyễn chí thanh",
        "pick_name": "HCM-nội thành",
        "id": "a4",
        "pick_tel": "0911222333",
        "name": "GHTK - HCM - Noi Thanh",
        "district": "Quận 1",
        "pick_province": "TP. Hồ Chí Minh",
        "is_freeship": "1",
        "pick_date": "2016-09-30",
        "pick_money": 47000,
        "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: XXX",
        "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",
    "products": []
  }
}

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 no 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 teo
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 cần thu hộ. Nếu bằng 0 thì không thu hộ tiền. 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 no String - Tên phường/xã của người nhận hàng hóa
order.street no String - Tên đường/phố của người nhận hàng hóa
order.tel yes String - Số điện thoại người nhận hàng hóa
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êm123
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.deliver_work_shift no Integer - Nếu set bằng 3 đơn hàng sẽ được giao vào buổi tối. Giá trị mặc định bằng 0
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 no Interger (VNĐ) - Giá trị thực đơn hàng, áp dụng tính phí bảo hiểm

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

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
}

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 HTTP/1.1
Token: xxx
curl -X GET -H "Token: XXX" \
  "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"
<?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,
);
$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: XXX",
    ),
));

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

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Đ

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.delivery_type Hình thức vận chuyển: only_hanoi đơn giao nội vùng Hà Nội, only_hochiminh đơn giao nội vùng TP. HCM, between_hanoi_and_hochiminh đơn giao giữa HN và TP. HCM, between_hanoi_hochiminh_and_other_provinces đơn giao giữa HN, TP. HCM tới các tỉnh thành khác

Trạng thái đơn hàng

Sử dụng mã vận đơn của GHTK

GET /services/shipment/S1.A1.17373471 HTTP/1.1
Token: XXX

curl -X GET -H "Token: XXXX" \  
 "https://services.giaohangtietkiem.vn/services/shipment/S1.17373471"
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/S1.17373471",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Sử dụng mã vận đơn của đối tác

GET /services/shipment/partner_id:1234567 HTTP/1.1
Token: XXX

curl -X GET -H "Token: XXX" \
 "https://services.giaohangtietkiem.vn/services/shipment/partner_id:1234567"
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/shipment/partner_id:1234567",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Kết quả trả về ở dạng JSON

{
  "success": true,
  "message": "",
  "order": {
    "label_id": "S1.A1.17373471",
    "partner_id": "1234567",
    "status": 1,
    "created": "2016-10-31 22:32:08",
    "updated": "2016-10-31 22:32:08",
    "pick_date": "2016-11-01",
    "pick_period": "MORNING",
    "deliver_date": "",
    "deliver_period": ""
  }
}

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.

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

Response

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.
created String - Thời gian tạo đơn hàng, định dạng YY-MM-DD hh:mm:ss
updated String - Thời gian cuối cùng cập nhật đơn hàng, định dạng YY-MM-DD hh:mm:ss
pick_date String - Ngày hẹn lấy hàng của đơn hàng nếu có, định dạng YY-MM-DD
pick_period String - Ca lấy hàng, xác định lấy hàng vào buổi sáng hay chiều, nhận một trong hai giá trị MORNING, AFTERNOON
deliver_date String - Ngày hẹn giao đơn hàng nếu có
deliver_period String - Ca giao hàng, xác định giao hàng vào buổi sáng hay chiều, nhận một trong hai giá trị MORNING, AFTERNOON
deliver_message String - Trạng thái giao hàng. Trả về lý do giao hàng delay nếu có: lần 1 - lý do:…, lần 2 - lý do:.., (Delay quá 3 lần sẽ tự động hủy đơ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: XXX

curl -X POST -H "Token: XXXX" \  
 "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: XXX",
    ),
));

$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: XXX

curl -X POST -H "Token: XXX" \
 "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: XXX",
    ),
));

$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

Thay đổi thông tin đơn hàng (ngày lấy, ngày giao, địa chỉ, thông tin liên lạc)

N/A

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”, hệ thống 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
}

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
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' \
  "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,
);
$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;
?>

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Đ)

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
20 Đang trả hàng (COD cầm hàng đi trả)
21 Đã trả hàng (COD đã trả xong 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ỉ/ SĐT người nhận sai, chờ 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

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

Listing urls

Các tham số N/A - không có

Request

GET /services/webhook HTTP/1.1
Token: xxx
curl -X GET -H "Token: XXX" \
  "https://services.giaohangtietkiem.vn/services/webhook"
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/webhook",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Kết quả trả về

{
  "success": true,
  "data": [
    "http://sample.url1.com", "http://sample.url2.com"
  ]
}

Xóa URL

Các tham số URL

Request

POST /services/webhook/del HTTP/1.1
Token: XXX
url=http://delete.sample.url.com
curl -X POST -H "Token: XXX" \  
 "https://services.giaohangtietkiem.vn/services/webhook/del"  \
 -d 'url=http://delete.sample.url.com'
<?php
$data = array(
  'url' => 'http://delete.sample.url.com'
);

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/webhook/del",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
    CURLOPT_POSTFIELDS => $data
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Kết quả trả về khi thành công json { "success": true }

Kết quả trả về khi có lỗi json { "success": false, "message": "URL không tồn tại" }

Thêm URL

Các tham số URL

Request

POST /services/webhook/add HTTP/1.1
Token: XXX
url=http://delete.sample.url.com
curl -X POST -H "Token: XXX" \  
 "https://services.giaohangtietkiem.vn/services/webhook/add"  \
 -d 'url=http://delete.sample.url.com'
<?php
$data = array(
  'url' => 'http://delete.sample.url.com'
);

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/webhook/add",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
    CURLOPT_POSTFIELDS => $data
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Kết quả trả về khi thành công json { "success": true }

Kết quả trả về khi có lỗi json { "success": false, "message": "URL đã tồn tại" }

Địa chỉ

Khu vực GHTK hỗ trợ giao hàng

Trả về các quận/huyện Giaohangtietkiem hỗ trợ giao hàng

GET /services/address/getSupports HTTP/1.1
Token: XXX

curl -H "Token: XXXX" \
  "https://services.giaohangtietkiem.vn/services/address/getSupports"
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://services.giaohangtietkiem.vn/services/address/getSupports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_HTTPHEADER => array(
        "Token: XXX",
    ),
));

$response = curl_exec($curl);
curl_close($curl);

echo 'Response: ' . $response;
?>

Kết quả trả về danh sách các quận/huyện được hỗ trợ giao

{
  "success": true,
  "message": "",
  "data": [
    {
      "province": "Hà Nội",
      "districts": [
        {"code": 1, "name": "Ba Đình", "support": true},
        {"code": 2, "name": "Cầu Giấy", "support": false},
        ....
      ]
    },
    {
      "province": "TP. Hồ Chí Minh",
      "districts": [
        ....
      ]
    }
  ]
}

Định dạng dữ liệu trả về

Dữ liệu trả về ở dạng JSON bao gồm các thông tin