- ỨNG DỤNG
- Kết nối vận chuyển GHN Express 18.0
| Số dòng Code | 754 |
| Tên kỹ thuật | viin_delivery_ghn |
| Giấy phép | OPL-1 |
| Website | https://viindoo.com/apps/modules/18.0/viin_delivery_ghn |
| Đọc mô tả cho | |
| Yêu cầu các App | Invoicing (account) Discuss (mail) Inventory (stock) |
| Bao gồm Các phụ thuộc | Ghi nhật ký API Request Nền tảng kết nối vận chuyển nội địa Việt Nam |
Ứng dụng làm gì
Nối Odoo với Giao Hàng Nhanh qua REST API công khai của hãng, để một phiếu giao trở thành một kiện GHN mà không ai phải gõ lại địa chỉ vào trang quản trị của hãng.
Tính năng chính
- Cước và thời gian giao trước khi chốt: GHN báo giá đúng tuyến, khối lượng và kích thước của phiếu giao, kèm ngày cam kết giao, cả hai hiện trên đơn bán.
- Đẩy đơn không thể thu tiền khách hai lần: số phiếu giao được gửi làm mã đơn đối tác của GHN, nên đẩy lại một lần nữa sẽ trả về đúng kiện đã có thay vì tạo kiện thứ hai.
- Thu hộ COD, với hạn mức của GHN được kiểm ngay trong Odoo trước khi gửi request, chứ không phải đợi hãng từ chối.
- Vận đơn khổ A5, 80x80 và 52x70, tải về và đính kèm vào phiếu giao.
- Huỷ đơn khi GHN còn cho phép, và báo rõ khi đã quá hạn huỷ.
- Trạng thái tức thời qua webhook, với toàn bộ bộ mã trạng thái của GHN được ánh xạ sang ngôn ngữ của Odoo, mỗi sự kiện thành một mốc trên dòng thời gian của phiếu giao.
- Đối soát tiền COD: GHN báo từng lần chuyển tiền thu hộ qua webhook, và các báo cáo đó được khớp ngược về đúng phiếu giao, nên trả thiếu là thấy được.
- Cả hai bản đồ địa giới: tỉnh và phường hai cấp có từ 01/07/2025 để tạo đơn, và mã ba cấp cũ của GHN cho các API tính cước và thời gian giao vốn vẫn đòi mã cũ. Phường được nạp khi cần chứ không nạp hết một lượt.
- Môi trường thử và thật chỉ là một công tắc trên phương thức giao hàng, nên việc tích hợp được chứng minh xong mới có kiện hàng thật chạy.
Ấn bản được Hỗ trợ
- Ấn bản Community
- Ấn bản Enterprise
Kết nối vận chuyển GHN Express
Tài liệu này nối Odoo với Giao Hàng Nhanh để một phiếu giao trở thành một kiện GHN: có giá, được đẩy đơn, có nhãn và theo dõi được mà không ai phải mở cổng quản trị của GHN.
Tài liệu 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 cho mọi hãng - ghi địa chỉ, so giá, đối soát COD - còn tài liệu này nói riêng phần của GHN.
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 GHN Express rồi bấm Cài đặt.
Lấy thông tin đăng nhập
- Tạo tài khoản tại khachhang.ghn.vn cho môi trường thật, hoặc tại 5sao.ghn.dev cho môi trường thử. Đây là hai tài khoản tách biệt: token môi trường thử không dùng được ở môi trường thật.
- Mở phần thiết lập tài khoản và sao chép API token cùng Shop ID.
- Điền địa chỉ lấy hàng cho cửa hàng, nếu luồng đăng ký chưa hỏi tới.
Bước cuối không phải tuỳ chọn, và đây là chỗ hay hỏng nhất. Một cửa hàng đăng ký xong mà chưa có địa chỉ vẫn là tài khoản hợp lệ: token dùng được, cửa hàng tồn tại, danh mục địa giới tải về bình thường. Nhưng GHN từ chối tính cước và từ chối đẩy đơn lấy từ cửa hàng đó, chỉ trả về HTTP 400 kèm mã cửa hàng. Nút Kiểm tra kết nối phát hiện đúng tình huống này và nói thẳng ra trong một câu, nên hãy bấm nó trước tiên.
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à GHN Express.
- Ở tab Vietnam Shipping, điền GHN Token và GHN Shop ID.
- Cứ để Môi trường thử. Khi đó Odoo nói chuyện với dev-online-gateway.ghn.vn và không có kiện hàng thật nào được tạo.
- Bấm Kiểm tra kết nối.
- Bấm Đồng bộ tỉnh và phường.
Về bước cuối: Việt Nam bỏ cấp huyện từ 01/07/2025, và GHN trả lời trên cả bản đồ hai cấp mới lẫn bản đồ ba cấp cũ. Không bản đồ nào phủ hết cả nước - đo trên sandbox của chính GHN, Hà Nội và TP.HCM bị từ chối ở bản đồ mới nhưng chấp nhận ở bản đồ cũ, còn Hải Phòng và Đà Nẵng thì ngược lại. Vì vậy cả hai danh mục đều được nạp; báo giá và đẩy đơn đều thử bản đồ mà phương thức giao hàng đang đặt trước, rồi lùi sang bản đồ kia, và chỉ báo không định tuyến được khi GHN đã từ chối cả hai. Phường của danh mục cũ được nạp theo từng quận/huyện vào lần đầu có thứ gì cần tới, nên lần báo giá đầu tiên tới một thành phố mới sẽ chậm hơn các lần sau.
GHN không có việc này
GHN không công bố endpoint nào để yêu cầu bưu tá giao lại sau một lần giao hỏng - API đơn hàng của họ chỉ có tạo, sửa, huỷ và hoàn. Nút Giao lại vì thế nói thẳng điều đó chứ không giả vờ; hãy hẹn lần giao tiếp theo trực tiếp với GHN, hoặc duyệt hoàn khi họ bỏ cuộc.
Huỷ và hoàn được GHN trả lời theo từng kiện, nằm bên trong một HTTP 200. Kiện nào bị từ chối - đã đi quá xa để huỷ, hoặc chưa tới trạng thái hoàn được - sẽ hiện đúng lý do của GHN, và phiếu giao giữ nguyên trạng thái cũ. Không chỗ nào ở đây coi mã 200 là "xong".
Các tuỳ chọn đáng đặt
- GHN Service - cứ để Chọn theo khối lượng thì dịch vụ đúng sẽ được chọn từ chính kiện hàng: dịch vụ hàng nhẹ của GHN dưới 20 kg, hàng nặng từ 20 kg trở lên, và hàng nặng mỗi khi một phiếu giao được đóng thành nhiều hơn một thùng - đây là yêu cầu của GHN. Ép cứng một dịch vụ hiếm khi là điều bạn muốn: đo trên tài khoản thật, kiện 1 kg Hà Nội - TP.HCM tốn 34.000 ₫ ở dịch vụ hàng nhẹ và 210.000 ₫ ở hàng nặng, trong khi kiện 25 kg lại rẻ hơn ở hàng nặng so với hàng nhẹ.
- 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. GHN nhận bên trả phí qua payment_type_id và quy tắc xem hàng qua required_note; GHN luôn đến lấy nên không gửi mục bàn giao.
- Khai giá kiện hàng - khai giá trị hàng để được bồi thường khi mất kiện. GHN thu một tỷ lệ phần trăm trên giá trị khai, tối đa 5.000.000 ₫.
- Hạn mức COD - bản thân GHN từ chối quá 50.000.000 ₫ mỗi kiện. Đặt hạn mức thấp hơn sẽ chặn số thu hộ quá lớn ngay khi người dùng còn ở trên phiếu giao.
Webhook
Không có webhook thì trạng thái kiện hàng chỉ nhích khi Odoo tự hỏi - theo vòng quét mỗi giờ. Có webhook thì dòng thời gian cập nhật theo bước chân bưu tá, và việc đối soát COD mới thực hiện được.
Trước khi bắt đầu, hãy kiểm tra Odoo của bạn có địa chỉ HTTPS công khai. GHN gọi tới bạn, từ máy chủ của họ, nên một Odoo chỉ truy cập được qua localhost hay trong mạng nội bộ công ty sẽ không bao giờ nhận được callback, dù đăng ký đúng đến đâu.
- Trên phương thức giao hàng, bấm Sinh khoá bí mật mới, rồi sao chép Webhook URL. Nó có dạng https://odoo-cua-ban.example.com/viin_delivery/webhook/ghn/12.
- Đăng nhập developer.ghn.vn, mở menu dưới tên bạn ở góc trên bên phải và chọn Cấu hình webhook - hoặc vào thẳng /account/webhook.
- Ở tab Order, dán URL vào ô URL Endpoint.
- Trong mục Header tùy chỉnh, thêm X-Webhook-Secret với đúng khoá vừa sinh. Đây là thứ duy nhất phân biệt callback thật của GHN với bất kỳ ai đoán trúng URL, vì GHN không ký callback.
- Trong mục Quyền, tích các sự kiện bạn cần. Xem bảng dưới để biết cái nào đáng bật.
- Timeout và Số lần retry cứ để mặc định nếu không có lý do riêng. Mười giây và ba lần retry là hợp với một Odoo không quá tải.
- Bấm Tạo webhook. GHN có cache cấu hình, nên hãy chờ khoảng mười lăm phút trước khi callback đầu tiên về tới.
Nên bật sự kiện nào
| Sự kiện | Nó làm được gì cho bạn |
|---|---|
| switch_status | Đẩy kiện hàng đi qua dòng thời gian. Bắt buộc bật. |
| cod | Kích hoạt khi GHN chuyển tiền thu hộ về. Bắt buộc nếu muốn đối soát COD - xem mục dưới. |
| create | Xác nhận GHN đã nhận đơn. Odoo vốn đã biết vì chính nó gọi; bật cũng không hại gì. |
| update_weight | GHN cân lại kiện. Nên bật: thường kéo theo thay đổi cước. |
| update_cod, | Số tiền, cước hoặc bên trả cước bị đổi ở phía GHN. Hãy bật |
| update_fee, | nếu có người vừa sửa đơn trong cổng GHN vừa làm trên Odoo. |
| update_payment_type | |
| update_partial_return | Người nhận lấy một phần và trả lại phần còn lại. |
Bốn công tắc Bổ sung dữ liệu không kích hoạt sự kiện nào, chúng thêm trường vào payload:
- pod - link bằng chứng giao hàng, gửi một lần, vào lúc chuyển sang đã giao. Odoo lưu nó trên mục dòng thời gian, tên là Bằng chứng giao hàng, chính là thứ bạn đưa ra khi khách nói chưa hề nhận được hàng. Riêng cái này đã đáng bật.
- warehouse - tên kho hiện tại, hiện ở cột vị trí của sự kiện.
- shipper - tên và số điện thoại bưu tá.
- fee - chi tiết cước.
GHN chờ gì ở phía bạn
Odoo trả 200 cho mọi callback nó đọc được, kể cả callback nó quyết định không xử lý - và đó là điều bạn muốn: GHN coi mọi mã khác là thất bại rồi gọi lại theo đường cong giãn dần - 30 giây, 2 phút, 5 phút, kéo tới 12 tiếng - cho tới hết số lần retry bạn đặt. Mã 4xx không phải 408 hay 429 bị coi là hỏng vĩnh viễn và callback bị bỏ luôn.
Một điều nên biết nếu có callback hỏng thật: GHN giao theo thứ tự trên từng kiện hàng, nên một callback cứ hỏng sẽ chặn các callback phía sau của chính kiện đó cho tới khi nó thành công hoặc bị bỏ. Các kiện khác không ảnh hưởng. Khi máy chủ của bạn sống lại, toàn bộ phần tồn của kiện đó được đẩy về một lượt, đúng thứ tự.
Callback trùng là chuyện bình thường. GHN có thể gửi cùng một sự kiện hai lần, và bắn nhiều callback cho một thay đổi. Odoo loại trùng theo kiện hàng, loại sự kiện và thời điểm, nên chuyện này không gây hại gì.
Môi trường thử và môi trường thật là hai tài khoản tách biệt, webhook cũng vậy: cấu hình ở cổng môi trường thử không tự áp sang môi trường thật. Khi chạy thật, hãy cấu hình lại ở đó.
Đối soát COD
GHN không công bố báo cáo đối soát. Thứ họ có công bố là callback cod, bắn ra khi họ chuyển tiền thu hộ về cho bạn, và bảng kê được dựng từ đúng dữ liệu đó. Vì vậy sự kiện cod bắt buộc phải được bật trên webhook; nếu không bật, nút Lấy từ hãng sẽ nói rõ điều đó chứ không trả về một bảng kê rỗng.
Mọi bước sau đó giống như với hãng khác - xem tài liệu của ứng dụng nền tảng.
Dùng hằng ngày
Bấm Gửi sang hãng trên phiếu giao là kiện được đẩy sang GHN. Số phiếu giao được gửi cho GHN làm client_order_code, và GHN chống trùng theo trường này: đẩy cùng một phiếu giao hai lần sẽ trả về đúng kiện đã có chứ không tạo kiện thứ hai, nên đẩy lại sau khi bị timeout là an toàn.
In vận đơn tải vận đơn theo khổ đã đặt trên phương thức giao hàng - A5, 80×80 hoặc 52×70 mm - và đính vào phiếu giao.
Huỷ đơn chạy được khi GHN còn cho phép. Khi kiện đã giao, đã hoàn hoặc đã huỷ, Odoo từ chối và bảo bạn mở yêu cầu hoàn với GHN thay vì huỷ.
Xử lý sự cố
"GHN does not recognise ... in its legacy address catalogue"
GHN đã từ chối địa chỉ này trên cả hai bản đồ. Thường gặp nhất với các đặc khu đảo lập năm 2025 (Bạch Long Vĩ, Hoàng Sa, Trường Sa, Côn Đảo): chúng chỉ tồn tại ở bản đồ hai cấp, mà máy tính cước của GHN lại chạy trên danh mục cũ không có chúng. Hãy đặt tay phường trên liên hệ, hoặc tính giá bằng luật giá của chính Odoo.
"Authorization header is required"
Token trống hoặc sai môi trường. Dùng token môi trường thử cho môi trường thật sẽ lỗi đúng kiểu này.
Cước trả về bằng không
Kiểm tra kiện hàng đã có khối lượng chưa. GHN từ chối kiện không có khối lượng; ô Khối lượng mặc định trên phương thức giao hàng lo cho các sản phẩm chưa khai khối lượng.
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.