- ỨNG DỤNG
- Nền tảng kết nối vận chuyển nội địa Việt Nam 18.0
| Số dòng Code | 2647 |
| Tên kỹ thuật | viin_delivery_vn_base |
| Giấy phép | OPL-1 |
| Website | https://viindoo.com/apps/modules/18.0/viin_delivery_vn_base |
| Đọ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 |
| Các mở rộng | Kết nối vận chuyển Viettel Post Kết nối vận chuyển Giao Hàng Tiết Kiệm Kết nối vận chuyển GHN Express Vận chuyển Việt Nam cho Thương mại điện tử Vận chuyển Việt Nam theo lô Vận chuyển Việt Nam tại Điểm bán hàng |
Ứng dụng làm gì
Các hãng vận chuyển Việt Nam không nói thứ ngôn ngữ mà tầng giao hàng của Odoo chờ đợi. Họ đánh địa chỉ bằng mã tỉnh và mã phường riêng, họ trả tiền mặt về sau vài ngày, họ đẩy trạng thái qua webhook, và ngày 01/07/2025 cả nước bỏ cấp huyện khỏi bản đồ hành chính. Ứng dụng này gánh trọn phần đó một lần, để mỗi ứng dụng hãng - GHN, GHTK, Viettel Post - chỉ còn phải mô tả API của chính mình.
Tính năng chính
- Bản đồ địa giới hai cấp 2025: tỉnh và phường theo đúng cách Việt Nam vẽ lại ngày 01/07/2025, đồng thời giữ các đơn vị ba cấp cũ để đơn ghi trước cải cách vẫn tra được. Mã riêng của từng hãng lưu thành bảng ánh xạ riêng, nên một địa chỉ dùng được cho mọi hãng.
- Khớp địa chỉ chịu được dữ liệu thật: khách gõ "tp hcm", "TP. Hồ Chí Minh" hay "ho chi minh" đều ra cùng một tỉnh, bỏ qua dấu và tiền tố hành chính. Khi nhập nhằng thì luôn báo, không bao giờ tự đoán.
- So giá nhiều hãng cạnh nhau: hỏi giá và thời gian giao của mọi hãng đã cấu hình trong một lần, xem bảng xếp hạng, và để một luật chọn hãng rẻ nhất hoặc nhanh nhất. Lý do chọn được lưu lại trên đơn.
- Đối soát COD: nạp bảng kê chuyển trả của hãng, khớp từng dòng với phiếu giao tương ứng, và thấy rõ đơn nào đã giao mà chưa được trả tiền, đơn nào trả sai số tiền, hãng đã trừ những khoản phí gì.
- Dòng thời gian giao hàng: mọi trạng thái hãng báo về được giữ thành một sự kiện có thời điểm và địa điểm, hiện ngay trên phiếu giao và đăng vào chatter, nên "hàng đang ở đâu" được trả lời mà không cần rời Odoo.
- Webhook có xác thực: mỗi hãng một endpoint với khoá bí mật riêng, chữ ký của hãng được kiểm trước khi ghi bất cứ thứ gì.
- Ghi nhật ký mọi lệnh gọi: mỗi request rời khỏi máy chủ đều được lưu kèm dữ liệu gửi, dữ liệu nhận, thời lượng và kết quả - token và khoá bí mật đã che - nên tranh chấp với hãng được xử bằng bằng chứng.
- Thử lại mà không nhân đôi đơn: lệnh gọi hỏng được thử lại với giãn cách tăng dần, và việc tạo đơn được khoá theo số phiếu giao, nên một kiện không bao giờ bị đẩy hai lần.
- Tiền về tới sổ sách: đóng một lần đối soát sẽ tất toán từng hoá đơn khách hàng qua một sổ nhật ký giữ tiền riêng cho từng hãng, tính vào đúng ngày kiện được giao, rồi tất toán sổ đó bằng số tiền hãng thực chuyển sau khi trừ phí. Phần còn lại trên sổ chính là số hãng vẫn đang nợ bạn.
- Mỗi thùng một kiện: phiếu giao đóng thành ba package được đẩy thành ba kiện với ba số vận đơn, theo dõi riêng từng kiện. Tiền thu hộ chỉ thu một lần, trên một vận đơn, vì bưu tá vốn làm vậy - và thùng bị từ chối sau khi thùng trước đã được nhận sẽ khiến các kiện đã nhận bị huỷ, thay vì để lại một lô hàng đẩy dở.
- Hàng quay về: đơn hoàn được đẩy theo chiều ngược lại, lấy từ khách và giao về kho, không phải cấu hình thêm gì. Và khi hãng giữ một kiện không giao được, phiếu giao đưa ra đúng hai câu trả lời mà hãng đang chờ - giao lại, hoặc chấp nhận hoàn hàng.
Bản thân ứng dụng này không cấu hình gì: hãy cài ứng dụng hãng bạn cần, ứng dụng đó phụ thuộc vào ứng dụng này.
Ấn bản được Hỗ trợ
- Ấn bản Community
- Ấn bản Enterprise
Nền tảng kết nối vận chuyển nội địa Việt Nam
Ứng dụng này là phần lõi mà các ứng dụng kết nối GHN, GHTK và Viettel Post chạy trên đó. Hãy cài ứng dụng hãng bạn cần, ứng dụng này sẽ được cài kèm; bản thân nó không cấu hình gì.
Nó gánh bốn thứ mà mọi tích hợp hãng vận chuyển Việt Nam đều cần: bản đồ hành chính cả nước vẽ lại ngày 01/07/2025, cách biến một địa chỉ viết tay thành đơn vị mà hãng chấp nhận, việc đối soát tiền hãng thu hộ, và một bộ từ vựng trạng thái duy nhất để báo cáo không phải biết bốn bộ.
Cài đặt
- Vào Ứng dụng.
- Bỏ bộ lọc Ứng dụng mặc định, tìm hãng bạn dùng - Kết nối vận chuyển GHN Express, Kết nối vận chuyển Giao Hàng Tiết Kiệm, Kết nối vận chuyển Viettel Post hoặc Kết nối vận chuyển Viettel Post - rồi bấm Cài đặt. Ứng dụng này được cài kèm.
Cấu hình
Bước 1 - Thiết lập phương thức giao hàng
- Vào Kho vận > Cấu hình > Phương thức Giao hàng, mở phương thức mà ứng dụng hãng đã tạo, hoặc tạo mới và chọn hãng ở mục Nhà cung cấp.
- Điền thông tin đăng nhập ở tab Vietnam Shipping. Các giá trị này lấy từ cổng quản trị của hãng hoặc từ hợp đồng đối tác; tài liệu của từng ứng dụng hãng nói rõ cần đúng giá trị nào.
- Cứ để Môi trường thử cho tới khi bạn đã đẩy trọn một kiện hàng từ đầu đến cuối. Ý nghĩa của cờ này tuỳ hãng, vì các hãng không giống nhau: GHN và Viettel Post chuyển lệnh sang sandbox riêng của họ, không sinh kiện thật. GHTK không có sandbox nào, nên ở đó cờ này cho bạn làm mọi thứ không tạo ra gì - báo giá, địa chỉ, tra trạng thái - và chỉ chặn riêng việc đẩy đơn. Tài liệu của từng ứng dụng hãng nói rõ.
- Bấm Kiểm tra kết nối. Thông báo xanh nghĩa là thông tin đăng nhập dùng được.
Bước 2 - Nạp danh mục địa giới
- Vẫn ở tab đó, bấm Đồng bộ tỉnh và phường.
- Odoo nạp đúng danh mục tỉnh và phường của hãng, kèm các cách viết tên mà hãng công bố cho từng đơn vị, và mã mà hãng chờ nhận lại.
- Kiểm tra kết quả tại Kho vận > Cấu hình > Vietnam Shipping > Đơn vị hành chính.
Chạy lần thứ hai là cập nhật chứ không nhân đôi danh mục, nên cứ chạy lại mỗi khi hãng đổi danh mục.
Bước 3 - Đăng ký webhook
- Vẫn ở tab Vietnam Shipping, bấm Sinh khoá bí mật mới, rồi sao chép Webhook URL.
- Đăng ký URL đó trong cổng của hãng và đưa khoá bí mật theo đúng cách hãng yêu cầu - tài liệu của từng ứng dụng hãng nói rõ chỗ nào.
- Nếu không đặt khoá, endpoint sẽ nhận callback không xác thực và ghi cảnh báo vào log máy chủ. Hãy đặt khoá trước khi chạy thật.
Dùng hằng ngày
Ghi địa chỉ khách hàng
Hãng vận chuyển Việt Nam định tuyến theo tỉnh và phường, không theo địa chỉ viết tự do. Trên liên hệ, hãy điền Tỉnh/Thành phố và Phường/Xã ở mục Địa chỉ Việt Nam, cùng với đường phố để riêng.
Khi các ô đó trống, địa chỉ viết tay sẽ được diễn giải thay: dấu, dấu câu và tiền tố hành chính đều được bỏ qua, nên TP. Hồ Chí Minh, thanh pho ho chi minh và hcm đều ra cùng một tỉnh. Giá trị đặt tay luôn thắng giá trị diễn giải, và địa chỉ khớp với hai phường khác nhau thì được báo chứ không bị đoán - một kiện giao nhầm phường tốn kém hơn một lần đẩy đơn phải chờ câu trả lời.
Mọi hãng đều cần số điện thoại, vì bưu tá gọi trước khi giao. Liên hệ không có số sẽ bị từ chối ngay trong Odoo trước khi request được gửi đi.
So sánh hãng ngay trên đơn bán
- Mở báo giá và bấm So sánh hãng vận chuyển.
- Mọi phương thức giao hàng Việt Nam đã cấu hình cho công ty được hỏi giá và thời gian giao cùng lúc. Hãng nào không phục vụ hoặc không gọi được sẽ có dòng riêng kèm lý do, nên một hãng chết không bao giờ che mất các hãng còn lại.
- Chọn Rẻ nhất, Nhanh nhất, hoặc tự chọn một báo giá, rồi bấm Dùng hãng này.
- Đơn hàng giữ lại lý do hãng được chọn, để sau này còn giải trình được.
Đẩy đơn và theo dõi kiện hàng
Phiếu giao có khối Vận chuyển ngay trang chính: hãng, mã vận đơn, kiện đang ở đâu, tiền thu hộ, và những gì bưu tá được dặn. Không có gì về kiện hàng bị giấu trong thẻ phụ.
- Mở phiếu giao từ Kho vận > Vận hành > Vận chuyển > Kiện gửi. Danh sách mở sẵn những việc cần làm hôm nay: phiếu chưa đẩy, kiện đang chờ bưu tá đến lấy, kiện đang trên đường, và giao thất bại đang chờ quyết định.
- Kiểm tra bưu tá sẽ được dặn gì - xem bên dưới - và tiền thu hộ, rồi bấm Gửi sang hãng. Kiện được đẩy khi phiếu giao còn Sẵn sàng, và mã vận đơn về ô Mã vận đơn. Đây là thứ tự một cửa hàng vẫn làm: đẩy đơn, in nhãn, đóng gói, bàn giao, rồi mới xác nhận phiếu giao khi bưu tá ký nhận. Ai quen thứ tự của Odoo mà xác nhận trước thì kiện vẫn được đẩy; xác nhận sau thì kiện đã đẩy được giữ nguyên.
- Số phiếu giao được gửi làm khoá đơn của hãng, nên đẩy cùng một phiếu hai lần sẽ trả về đúng kiện đã có thay vì tạo kiện thứ hai.
- In vận đơn tải vận đơn về và đính vào phiếu giao.
- Huỷ kiện gửi báo hãng bỏ kiện, chừng nào kiện chưa giao. Phiếu giao vẫn mở, nên đẩy lại được - sang hãng khác nếu cần.
- Làm mới trạng thái hỏi hãng xem kiện đang ở đâu. Webhook làm đúng việc đó mà không cần hỏi; tác vụ định kỳ Delivery: refresh parcel status là lưới an toàn cho các sự kiện webhook đánh rơi, và chỉ xét những kiện còn đang trên đường.
- Nút Dòng thời gian mở ra mọi trạng thái hãng đã báo, kèm thời điểm và địa điểm. Trạng thái cũng được đăng vào chatter.
- Với hãng nào có công bố, mục dòng thời gian còn mang theo Bằng chứng giao hàng - link tới chữ ký hoặc ảnh chụp lúc bàn giao. Nó về một lần, vào lúc giao thành công, và chỉ khi tài liệu của ứng dụng hãng đó bảo bật lên. Đây là thứ bạn đưa ra trước mặt khách khi họ nói chưa nhận được hàng.
Bưu tá được dặn gì
Bốn điều đổi theo từng kiện, và hãng nào ở Việt Nam cũng hỏi đủ cả bốn khi nhận đơn. Chúng được đặt mặc định trên phương thức giao hàng và đổi trên từng phiếu giao khi kiện đó khác đi; kiện đã đẩy rồi thì khoá lại, vì hãng đã nhận rồi.
- Bên trả phí giao - cửa hàng, hay người nhận trả lúc giao. Khi là người nhận, bưu tá thu phí giao cộng thêm vào tiền thu hộ, và hãng nào cũng tách hai khoản này trên bảng kê.
- Người nhận được xem hàng - không cho xem, cho xem, hay cho thử. GHN có trường riêng; GHTK và Viettel Post đọc nó ở đầu ghi chú cho bưu tá.
- Bàn giao - bưu tá đến lấy tại cửa hàng, hay cửa hàng mang ra bưu cục. Hãng chỉ đến lấy thì bỏ qua.
- Ghi chú cho bưu tá - một dòng bưu tá đọc: "gọi trước khi giao", "hàng dễ vỡ", "gửi bảo vệ". Đây không phải ghi chú nội bộ của phiếu giao; ghi chú đó ở lại trong Odoo.
Hàng trả về không bao giờ tính phí cho khách: trên phiếu hoàn, bên trả phí luôn là cửa hàng dù mặc định là gì.
Thu hộ COD
Tiền thu hộ trên phiếu giao mặc định bằng số khách còn nợ: dư nợ của hoá đơn đã vào sổ, hoặc tổng đơn trừ phần đã thanh toán online. Đơn đã trả trước sẽ đi với số thu hộ bằng không, nên một phương thức giao hàng phục vụ được cả hai luồng thanh toán. Muốn thu một phần thì sửa lại số tiền.
Có thể đặt hạn mức theo từng phương thức giao hàng. Kiện vượt hạn mức bị từ chối khi người dùng còn đang ở trên phiếu giao, chứ không phải vài giây sau bởi hãng.
Đối soát tiền về
- Vào Kho vận > Hoạt động > Bảng kê COD và tạo một bảng kê cho một hãng và một kỳ.
- Bấm Lấy từ hãng. Hãng nào có báo số tiền đã chuyển trả thì lấy đúng số đó; hãng nào không có thì ứng dụng nói rõ và giải thích nó đã dùng dữ liệu gì thay thế.
- Bấm Khớp. Mỗi dòng được nối với đúng phiếu giao mà nó trả tiền, theo mã vận đơn.
- Đọc kết quả:
- Đã khớp - hãng trả đúng số đã yêu cầu.
- Lệch số tiền - hãng trả không đúng, và khoản chênh nằm ngay trên dòng. Đây là tiền phải đòi.
- Không tìm thấy phiếu giao - kiện mà cơ sở dữ liệu này chưa từng gửi, chuyện bình thường khi nhiều hệ thống dùng chung một tài khoản hãng.
- Đã trả rồi - cùng một kiện xuất hiện hai lần, nên không bị tính thành doanh thu hai lần.
- Bấm Đóng để ghi số tiền đã nhận, phí của hãng và ngày trả về lại từng phiếu giao.
Đưa tiền vào sổ sách
Mặc định, việc đối soát chỉ là một báo cáo: nó cho biết chuyện gì đã xảy ra và không đụng tới tài khoản nào. Bật Ghi sổ tiền COD trên phương thức giao hàng sẽ khiến việc đóng bảng kê làm luôn phần kế toán, theo đúng hai bước mà tình huống này vốn có.
Trước hết, cấu hình trên phương thức giao hàng:
- Sổ nhật ký tiền đang chuyển - nơi tiền nằm lại từ lúc bưu tá thu tới lúc hãng chuyển trả. Hãy dùng một sổ riêng cho từng hãng: số dư của sổ đó, tại bất kỳ thời điểm nào, chính là số hãng đang nợ bạn.
- Sổ nhật ký nhận tiền - tài khoản ngân hàng mà tiền hãng chuyển về.
- Tài khoản phí của hãng - tài khoản chi phí cho khoản hãng trừ.
- Liên hệ của hãng - hãng dưới dạng một liên hệ, để đứng trên bút toán quyết toán.
Sau đó, khi một bảng kê được đóng:
- Mỗi dòng đã khớp sẽ thanh toán hoá đơn khách hàng tương ứng, qua sổ nhật ký tiền đang chuyển. Khách đã trả tiền cho bưu tá, nên hoá đơn được tất toán - vào đúng ngày kiện hàng được giao, chứ không phải ngày hãng mới chuyển tiền về.
- Một bút toán tất toán số dư đang giữ: ngân hàng nhận phần thực nhận, khoản phí hãng giữ lại trở thành chi phí, và tài khoản tiền đang chuyển được ghi Có đúng bằng số nó đang giữ.
Phần còn lại trên tài khoản tiền đang chuyển chính là tiền đã thu của khách mà hãng chưa giao lại. Con số đó đáng để theo dõi.
Dòng trả thiếu chỉ tất toán đúng phần tiền đã về, nên hoá đơn còn dư nợ và khách vẫn hiện là còn nợ khoản chênh - đó chính là điều cần thấy. Dòng mà việc đối soát không khớp được với phiếu giao nào thì không ghi sổ gì cả: tiền không quy được về ai thì không được đoán vào tài khoản của ai.
Nhiều thùng, nhiều kiện
Một phiếu giao đóng thành ba package sẽ được đẩy thành ba kiện với ba số vận đơn. Hãy đóng gói như bình thường - Đóng gói ở phần thao tác chi tiết - rồi xác nhận; mỗi package thành một kiện riêng, và tab Các kiện gửi liệt kê chúng kèm mã vận đơn và trạng thái riêng.
Tiền thu hộ không bị chia ra giữa các kiện. Bưu tá chỉ thu một lần, và mọi hãng ở đây đều chờ số tiền nằm trên đúng một vận đơn; chia ra sẽ khiến người nhận phải trả nhiều lần.
Nếu một thùng bị từ chối sau khi thùng trước đã được nhận, các kiện đã nhận sẽ bị huỷ trước khi lỗi được báo ra. Một lô hàng đẩy dở dang sẽ tính tiền khách cho những thùng không bao giờ chạy.
Hàng quay về
Phiếu giao hoàn - một lệnh chuyển hàng chiều nhập, hoặc phiếu được Odoo đánh dấu là hoàn - sẽ được đẩy theo chiều ngược lại: bưu tá tới lấy hàng từ khách và giao về kho. Không phải cấu hình thêm gì; chiều được đọc ra từ chính phiếu giao.
Tách biệt với việc đó, một hãng không giao được sẽ giữ kiện hàng và chờ được cho biết phải làm gì. Khi đó phiếu giao hiện hai nút Giao lại và Chấp nhận hoàn hàng. Hãy trả lời sớm: để yên thì rốt cuộc hãng vẫn hoàn hàng và tính tiền cả hai chiều.
Xử lý sự cố
Địa chỉ bị từ chối
Thông báo nói rõ cái gì không khớp và ở đâu. Hãy sửa lại cách viết trên liên hệ, đặt tay tỉnh và phường, hoặc đồng bộ danh mục địa giới của hãng nếu chưa từng nạp.
Đẩy đơn thất bại
Vào Nhật ký API > Nhật ký yêu cầu API, hoặc nút Lệnh gọi tới hãng ngay trên phiếu giao, lọc Thất bại, và đọc request cùng câu trả lời của hãng. Thông tin đăng nhập đã bị che, còn lại đủ cả. Đẩy lại cùng một phiếu giao là an toàn.
Dòng thời gian ngừng cập nhật
Kiểm tra webhook URL đã đăng ký ở hãng chưa và khoá bí mật có khớp không. Nếu vẫn không được, nút Làm mới trạng thái trên phiếu giao sẽ hỏi thẳng hãng.
Đóng bảng kê bị từ chối vì thiếu tài khoản
Thông báo nói rõ thiếu tài khoản nào. Ghi sổ khi cấu hình còn dở dang còn tệ hơn là không ghi - nó đưa tiền vào sai chỗ và sau đó phải có người đi gỡ - nên không gì được ghi sổ cho tới khi cấu hình đủ. Điền nốt, hoặc tắt Ghi sổ tiền COD, đều mở được nút đóng.
Tài khoản tiền đang chuyển không bao giờ về không
Đó chính là khoản hãng đang nợ bạn, và thường là đúng. Hãy đối chiếu với các kiện đã đánh dấu giao thành công mà chưa nằm trên bảng kê nào. Nếu vẫn không khớp, mục Chênh lệch chưa giải thích trên bảng kê là chỗ liệt kê chi tiết phần sai lệ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.
