Kết nối Viettel Post với website: 3 cách cho shop online

Chào anh em! Shop có website mà gửi hàng Viettel Post thì kịch bản quen thuộc là: khách hỏi phí ship, mở viettelpost.vn tra tay; có đơn thì chép tên, số điện thoại, địa chỉ sang Viettel Post; giao xong lại quay về web đổi trạng thái đơn. Kết nối Viettel Post với website là để bỏ ba việc chép tay đó. Có ba đường: dùng nền tảng bán hàng có sẵn kết nối, tự code qua API của Viettel Post, hoặc cài plugin nếu web chạy WordPress/WooCommerce. Đọc xong, anh em chọn được cách hợp với web của mình và biết phải chuẩn bị gì trước khi bắt tay làm.

Plugin ở cách 3 là sản phẩm mình viết và bảo trì. Cách 1 mình lấy theo trang hướng dẫn chính thức của từng nền tảng, cách 2 theo tài liệu API tại partner2.viettelpost.vn, tất cả kiểm lại vào tháng 10/2026. Giao diện các bên có thể đổi sau thời điểm đó, tên nút lệch chút thì cứ theo ý các bước.

Kết nối Viettel Post với website gồm những việc gì?

Hiện được phí ship mới là một trong bốn phần của bộ kết nối đầy đủ:

• Website tính phí ở trang thanh toán: khách chọn địa chỉ là website hỏi Viettel Post rồi hiện đúng cước của từng gói dịch vụ, thay vì một mức đồng giá cho cả nước.
• Website tạo vận đơn bằng cách gửi người nhận, khối lượng, tiền thu hộ sang Viettel Post và nhận lại mã vận đơn, không phải gõ lại lần nào.
• Trạng thái đơn tự cập nhật nhờ Viettel Post báo về website mỗi khi vận đơn đổi trạng thái (webhook), nên đơn giao xong tự chuyển sang hoàn thành.
• Website phải biết lấy hàng ở kho nào và gửi tỉnh, phường/xã khớp đúng danh mục địa danh của Viettel Post.

Chuẩn bị chung cho cả ba cách

• Shop cần một tài khoản Viettel Post và tự đăng ký được trên viettelpost.vn, các bước chi tiết có ở bài đăng ký tài khoản Viettel Post.
• Địa chỉ lấy hàng (kho) phải khai sẵn trên tài khoản Viettel Post, vì nền tảng hay plugin đều đọc danh sách kho từ đó để liên kết, và kho khai sai thì phí báo cho khách sai theo.
• Từng sản phẩm phải có cân nặng (và kích thước nếu hàng cồng kềnh), vì cước tính theo khối lượng nên sản phẩm để trống cân nặng là phí sai.
• Bán COD thì ký hợp đồng điện tử trên app ViettelPost, vì Viettel Post thông báo từ 10/09/2024 khách phải ký mới tiếp tục dùng được các tính năng như thu hộ.

Cách 1: Dùng nền tảng bán hàng có sẵn kết nối Viettel Post

Website chạy trên một nền tảng bán hàng như Sapo, Haravan, Nhanh.vn hay MISA eShop thì không cần code gì: bật Viettel Post trong phần vận chuyển của nền tảng đó. Hướng dẫn chính thức của từng bên:

• Sapo có bài Tích hợp Viettel Post trên website Sapo.
• Haravan có bài Hướng dẫn kết nối nhà vận chuyển Viettel Post.
• Nhanh.vn hướng dẫn ở mục “Kết nối Viettel Post” trong bài giao hàng tự động của Nhanh.vn.
• MISA eShop có bài Kết nối và thiết lập đối tác vận chuyển Viettel Post.

Điểm chung trong các hướng dẫn trên: nhập tài khoản và mật khẩu Viettel Post vào nền tảng, rồi liên kết kho trên nền tảng với kho trên Viettel Post. Hai chi tiết đáng để ý: Sapo ghi rằng tài khoản đăng ký bằng số điện thoại cần cập nhật thêm email và mật khẩu trên Viettel Post mới kết nối được; MISA eShop ghi rằng sau khi kết nối, phần mềm chỉ đồng bộ trạng thái giao hàng về, chưa kéo ngược đơn tạo trên Viettel Post về phần mềm.

