Ứng dụng làm gì
Nối Odoo với Giao Hàng Tiết Kiệm qua API công khai của hãng, để một phiếu giao
trở thành một kiện GHTK mà không phải rời Odoo.
Tính năng chính
- Báo cước theo tuyến thật: GHTK tính đúng địa chỉ lấy và giao, khối lượng
và giá trị khai của phiếu giao.
- Đẩy đơn khoá theo phiếu giao, gửi làm mã đơn đối tác của GHTK, nên đẩy lại
không tạo ra kiện thứ hai.
- Địa chỉ không cần cấp huyện: GHTK hỏi tỉnh và phường, còn quận/huyện là
tuỳ chọn - đúng bằng bản đồ hai cấp Việt Nam áp dụng từ 01/07/2025. Địa chỉ
ghi theo kiểu nào cũng nhận.
- Thu hộ COD, kèm cờ freeship của GHTK để quyết định người nhận có phải trả
phí giao hay không, theo đúng chính sách giá của bạn.
- Vận đơn ở mọi khổ giấy GHTK hỗ trợ, đính kèm vào phiếu giao.
- Trạng thái tức thời qua webhook, gồm cả các trạng thái do shipper báo mà
GHTK gửi trước khi xác nhận, tất cả ánh xạ sang ngôn ngữ của Odoo.
- Đối soát COD theo đúng cách GHTK phân biệt: GHTK tách "đã giao, chưa đối
soát" khỏi "đã đối soát", và việc đối soát đọc đúng chỗ đó, nên tiền còn nợ
bạn không bao giờ bị tính nhầm là đã nhận.
- Giữ lại phụ phí: phí hàng dễ vỡ, gia cố, nông sản mà GHTK cộng thêm được
ghi theo từng kiện thay vì tan vào một con số tổng.
Ấn bản được Hỗ trợ
- Ấn bản Community
- Ấn bản Enterprise
Kết nối vận chuyển Giao Hàng Tiết Kiệm
Tài liệu này nối Odoo với Giao Hàng Tiết Kiệm. Nó giả định Nền tảng kết nối vận chuyển nội địa
Việt Nam đã được cài, việc này tự động xảy ra khi cài ứng dụng này; tài liệu của ứng dụng nền tảng
nói về phần chung là ghi địa chỉ, so giá và đối soát COD, còn tài liệu này nói riêng phần của GHTK.
Cài đặt
- Vào Ứng dụng, bỏ bộ lọc Ứng dụng mặc định, tìm Kết nối vận chuyển Giao Hàng Tiết Kiệm rồi
bấm Cài đặt.
Lấy thông tin đăng nhập
- Đăng nhập tài khoản doanh nghiệp GHTK và mở phần API.
- Sao chép API token, và mã đối tác nếu GHTK có cấp cho bạn. Mã đối tác được gửi qua header
X-Client-Source và một số tài khoản bắt buộc phải có.
Cấu hình
- Vào Kho vận > Cấu hình > Phương thức Giao hàng và tạo một phương thức với Nhà cung cấp là
Giao Hàng Tiết Kiệm.
- Ở tab Vietnam Shipping, điền GHTK Token và Mã đối tác GHTK nếu có.
- Đặt tỉnh và phường Việt Nam cho liên hệ kho của bạn. GHTK hỏi nơi lấy hàng ở mọi lệnh gọi, kể cả
khi chỉ báo giá, và sẽ không nhận đơn nếu thiếu.
- Bấm Kiểm tra kết nối. Nút này liệt kê các địa điểm lấy hàng đã đăng ký trên tài khoản GHTK;
nếu bạn có điền Mã địa điểm lấy hàng, nó kiểm luôn mã đó có thật trên tài khoản không.
GHTK ghi địa chỉ theo tên chứ không theo mã, nên hãng này không có danh mục địa giới phải đồng bộ.
Họ hỏi tỉnh và phường, còn quận/huyện là tuỳ chọn - đúng bằng dạng hai cấp Việt Nam áp dụng từ
01/07/2025 - nên địa chỉ ghi theo kiểu nào cũng nhận.
GHTK không có môi trường thử
GHTK chỉ chạy một hệ thống. Họ không công bố sandbox nào - host staging mà các tài liệu tích hợp cũ
nhắc tới thậm chí không có bản ghi DNS - nên mọi lần đẩy đơn đều sinh vận đơn thật, bưu tá
thật tới lấy hàng, và phát sinh cước thật.
Module không giả vờ ngược lại. Khi Test Environment còn bật, bạn làm được mọi thứ không tạo ra
cái gì: báo giá thật, danh sách địa điểm lấy hàng, tra trạng thái, kiểm tra kết nối. Chỉ riêng đẩy
đơn bị chặn, kèm câu giải thích vì sao. Tắt cờ đó đi khi bạn sẵn sàng gửi hàng - và đó chính là lúc
bạn xác nhận rằng kiện hàng là thật.
Muốn chạy thử trọn đường trước khi vào việc, hãy đẩy một kiện nhỏ không thu hộ rồi huỷ ngay trên
phiếu giao. GHTK cho huỷ tới khi bưu tá chưa lấy hàng.
Các tuỳ chọn đáng đặt
- Mã địa điểm lấy hàng - nếu tài khoản GHTK của bạn có nhiều địa điểm lấy hàng đã đăng ký, hãy
điền mã của địa điểm cần lấy vào đây; nút Kiểm tra kết nối liệt kê sẵn cho bạn. GHTK sẽ tới
lấy đúng điểm đó. Nhưng nó không miễn cho bạn phần tỉnh và phường của kho: tài liệu của họ nói hai
trường này thành tuỳ chọn khi đã có mã, đo trên hệ thống thật thì không - yêu cầu bị từ chối cho
tới khi có đủ cả hai.
- Phương thức vận chuyển - đường bộ hay đường bay.
- Bên trả phí giao, Người nhận được xem hàng, Bàn giao - mặc định cho mọi kiện, đổi
theo từng phiếu giao trong khối Vận chuyển. Bên trả phí chính là cờ is_freeship của GHTK:
cửa hàng trả và GHTK trừ phí giao vào khoản chuyển trả, hay người nhận trả ở cửa cộng thêm vào
tiền hàng. Bàn giao là pick_option của GHTK: bưu tá đến lấy, hay cửa hàng mang ra bưu cục
GHTK. GHTK không có trường cho quy tắc xem hàng, nên nó được ghi ở đầu ghi chú cho bưu tá.
- Khổ vận đơn GHTK - A5, A6, A7 hoặc 50×72 mm.
Webhook
- Trên phương thức giao hàng, bấm Sinh khoá bí mật mới và sao chép Webhook URL.
- Nối khoá bí mật vào URL đó dưới dạng tham số hash, thành
.../viin_delivery/webhook/ghtk/<id>?hash=<khoá bí mật>.
- Đăng ký nguyên URL đó, kèm cả hash, làm địa chỉ callback với GHTK.
GHTK không ký callback; việc biết được hash trong URL chính là bằng chứng callback là thật, nên nó
được so sánh theo thời gian hằng định và khoá bí mật nên đặt dài. GHTK cũng gửi callback dạng form
chứ không phải JSON - Odoo đọc được cả hai, không cần cấu hình gì thêm.
Đối soát COD
GHTK minh bạch một cách hiếm thấy về chính dòng tiền của họ, và ứng dụng này dùng đúng điểm đó. Họ
tách trạng thái 5, "đã giao hàng, chưa đối soát", khỏi trạng thái 6, "đã đối soát" - và chỉ
trạng thái thứ hai mới nghĩa là tiền đã thực sự về tay bạn.
Vì vậy nút Lấy từ hãng chỉ báo những kiện GHTK đã chuyển sang trạng thái 6. Nếu chưa có kiện
nào, nó nói rõ đang có bao nhiêu kiện nằm ở trạng thái 5 thay vì trả về bảng kê rỗng, để khoảng cách
giữa "đã giao" và "đã trả tiền" nhìn thấy được chứ không âm thầm biến mất. Tính trạng thái 5 thành
doanh thu chính là cách một cửa hàng tưởng mình đã được trả tiền trong khi chưa.
Dùng hằng ngày
Bấm Gửi sang hãng trên phiếu giao. Số phiếu giao được gửi cho GHTK làm mã đơn đối tác, và họ chống
trùng theo trường này, nên đẩy lại sẽ trỏ về đúng kiện đã có.
GHTK gửi hai loại trạng thái: loại đã xác nhận, và loại bưu tá báo từ điện thoại sớm hơn một chút
(mã 123, 127, 128, 45, 49, 410). Cả hai đều được ghi nhận và cùng ánh xạ về một chỗ trong Odoo, nên
dòng thời gian chạy ngay khi bưu tá báo chứ không đợi hậu kỳ cập nhật.
Xử lý sự cố
"Cần cung cấp token hợp lệ"
Token thiếu hoặc sai. GHTK trả lỗi này bên trong một HTTP 200 kèm success: false, và Odoo nâng
thành lỗi thật chứ không coi là thành công.
Khách bị thu nhiều hơn dự kiến
Kiểm tra ô Phí giao tính trong COD. Khi tắt, GHTK cộng phí giao vào số tiền thu ở cửa.
Kiện đã giao nhưng không có trong bảng kê
GHTK chưa đối soát kiện đó. Nó sẽ xuất hiện khi GHTK chuyển sang trạng thái 6; thông báo trên bảng
kê cho biết đang có bao nhiêu kiện phải chờ.
Phần mềm này và các tệp liên kết ("Phần mềm")
được sử dụng (chạy, tuỳ biến, chạy sau khi được tuỳ biến)
chỉ khi bạn mua được giấy phép có hiệu lực từ tác giả,
điển hình như qua các Ứng dụng Odoo, hoặc trong trường hợp
bạn nhận được thoả thuận bằng văn bản từ tác giả của Phần mềm (chi tiết tại tệp COPYRIGHT).
Bạn có thể phát triển các phân hệ Odoo có sử dụng Phần mềm như một Thư viện (thường là phụ thuộc vào, nhập vào và sử dụng nguồn của nó)
nhưng không sao chéo bất kỳ mã nguồn hay tài liệu nào thuộc Phần mềm. Bạn có thể phân phối những phân hệ này theo giấy phép
mà bạn lựa chọn, miễn sao nội dung giấy phép đó tương tích với điều khoản của Giấy phép Phần mềm Độc quyền Odoo
(ví dụ: LGPL, MIT hay bất kỳ loại giấy phép phần mềm độc quyền nào tương tự vậy).
Nghiêm cấm phát hành, phân phối, cấp phép lại hoặc bán bản sao của Phần mềm hoặc
bản sao
Phần mềm đã được sửa đổi.
Thông báo bản quyền và chấp thuận nêu trên buộc phải được bao gồm trong tất cả các bản sao hoặc các phần quan trọng của Phần mềm.
PHẦN MỀM ĐƯỢC CUNG CẤP "NGUYÊN TRẠNG", KHÔNG BẢO ĐẢM DƯỚI BẤT KỲ HÌNH THỨC NÀO, ĐƯỢC THỂ HIỆN RÕ RÀNG HOẶC NGỤ Ý, KHÔNG GIỚI HẠN
ĐẢM BẢO VỀ CÁC BẢO ĐẢM NGỤ Ý VỀ KHẢ NĂNG THƯƠNG MẠI, PHÙ HỢP VỚI MỤC ĐÍCH CỤ THỂ VÀ KHÔNG VI PHẠM.
TRONG MỌI TRƯỜNG HỢP SẼ KHÔNG CÓ TÁC GIẢ HOẶC CHỦ SỞ HỮU BẢN QUYỀN NÀO CHỊU TRÁCH NHIỆM VỀ BẤT KỲ KHIẾU NẠI,
THIỆT HẠI HOẶC TRÁCH NHIỆM PHÁP LÝ KHÁC NÀO TRONG PHẠM VI HỢP ĐỒNG, CÁC THIỆT HẠI HOẶC CÁCH KHÁC, PHÁT SINH TỪ, NGOÀI HOẶC
CÓ LIÊN KẾT VỚI PHẦN MỀM HOẶC VIỆC SỬ DỤNG HOẶC KINH DOANH KHÁC TẠI PHẦN MỀM.
