8. Webhook
Luồng webhook được sử dụng để đồng bộ trạng thái mã vận đơn GHTK tới hệ thống của đối tác tích hợp APIs.
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".
Giả sử callback link của đối tác là
https://doitac.example.com/updateShipment?hash=XXX
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
}
Request gửi từ máy chủ của GHTK gọi sang hệ thống của đối tác
- HTTP
- CURL
- PHP
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
Danh sách tham số cung cấp cho đối tác
| Tham số | Kiểu dữ liệu | 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 |
| 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ưu ý: Các trạng thái cập nhật của Shipper 123, 127, 128, 45, 49, 410 chỉ mang tính chất thông báo thông tin, không phải trạng thái của đơn hàng trên GHTK.
Ví dụ Shipper có thể cập nhật 123 nhưng vì lý do khách quan (ví dụ: thao tác nhầm đơn) sau đó có thể cập nhật lại 127
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 |