• Cách này hợp với shop đang bán trên chính nền tảng đó.
• Shop cần tài khoản Viettel Post và quyền cấu hình vận chuyển trên nền tảng.
• Công sức chỉ là vài phút cấu hình và nền tảng lo phần bảo trì, đổi lại bạn dùng đúng những gì nền tảng làm sẵn, còn chuyển cả website sang nền tảng khác chỉ vì phần vận chuyển thì không đáng.

Cách 2: Tự code qua API Viettel Post

Website tự viết (Laravel, PHP thuần, WordPress không dùng WooCommerce) hoặc cần nối thẳng phần mềm quản lý kho, ERP thì gọi API của Viettel Post. Tài liệu chính thức ở partner2.viettelpost.vn/document, có hai môi trường: Development (partnerdev.viettelpost.vn) để chạy thử và Production (partner.viettelpost.vn) tạo đơn thật. Luồng tối thiểu gồm sáu bước:

1. Lấy token bằng cách gọi user/Login với tài khoản Viettel Post để nhận token ngắn hạn, rồi gọi user/ownerconnect để đổi sang token dài hạn 1 năm.
2. Chọn một bộ địa danh, danh mục cũ V2 (Tỉnh → Quận/Huyện → Phường/Xã) hoặc mới V3 (Tỉnh → Phường/Xã, sau sáp nhập), rồi dùng trọn bộ đó cho cả người gửi lẫn người nhận.
3. Tính cước bằng order/getPriceAll để lấy các gói dịch vụ đi được trên tuyến kèm cước, còn order/getPrice tính cước cho gói khách chọn.
4. Tạo đơn bằng order/createOrder, trong đó ORDER_PAYMENT là loại vận đơn (1 không thu hộ, 2 thu hộ tiền hàng và tiền cước, 3 chỉ thu tiền hàng, 4 chỉ thu tiền cước) và CHECK_UNIQUE chống tạo trùng, rồi lưu lại mã vận đơn trả về.
5. Huỷ đơn bằng order/UpdateOrder với TYPE là 4, chỉ áp dụng cho đơn chưa nhận thành công.
6. Nhận trạng thái bằng cách khai webhook trên trang Partner, ở mục Bảng điều khiển → Thông tin tài khoản → Cấu hình webhook.

Làm xong bốn bước đầu là website đã tính phí và tạo đơn được. Code PHP cho từng bước, kèm các lỗi hay gặp, mình viết ở bài tích hợp API Viettel Post.

• Cách này hợp với lập trình viên, với hệ thống có luồng đơn riêng, hoặc khi chỉ cần một API lẻ như tính cước.
• Bạn cần tài khoản Viettel Post đăng nhập được trang Partner, người viết code và người bảo trì về sau.
• Gọi được API thì không lâu, cái tốn ngày tới tuần là mọi thứ xung quanh (dữ liệu tỉnh, phường/xã khớp ID Viettel Post và đổi theo mỗi lần địa giới thay đổi, ô địa chỉ ở trang thanh toán, màn hình tạo đơn cho nhân viên, bảng ánh xạ trạng thái, đường lùi khi API chậm), chưa kể còn sửa tiếp mỗi lần Viettel Post đổi API.

Cách 3: Viettel Post cho WordPress/WooCommerce bằng plugin

Web chạy WooCommerce thì không phải viết lại những thứ ở cách 2. Mình lấy ví dụ plugin ViettelPost cho WooCommerce của mình. Website cần WooCommerce 5.6 trở lên, PHP 7.2 trở lên, hosting bật ionCube Loader; plugin không hỗ trợ multisite. Đang dùng bản miễn phí Woo Vietnam Checkout thì tắt nó trước, vì plugin đã có sẵn module trang thanh toán. Kết nối gồm 4 bước.

Bước 1: Cài plugin và kích hoạt license

Tải file zip lên ở Plugin → Cài mới → Tải plugin lên, kích hoạt, rồi vào WooCommerce → ViettelPost → License dán mã bản quyền. Chưa kích hoạt license thì các tab khác chưa dùng được. Chi tiết ở trang cài đặt plugin và kích hoạt license.

Bước 2: Đăng nhập tài khoản Viettel Post

