8. Webhook
The webhook flow is used to synchronize the shipment status of GHTK orders to the partner’s system via API integration.
Assume that an order with GHTK tracking code "S1.A1.17373471" (and code "1234567" in customer system) has been updated to "successfully delivered".
Assume the partner’s callback URL is:
https://doitac.example.com/updateShipment?hash=XXX
Data of GHTK will send to the partner’s callback link the following content:
{
"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 sent from GHTK's server to the partner's system
- 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 uses the HTTP Status Code in the response to determine whether the update was successfully received by the partner’s system.
Once receiving response code 200, GHTK will consider the update as successfully delivered to the partner.
HTTP/1.1 200 OK
If no response is received, or if the response code is not 200, GHTK will retry sending the update once.
HTTP/1.1 500 Internal Server Error
List of Parameters Provided to Partners
| Parameter | Data Type | Description |
|---|---|---|
| label_id | String | - GHTK order code |
| partner_id | String | - Partner’s order code |
| status_id | Integer | - Order status code |
| action_time | String | ISO 8601 - Order action time |
| reason_code | String | - Update reason code |
| reason | String | - Detailed update reason |
| weight | Float | - Order weight (in kilograms) |
| fee | Integer | - Shipping fee (in VND) |
| return_part_package | Integer | - Value = 1 if the order was partially delivered |
Order Status
These are the various status transitions that an order can go through in the GHTK system:
| Parameter | Description |
|---|---|
| -1 | Order Canceled |
| 1 | Not Yet Received |
| 2 | Received |
| 3 | Picked Up / Warehoused |
| 4 | Out for Delivery / In Delivery |
| 5 | Delivered / Not Yet Reconciled |
| 6 | Reconciled |
| 7 | Pickup Failed |
| 8 | Pickup Delayed |
| 9 | Delivery Failed |
| 10 | Delivery Delayed |
| 11 | Return Reconciliation Completed |
| 12 | Pickup Assigned / In Pickup |
| 13 | Compensation Order |
| 20 | In Return Process (COD is returning the package) |
| 21 | Returned (COD has completed the return) |
| 123 | Shipper Reported Completed Pickup |
| 127 | Shipper Reported Failed Pickup |
| 128 | Shipper Reported Pickup Delay |
| 45 | Shipper Reported Completed Delivery |
| 49 | Shipper Reported Failed Delivery |
| 410 | Shipper Reported Delivery Delay |
Note: Status codes 123, 127, 128, 45, 49, 410 (reported by shippers) are informational only and do not represent the official status of the order in GHTK's system.
Example: A shipper might update status 123, but due to an error (e.g., accidentally selecting the wrong order), it may be corrected to status 127 later.
Pickup Delay Reasons
Reasons why the pickup is delayed beyond the expected time
reason_code table for pickup delay reasons (status_id = 8)
| Code | Description |
|---|---|
| 100 | Supplier requested pickup in the next working shift |
| 101 | GHTK could not contact the supplier |
| 102 | Supplier does not have the goods ready |
| 103 | Supplier changed address |
| 104 | Supplier scheduled a pickup date |
| 105 | GHTK is overloaded, cannot pick up on time |
| 106 | Weather or other objective conditions |
| 107 | Other reason |
Pickup Failure Reasons
| Code | Description |
|---|---|
| 110 | Address is outside the service area |
| 111 | Items are not eligible for transport |
| 112 | Supplier canceled the order |
| 113 | Supplier delayed/ could not be contacted after 3 attempts |
| 114 | Other reason |
| 115 | Partner canceled the order via API |
Delivery Delay Reasons
| Code | Description |
|---|---|
| 120 | GHTK is overloaded, cannot deliver on time |
| 121 | Recipient requested delivery in the next working shift |
| 122 | Cannot contact the recipient |
| 123 | Recipient scheduled a delivery date |
| 124 | Recipient changed delivery address |
| 125 | Incorrect recipient address, supplier needs to verify |
| 126 | Weather or other objective conditions |
| 127 | Other reason |
| 128 | Partner scheduled a specific delivery time |
| 129 | Package not found |
| 1200 | Incorrect recipient phone number, supplier needs to verify |
Delivery Failure Reasons
| Code | Description |
|---|---|
| 130 | Recipient refused to accept the product |
| 131 | Unable to contact recipient after 3 attempts |
| 132 | Recipient rescheduled delivery more than 3 times |
| 133 | Shop requested to cancel the order |
| 134 | Other reason |
| 135 | Partner canceled the order via API |
Return Delay Reasons
| Code | Description |
|---|---|
| 140 | Supplier scheduled return in next working shift |
| 141 | Cannot contact the supplier |
| 142 | Supplier not at home |
| 143 | Supplier scheduled a return date |
| 144 | Other reason |