1. Nhân viên tạo đơn giao hàng trong EzyDelivery với phương thức giao hàng Chuyển phát nhanh và chọn dịch vụ Giao Hàng Tiết Kiệm.
2. EzyDelivery gửi đơn sang GHTK, nhận về mã vận đơn GHTK và in tem.
3. Trong quá trình giao, GHTK gọi lại (webhook) về hệ thống, EzyDelivery cập nhật trạng thái đơn theo thời gian thực.

Chuẩn bị

Cấu hình dịch vụ GHTK

• Khác với Viettel Post, khi lưu EzyDelivery không gọi thử sang GHTK, nên token sai vẫn lưu được. Lỗi token chỉ lộ ra ở lần gửi đơn đầu tiên, vì vậy nên tạo thử một đơn sau khi cấu hình.
• Token GHTK không tự hết hạn. Khi tạo lại token trên trang GHTK, nhớ cập nhật lại ô Khoá bí mật.
• Khi sửa các ô khác, cứ để nguyên ô Khoá bí mật đang hiển thị dạng ẩn, hệ thống sẽ giữ giá trị cũ.

Đặt làm dịch vụ mặc định (tuỳ chọn)

Ánh xạ tiền tố đơn vị hành chính

[
  { "type": "PROVINCE", "prefix": "T." },
  { "type": "CITY", "prefix": "TP." },
  { "type": "DISTRICT_IN_CITY", "prefix": "Q." },
  { "type": "DISTRICT_IN_PROVINCE", "prefix": "H." },
  { "type": "TOWN_IN_PROVINCE", "prefix": "TX." },
  { "type": "WARD", "prefix": "X." },
  { "type": "WARD_IN_CITY", "prefix": "P." },
  { "type": "TOWN", "prefix": "TT." }
]

• type: loại đơn vị hành chính, khớp với loại bạn chọn khi tạo tỉnh/thành phố, quận/huyện, phường/xã trên trang quốc gia.
• prefix: tiền tố được thêm trước tên đơn vị khi gửi sang GHTK. Ví dụ phường Bến Nghé có loại WARD_IN_CITY sẽ thành P. Bến Nghé.

Cấu hình webhook trên GHTK

https://shop.example.com/callback/GHTK?hash=abc123xyz

• Đường dẫn trên thuộc trang web (web plugin), không phải trang quản trị. Tên miền phải truy cập được từ Internet và nên dùng https.
• Mỗi lần nhận webhook, EzyDelivery kiểm tra tham số hash trên đường dẫn. Thiếu hash sẽ bị từ chối với lỗi hash: required, hash không khớp Khoá máy khách sẽ bị từ chối với lỗi hash: invalid.
• Nếu chưa điền Khoá máy khách mà GHTK vẫn gọi webhook, hệ thống sẽ báo lỗi no ghtk client key.
• Dữ liệu GHTK gửi về phải có partner_id và status_id, nếu thiếu sẽ bị từ chối (partnerId: required, statusId: required).
• EzyDelivery chỉ chấp nhận cập nhật cho đơn mà nó đã tạo và có mã vận đơn khớp với label_id GHTK gửi về. Các đơn tạo trực tiếp trên trang GHTK sẽ bị bỏ qua (trả về deliveryOrder: notFound).

Tạo đơn giao hàng qua GHTK

1. Vào Các yêu cầu giao hàng (/ezydelivery/shipping-requests) và mở yêu cầu cần giao.
2. Bấm Tạo vận đơn, kiểm tra Tổng số cân (kg).
3. Ở ô Dịch vụ vận chuyển, chọn Giao Hàng Tiết Kiệm (chỉ hiện khi phương thức giao hàng là chuyển phát nhanh).
4. Bấm Tạo hoặc Tạo và hoàn thành.

Nhãn đặc tính hàng hoá

Kết quả gửi đơn

• Thành công: đơn chuyển sang trạng thái Đã gửi yêu cầu, mã vận đơn GHTK (label) được lưu làm mã vận đơn của đơn, và tem được in ngay. Các thông tin GHTK trả về (phí vận chuyển, phí bảo hiểm, thời gian lấy và giao dự kiến, mã phân loại, ca lấy và ca giao, ...) được lưu kèm đơn.
• Thất bại: đơn chuyển sang trạng thái Gửi yêu cầu thất bại, nội dung lỗi GHTK trả về (thông báo, mã lỗi, mã log) được lưu vào đơn để xem lại. Sau khi sửa nguyên nhân có thể gửi lại.

Cập nhật trạng thái đơn

Xử lý sự cố thường gặp