Ở tab ViettelPost → Login, nhập tài khoản và mật khẩu Viettel Post rồi bấm Đăng nhập. Bạn không phải tự lấy token: plugin lấy token dài hạn và tự gia hạn trước khi hết hạn 1 ngày. Điều kiện bắt buộc: tài khoản phải đăng nhập được cả viettelpost.vn lẫn trang Partner, nếu không Viettel Post từ chối. Xem trang đăng nhập ViettelPost.

Bước 3: Kho lấy hàng, gói dịch vụ và cân nặng

• Ở mục Quản lý kho, bấm Đồng bộ kho từ ViettelPost để kéo kho đã khai về (chưa có kho thì bấm Thêm kho mới ngay trong plugin) rồi đặt một kho chính; có nhiều kho thì tích khu vực bán hàng theo tỉnh cho từng kho để đơn tới tỉnh nào lấy hàng ở kho phụ trách tỉnh đó (xem quản lý kho gửi hàng).
• Ở mục Cấu hình, bấm Lấy dịch vụ tự động để dò các gói Viettel Post cho phép với kho chính, tích gói muốn hiện cho khách và đặt lại tên cho dễ hiểu; dịch vụ cộng thêm (khai giá, phát tận tay…) tích theo từng gói và áp cho mọi đơn đi gói đó, nên tích cái nào là cước tăng theo cái đó (xem dịch vụ và phí vận chuyển).
• Khai cân nặng (và kích thước) cho sản phẩm trong WooCommerce vì plugin lấy số liệu từ sản phẩm, không tự đặt cân nặng mặc định, nên sản phẩm để trống là phí sai.
• Tab General mặc định dùng bộ địa chỉ 3 cấp cũ (“v2.0 – trước 01.07.2025”), muốn chuyển sang địa chỉ 2 cấp với ô Tỉnh → Phường/Xã theo đơn vị hành chính mới thì ở khối Công cụ, mục Đơn vị hành chính, chọn ô ngoài cùng bên trái rồi bấm “Cập nhật database” (xem trang thanh toán và địa chỉ).

Không cần thêm Viettel Post vào khu vực giao hàng như phương thức thường: WooCommerce → Cài đặt → Vận chuyển → ViettelPost chỉ có ô Kích hoạt. Xong bước này, khách chọn tỉnh, phường/xã ở trang thanh toán là thấy các gói Viettel Post kèm phí. Khách chọn chuyển khoản thì plugin gửi tiền thu hộ bằng 0 và ẩn gói chỉ dành cho COD (trên trang thanh toán cổ điển, đổi hình thức thanh toán là phí tính lại).

Muốn xem trước thì vào bản demo: sản phẩm đã nằm sẵn trong giỏ, chọn địa chỉ ở trang thanh toán là thấy phí Viettel Post.

Bước 4: Khai webhook để trạng thái tự về

Ở mục Cấu hình, khối Cài đặt Webhook có sẵn Đường dẫn API/Webhook và Tham số bí mật; tham số bí mật chỉ có hiệu lực sau khi bấm Lưu. Sau đó đăng nhập trang Partner bằng chính tài khoản Viettel Post đó, vào Bảng điều khiển → Thông tin tài khoản → Cấu hình webhook, dán đường dẫn vào ô Webhook Endpoints, tham số bí mật vào ô Secret parameter, rồi bấm Kiểm tra kết nối. Việc này shop tự làm, không phải chờ Viettel Post bật giúp.

Có webhook, đơn trên website tự đổi trạng thái theo bảng ánh xạ chỉnh được (mặc định: phát thành công thì chuyển sang Hoàn thành), kèm lịch sử hành trình để khách tự tra ngay trên website. Xem webhook và trạng thái; phần phía Viettel Post mình viết riêng ở bài webhook Viettel Post.

Kết nối xong, hằng ngày làm gì?

Có đơn thì bấm Tạo vận đơn ViettelPost ngay trong danh sách đơn hoặc trong trang sửa đơn. Hộp thoại điền sẵn người nhận, kho lấy hàng, khối lượng, loại vận đơn, tiền thu hộ; bạn kiểm lại rồi bấm tạo là có mã vận đơn. Xem tạo và huỷ vận đơn.

