Giaohangtiemkiem RESTful API v1.6.3

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

• 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

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.

Tất cả các request đến API service của GHTK sẽ được xác thực theo giá trị `Token` trong header của request

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

Giá trị mặc định của `Content-Type` là `application/x-www-form-urlencoded`

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

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

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 Lưu ý: Đơn vị khối lượng GHTK sử dụng cho từng sản phẩm là KG Lưu ý: Phí ship ban đầu sẽ được tính theo tổng khối lượng các sản phẩm có trong đơn hàng Lưu ý: Nếu đơn hàng được set is_freeship = `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` Lưu ý: Trong trường hợp `pick_address_id` có giá trị hợp lệ, thông tin tỉnh thành, quận huyện,… của điểm lấy sẽ được lấy theo mã địa chỉ này, các trường `pick_province`, `pick_district` không bắt buộc phải gửi lên

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 Lưu ý: * Trong trường hợp `pick_address_id` có giá trị hợp lệ, thông tin tỉnh thành, quận huyện,… của điểm lấy sẽ được lấy theo mã địa chỉ này, các trường `pick_province`, `pick_district` không bắt buộc phải gửi lên * Bổ sung biến deliver_option = xteam để tính gói phí cho xfast

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ưu ý: Trong trường hợp `address` có giá trị hợp lệ, thông tin tỉnh thành, quận huyện,… của điểm lấy sẽ được lấy theo mã địa chỉ này, các trường `province`, `district`, `ward_street` không bắt buộc phải gửi lên

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 Hiện tại API đăng đơn Xfast của GHTK chỉ hỗ trợ đăng đơn Xfast ở ca hiện tại. Nếu dịch vụ Xfast không khả dụng thì đơn hàng sẽ được chuyển thành đơn thường. Quý khách cần sử dụng API này để check dịch vụ Xfast trước khi đăng đơn.

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.

Ví dụ: Đối tác A có callback link là https://doitac.example.com/updateShipment?hash=XXX

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 Lưu ý: GHTK sử dụng HTTP Status code = 200, để xác định có gửi cập nhật sang đối tác thành công hay không nếu server của đối tác trả về code khác 200 hoặc không response sẽ gửi lại cập nhật một lần nữa

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

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 Lưu ý: Tài khoản được tạo qua API, hoàn toàn có thể login theo email và đăng đơn trên hệ thống GHTK như các tài khoản bình thường khác Lưu ý: Nếu khách hàng của shop B2C đã có sẵn tài khoản trên GHTK, thì có thể lấy thông tin token trong mục ‘Sửa thông tin cửa hàng’. Không nhất thiết phải tạo tài khoản mới qua API

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 Lưu ý: Chỉ tài khoản B2C mới được sử dụng API lấy token

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