TỔNG QUAN:
Tích hợp đầy đủ API Giao Hàng Tiết Kiệm (GHTK) cho OpenCart 4.x. Tính phí
real-time, tự động đăng đơn, webhook cập nhật trạng thái, và dashboard quản lý
đơn hàng với xử lý hoàn trả.

TÍNH NĂNG CHÍNH:
- 2 môi trường: Staging + Production (token API riêng biệt)
- Hỗ trợ mã đối tác (Partner Code - header X-Client-Source)
- Nút "Kiểm tra kết nối" trong admin
- Tính phí vận chuyển real-time qua API GHTK
- Cache phí ship với TTL cấu hình được (mặc định 30 phút)
- Phụ phí nhiên liệu cấu hình được (mặc định 10.29%)
- Hình thức vận chuyển: Đường bộ hoặc Đường bay
- Ai trả phí ship: Người mua hoặc Shop trả (miễn phí ship)
- Hỗ trợ thuế và khu vực giao hàng (Tax Class & Geo Zone)
- Song ngữ: Tiếng Anh + Tiếng Việt

TỰ ĐỘNG QUẢN LÝ ĐƠN HÀNG:
- Tự động đăng đơn lên GHTK khi khách checkout (qua hệ thống event OpenCart)
- Nhận diện COD thông minh: đơn COD chỉ đăng khi admin chuyển Đang xử lý
- Đơn thanh toán online tự động đăng ngay
- Tự động huỷ đơn trên GHTK khi admin huỷ trong OpenCart
- Chống đăng đơn trùng lặp
- Webhook: nhận đẩy trạng thái từ GHTK (30+ mã trạng thái)
- Ánh xạ trạng thái cấu hình được (Đã giao/Hoàn thành/Xác nhận hoàn trả)

DASHBOARD QUẢN LÝ ĐƠN HÀNG (ADMIN):
- Thống kê: Tổng, Đã giao, Đang hoàn, Đã hoàn, Chờ xác nhận, Đã huỷ
- Lọc nâng cao: Mã đơn OC, mã vận đơn GHTK, trạng thái, khoảng ngày
- Bảng đơn hàng phân trang (20 đơn/trang)
- Thao tác: Đồng bộ trạng thái, Huỷ đơn, In nhãn, Đăng đơn chờ, Xác nhận hoàn trả
- In nhãn hàng loạt với ghép PDF (dùng Ghostscript)
- Theo dõi trạng thái in
- Widget đơn COD chờ xử lý (tối đa 50 đơn)

QUẢN LÝ HOÀN TRẢ:
- Tự động nhận diện trạng thái đang hoàn/đã hoàn từ GHTK
- Admin xác nhận hoàn trả thủ công
- Tự động khôi phục tồn kho (sản phẩm + tuỳ chọn)
- Ghi nhận người xác nhận và thời gian
- Cập nhật trạng thái đơn OpenCart

ĐỊA CHỈ & TRỌNG LƯỢNG:
- Ánh xạ custom field cho Quận/Huyện và Phường/Xã
- Chuyển đổi trọng lượng: kg, g, lb, oz sang gram
- Trọng lượng mặc định cấu hình được (500g)
- Hỗ trợ kích thước sản phẩm (dài, rộng, cao tính bằng cm)

CÁC ENDPOINT API GHTK SỬ DỤNG:
- GET /services/authenticated - Xác thực token
- GET /services/shipment/fee - Tính phí vận chuyển
- POST /services/shipment/order - Đăng đơn
- GET /services/shipment/v2/{tracking} - Tra cứu trạng thái
- POST /services/shipment/cancel/{tracking} - Huỷ đơn
- GET /services/shipment/list_pick_add - Danh sách kho hàng
- GET /services/label/{tracking} - In/tải nhãn vận đơn PDF
- Webhook POST callback - Nhận cập nhật trạng thái

KỸ THUẬT:
- Bảng CSDL: oc_ghtk_order (17 cột)
- Event hook: catalog/model/checkout/order.addHistory/after
- Ánh xạ 30+ mã trạng thái GHTK
- Tự động cấp quyền khi cài đặt
- Gỡ cài đặt sạch
- Bảo mật: SSL, timeout 15 giây, kiểm tra quyền, chống SQL injection