Nói rõ để anh em khỏi hiểu nhầm: plugin chính không tự đẩy đơn mới sang Viettel Post và không đăng hàng loạt. Hai việc đó nằm ở addon đăng đơn tự động/hàng loạt, mua thêm và có license riêng. Plugin cũng không in vận đơn: đơn tạo từ website vẫn nằm trong phần quản lý vận đơn trên viettelpost.vn, in phiếu ở đó.

• Cách này hợp với chủ shop bán bằng WooCommerce, hoặc dev, agency làm web cho khách cần chạy ngay.
• Bạn cần hosting có ionCube Loader, tài khoản Viettel Post vào được trang Partner và license plugin.
• Tài liệu plugin ghi khoảng 30 phút cài đặt, còn khi Viettel Post đổi API hay dữ liệu địa giới thì việc của bạn là cập nhật plugin.

Nên chọn cách nào?

• Web chạy trên Sapo, Haravan, Nhanh.vn, MISA eShop… thì dùng kết nối có sẵn của nền tảng.
• Web WooCommerce cần chạy ngay thì cài plugin.
• Hệ thống tự viết, ERP, hoặc chỉ cần một API lẻ thì tự code.

Còn đang phân vân giữa các hãng vận chuyển thì xem bài GHTK, GHN hay Viettel Post, mình so ba hãng ở đúng góc kết nối website.

Lỗi hay gặp khi kết nối Viettel Post

• Đăng nhập báo sai tài khoản hoặc mật khẩu dù gõ đúng thường do tài khoản chưa vào được trang Partner, nên thử đăng nhập partner2.viettelpost.vn bằng chính tài khoản đó trước.
• Trang thanh toán không hiện gói Viettel Post nào khi chưa tích gói dịch vụ, chưa có kho chính, ô Kích hoạt đang tắt, hoặc khách chưa chọn đủ tỉnh, phường/xã.
• Lỗi “Price does not apply to this itinerary!” theo FAQ trên trang Partner là do gói dịch vụ chưa được cấu hình cho tài khoản, không đi được tuyến đó, hoặc dịch vụ cộng thêm không hợp với gói chính; gặp lỗi này thì chọn gói khác trong danh sách khả dụng, vẫn lỗi thì liên hệ nhân viên kinh doanh Viettel Post kèm địa chỉ lấy hàng, địa chỉ giao và tài khoản.
• Đơn giao xong mà trạng thái trên web không đổi thường do chưa khai webhook trên Partner, tham số bí mật hai bên không khớp, website chạy ở máy local, hoặc tường lửa, plugin bảo mật chặn đường dẫn webhook.

Dùng plugin thì xem thêm trang hỏi đáp về plugin Viettel Post, trang này mình bổ sung dần theo các ca hỗ trợ thực tế.

Câu hỏi thường gặp

Website không dùng WooCommerce có kết nối Viettel Post được không?

Được. Website trên nền tảng bán hàng thì bật kết nối có sẵn của nền tảng; website tự viết thì gọi API Viettel Post theo tài liệu ở partner2.viettelpost.vn. Riêng plugin trong bài chỉ chạy với WooCommerce.

Có phải liên hệ Viettel Post mới kết nối được không?

Không. Shop tự đăng ký tài khoản trên viettelpost.vn; tài khoản đăng nhập được cả viettelpost.vn lẫn trang Partner là dùng được cho API và plugin.

Plugin có tự đẩy đơn sang Viettel Post khi có đơn mới không?

Plugin chính thì không: mỗi đơn bấm một nút, kiểm lại rồi mới tạo. Tự đăng đơn theo trạng thái và đăng hàng loạt nằm ở addon bán riêng.

Đổi mật khẩu Viettel Post thì website có bị ảnh hưởng không?

Có. Plugin dùng tài khoản đã lưu để tự lấy lại token khi gần hết hạn, nên đổi mật khẩu xong phải vào mục Login đăng nhập lại bằng mật khẩu mới. Kết nối qua nền tảng bán hàng thì cập nhật mật khẩu ở phần kết nối vận chuyển của nền tảng.

Anh em đang kết nối mà vướng chỗ nào cứ để lại bình luận, nhớ che mật khẩu và số điện thoại trước khi dán ảnh nhé. Chúc anh em sớm bỏ được ba việc chép tay giữa web và Viettel Post! 🚀