Đồng bộ đơn hàng KiotViet: đẩy đơn website thành phiếu Đặt hàng

Chào anh em! Khách đặt hàng trên web WooCommerce, còn soạn hàng và xuất hoá đơn thì nhân viên làm trên KiotViet. Hai bên chưa nối thì mỗi đơn web lại phải mở KiotViet gõ lại tên khách, số điện thoại, địa chỉ, từng mã hàng, tiền ship. Bài này nói về đồng bộ đơn hàng KiotViet theo chiều từ website lên: đơn web thành phiếu Đặt hàng, đăng tay hoặc để plugin tự đăng theo quy tắc, gửi kèm phí ship, VAT, thông tin khách, rồi nhận trạng thái phiếu về lại web. Cuối bài có phần đồng bộ khách hàng hai chiều.

Đẩy đơn hàng website WooCommerce về KiotViet thành phiếu Đặt hàng: đăng tay, tự động theo quy tắc, phí ship và khách hàng

Plugin trong bài do mình viết (bài theo bản 1.3.4), gửi đơn qua Public API của KiotViet; DevVN không phải đối tác của KiotViet. Quy trình xử lý đặt hàng phía KiotViet mình lấy từ trang hướng dẫn Đặt hàng ngành bán buôn, bán lẻ (KiotViet sửa ngày 11/08/2026), đọc lại tháng 10/2026. KiotViet đang chuyển sang giao diện quản lý mới 2026, tên menu có thể lệch chút. Ảnh plugin chụp trên site thử; khách, đơn, giá là dữ liệu mẫu.

🧾 Đồng bộ đơn hàng KiotViet: đơn web thành phiếu Đặt hàng

Mỗi đơn WooCommerce lên KiotViet thành một phiếu Đặt hàng. Plugin không tạo hoá đơn, cũng không có ô nào để chọn tạo hoá đơn.

Để duy trì blog nên mình có làm aff cho 1 số bên hosting. Nhưng dù aff mình cũng chọn 1 số nhà cung cấp uy tín về chất lượng và support nên các bạn cứ yên tâm nhé.

Nếu có mua hosting mà có trong list dưới đây các bạn click vào link trước khi mua để ủng hộ mình nhé. Mình cảm ơn nhiều

Trên KiotViet, phiếu đặt hàng và hoá đơn được quản lý riêng. Theo hướng dẫn Đặt hàng của KiotViet, tới lúc giao, nhân viên mở phiếu ở Đơn hàng → Đặt hàng trên màn hình Quản lý, bấm “Tạo hóa đơn” rồi thanh toán như hoá đơn thường. Một phiếu giao được nhiều lần, mỗi lần một hoá đơn; khách không lấy phần còn lại thì kết thúc phiếu. Nghĩa là đơn web nằm chung danh sách đơn đặt hàng với đơn khách gọi điện đặt trước, nhân viên xử lý như nhau.

Tồn kho trên KiotViet đổi theo cách KiotViet xử lý phiếu và hoá đơn, plugin không can thiệp bước đó. Tồn mới về lại web qua webhook. Cách tồn về web và đối soát khi lệch có ở bài đồng bộ tồn kho KiotViet.

⚙️ Chuẩn bị ở tab Đồng bộ đơn hàng

Trước khi đẩy đơn hàng website về KiotViet, vào WooCommerce > “Đồng bộ KiotViet”, tab “Đồng bộ đơn hàng”. Ô “Chi nhánh mặc định” bắt buộc chọn: để trống thì không đăng được đơn nào, và mọi đơn web đều vào chi nhánh này. “Dịch vụ giao hàng mặc định” có Giao thường, Giao nhanh, Giao trong ngày. “Kênh bán hàng” lấy danh sách kênh từ KiotViet, vừa tạo kênh mới thì bấm “Tải lại từ API”; để “– Không chọn kênh –” thì plugin không gửi kênh bán. Thứ tự cài đặt cả plugin có ở bài kết nối KiotViet với website.

Phần cài đặt, cách đăng tay từng đơn, nút Đăng KV và tự động đăng đơn có trong video hơn hai phút dưới đây.

Tab Đồng bộ đơn hàng của plugin đồng bộ KiotViet cho WooCommerce: Kích hoạt đồng bộ đơn hàng, Chi nhánh mặc định, Dịch vụ giao hàng mặc định, Kênh bán hàng, Xử lý khách hàng, Gửi VAT khi đăng đơn, Đồng bộ phụ thu, Tự động đăng đơn, Quy tắc tự động đăng và Ghi chú khi tự động đăng
Cài đặt đơn hàng trên site thử. Chi nhánh, kênh bán, khoản thu phí giao hàng là dữ liệu mẫu.

⚠️ Mọi sản phẩm trong đơn phải đã liên kết với hàng hoá KiotViet. Chỉ một sản phẩm thiếu KiotViet ID là plugin chặn cả đơn. Khối “Sản phẩm trên web thiếu dữ liệu KiotViet” ở tab “Đồng bộ sản phẩm” liệt kê sản phẩm chưa có KiotViet ID. Cách nối sản phẩm có ở bài đồng bộ sản phẩm KiotViet về WooCommerce.

✋ Đăng tay từng đơn

Mở đơn trong WooCommerce, hộp “KiotViet Order Sync” ở cột phải có nút Post to KiotViet (hộp này hiện chữ tiếng Anh). Popup “Đăng đơn lên KiotViet” mở ra với dữ liệu lấy sẵn từ đơn: thông tin khách, chi tiết sản phẩm kèm các khoản sẽ gửi dạng “thu khác”, thông tin thanh toán và vận chuyển.

Popup Đăng đơn lên KiotViet: thông tin đơn hàng, chi tiết sản phẩm có cột Sync, phí giao hàng gửi dạng thu khác, ô Số tiền khách đã trả, dịch vụ giao hàng, kích thước, khối lượng, ô Ghi chú gửi KiotViet và nút Post to KiotViet
Popup lấy sẵn khách, sản phẩm, phí ship từ đơn; phí giao hàng đi dạng thu khác. Khách, giá là dữ liệu mẫu.

Ô “Số tiền khách đã trả:” để 0 với đơn COD; khách chuyển khoản trước thì nhập số tiền. Khối vận chuyển chọn “Dịch vụ giao hàng:”, nhập kích thước và khối lượng. Ô “Ghi chú gửi KiotViet” (từ 1.3.4) điền sẵn ghi chú của khách; sửa ở đây chỉ đổi nội dung gửi lên KiotViet, ghi chú đơn trên web giữ nguyên. Popup không có ô chọn chi nhánh, người bán hay đối tác giao hàng. Đơn đã đăng thì hộp hiện nút “Update in KiotViet” và “Delete from KiotViet”.

📋 Nút Đăng KV trên danh sách đơn

Muốn đăng mà không mở từng đơn thì bật ô “Thay đổi giao diện trang đơn hàng” ở tab “Cài đặt chung”. Ô này mặc định tắt, chưa bật thì danh sách đơn không có nút nào của plugin. Bật lên, đơn chưa đăng có nhãn “KV: Chưa đăng” kèm “▶ Đăng KV”; đơn đã lên KiotViet hiện “KV:” cộng mã phiếu, kèm nút “✕ Hủy KV”. Danh sách còn thêm bộ lọc theo ngày, tỉnh, kênh bán hàng.

Danh sách đơn WooCommerce khi bật giao diện mới: nhãn KV: Chưa đăng kèm nút Đăng KV, đơn đã đăng hiện mã phiếu KiotViet kèm nút Hủy KV, bộ lọc ngày, tỉnh, kênh bán hàng
Đăng hoặc huỷ phiếu KiotViet ngay từ danh sách đơn. Khách, mã phiếu là dữ liệu mẫu.

🤖 Tự động đăng đơn theo quy tắc

Ô Tự động đăng đơn mặc định tắt. Bật lên rồi khai “Quy tắc tự động đăng”: mỗi quy tắc là một cặp “Trạng thái đơn hàng” và “Hình thức thanh toán”, đơn khớp bất kỳ quy tắc nào là được đăng. Cột trạng thái có thêm “Đơn mới (bất kỳ trạng thái)” để đăng ngay lúc đơn được tạo. Cột thanh toán có “Bất kỳ” và các cổng đang bật trên web. Cài mới có sẵn một quy tắc: Đang xử lý + Bất kỳ.

Ví dụ shop nhận COD và chuyển khoản ngân hàng:

  • 💵 Quy tắc 1 là “Đơn mới” + Thanh toán khi nhận hàng, nên đơn COD lên KiotViet ngay khi khách đặt.
  • 🏦 Quy tắc 2 là “Đang xử lý” + Chuyển khoản ngân hàng. WooCommerce để đơn chuyển khoản ở Tạm giữ; shop thấy tiền về, chuyển đơn sang Đang xử lý thì đơn mới lên KiotViet.

Đơn trả trước có một điểm cần biết. Khi tự động đăng, plugin chỉ tính đơn ở trạng thái Hoàn thành là đã thanh toán, nên đơn chuyển khoản đăng lúc Đang xử lý lên KiotViet với số tiền khách đã trả là 0. Nhân viên ghi nhận tiền khi xử lý phiếu trên KiotViet, hoặc dev đổi danh sách trạng thái bằng filter devvn_kiotviet_sync_order_has_paid_statuses.

Đơn tự đăng chạy nền qua Action Scheduler. Đơn đã có ID KiotViet thì bỏ qua. Gửi không thành thì plugin thử lại, tối đa 3 lần; lỗi dữ liệu thì dừng ngay. Ô “Ghi chú khi tự động đăng” (từ 1.3.4) thêm một dòng cố định vào ghi chú phiếu, ví dụ “Đơn từ website, gọi xác nhận trước khi giao”; ghi chú của khách nằm dòng đầu.

👤 Khách lẻ hay tạo khách mới

Ô “Xử lý khách hàng” có hai lựa chọn. “Tạo khách lẻ (mặc định)” đưa đơn lên dưới dạng khách lẻ, không tạo hồ sơ khách trên KiotViet. “Tạo khách mới” tìm khách theo liên kết đã lưu, rồi số điện thoại, rồi email; không thấy mới tạo, mã khách mang tiền tố ở ô “Tiền tố mã khách hàng” (mặc định “KH-“). Tạo khách bị lỗi thì đơn vẫn lên dạng khách lẻ. Chọn “Tạo khách mới” khi muốn đơn web nằm trong hồ sơ khách trên KiotViet, cạnh đơn mua tại quầy.

🚚 Phí ship, phí khác và VAT

Ô Đồng bộ phụ thu (mặc định tắt) gửi phí vận chuyển và phí khác lên KiotViet dưới dạng “thu khác”. Ghi chú của ô nêu yêu cầu: trên KiotViet phải tích “Hỗ trợ các khoản thu khác khi bán hàng” trong Thiết lập cửa hàng. Sau đó chọn “Khoản thu cho phí vận chuyển”, bấm “Tải lại từ API” hoặc “Tạo khoản thu khác mới” ngay trong plugin. Đừng chọn khoản thu dạng phần trăm, vì KiotViet sẽ tự tính lại theo tỉ lệ thay cho số tiền gửi lên. Để tắt phụ thu thì tổng đơn gửi lên vẫn gồm tiền ship nhưng không có dòng phí riêng, và tổng KiotViet tự tính dễ lệch tổng trên web.

Phí thu hộ COD, phí đóng gói thì khai ở “Ánh xạ phí khác”: mỗi dòng ghép “Tên phí chứa chuỗi” với một “Khoản thu khác KiotViet”. Phí không khớp dòng nào bị bỏ, có ghi log. Mã giảm giá cùng phí âm gộp thành một khoản giảm giá cho cả đơn. Ô “Gửi VAT khi đăng đơn” (mặc định tắt) gửi mức VAT từng sản phẩm theo mức đã đồng bộ về, chỉ bật khi gian hàng KiotViet đã thiết lập thuế.

🔁 Trạng thái phiếu về lại đơn web

Chiều này mặc định tắt. Bật “Kích hoạt đồng bộ trạng thái” trong mục “Đồng bộ trạng thái KiotViet → WooCommerce”, plugin đổi trạng thái đơn web khi nhận webhook order.update của phiếu đã đăng. “Bảng ánh xạ trạng thái” có năm trạng thái phiếu: Phiếu tạm, Đang giao hàng, Hoàn thành, Đã hủy, Đã xác nhận. Mỗi dòng chọn một trạng thái WooCommerce hoặc “Không thay đổi”; cài mới để sẵn Hoàn thành sang Đã hoàn thành, Đã hủy sang Đã hủy.

Mục Phí vận chuyển và phụ thu với ô Đồng bộ phụ thu, Khoản thu cho phí vận chuyển, và mục Đồng bộ trạng thái KiotViet về WooCommerce với bảng ánh xạ Phiếu tạm, Đang giao hàng, Hoàn thành, Đã hủy, Đã xác nhận
Phí ship gửi vào một khoản thu khác; bảng ánh xạ trạng thái phiếu sang trạng thái đơn web. Tên khoản thu là dữ liệu mẫu.

Cần đăng ký order.update ở tab “Webhook”; nút “Đăng ký tất cả webhook” có sẵn sự kiện này. Mã trạng thái được dò theo cách KiotViet gửi thực tế vì KiotViet không công bố đủ, nên thử vài đơn trước khi dựa hẳn vào nó. Đơn tạo trên KiotViet, như đơn bán tại quầy, không kéo về WooCommerce.

Về địa chỉ: với bộ địa chỉ 2 cấp chọn ở tab “Cài đặt chung”, khu vực trên phiếu là tỉnh/thành, phường/xã là phường/xã mới. Phường/xã nào KiotViet không nhận thì từ bản 1.3.3 plugin bỏ phường/xã, rồi tới khu vực, chuyển phần đó vào ô địa chỉ và gửi lại. Cài ô địa chỉ 2 cấp cho trang thanh toán có ở bài địa chỉ 2 cấp trong WooCommerce.

👥 Đồng bộ khách hàng KiotViet hai chiều

Tab “Đồng bộ khách hàng” nối danh sách khách KiotViet với tài khoản WordPress, tách khỏi ô “Xử lý khách hàng” của đơn. “Chế độ đồng bộ” có “Tắt” (mặc định), “KiotViet -> WooCommerce”, “WooCommerce -> KiotViet” và “Cả hai chiều”. Plugin khớp khách theo liên kết đã lưu, rồi số điện thoại (nhận cả dạng 0xx, 84xx, +84xx), rồi email. Khách tìm thấy chỉ được liên kết, dữ liệu trên KiotViet không bị ghi đè.

Ô “Tự động tạo user” (tắt) tạo tài khoản WordPress khi KiotViet thêm khách qua webhook; khách không có email thì nhận email tạm đuôi @kiotviet.local. “Xóa cứng user” (tắt) xoá tài khoản khi KiotViet xoá khách, trừ tài khoản administrator. Chiều web lên có ba ô “Khi đăng ký mới”, “Khi cập nhật hồ sơ”, “Guest Checkout”, đều tắt sẵn. Chi tiết từng nút ở trang đồng bộ khách hàng trong tài liệu plugin.

Tab Đồng bộ khách hàng: Chế độ đồng bộ Tắt, KiotViet sang WooCommerce, WooCommerce sang KiotViet, Cả hai chiều, các ô Tự động tạo user, Xóa cứng user, Khi đăng ký mới, Guest Checkout và bảng danh sách khách có nguồn Đã liên kết, KiotViet, Web
Chọn chiều đồng bộ khách, rồi liên kết hoặc đẩy từng nhóm khách. Tên, số điện thoại là dữ liệu mẫu.

🔧 Đơn không lên KiotViet: kiểm theo thứ tự

  1. License còn hạn. License hết hạn hoặc chưa kích hoạt thì mọi kết nối KiotViet dừng.
  2. Ô “Chi nhánh mặc định” đã chọn.
  3. Mọi sản phẩm trong đơn đã liên kết KiotViet.
  4. Với đơn tự động: ô “Tự động đăng đơn” đang bật, đơn khớp một quy tắc, chưa có ID KiotViet, và WP-Cron chạy được (xem “Kiểm tra môi trường” ở tab “Bắt đầu”).
  5. Phí ship không thành dòng thu khác thì xem lại ô “Đồng bộ phụ thu”, khoản thu đã chọn, và thiết lập khoản thu khác trên KiotViet.
  6. Vẫn chưa ra thì bật “Ghi log” ở tab “Cài đặt API” (mặc định tắt, tắt thì lỗi cũng không được ghi), đăng lại đơn, rồi xem WooCommerce > Status > Logs, nguồn kiotviet-sync.

Từng ô của tab có giải thích ở trang đồng bộ đơn hàng trong tài liệu plugin. Đăng tay, nút trên danh sách, tự động theo quy tắc, phí ship, VAT đều có sẵn trong plugin KiotViet cho WooCommerce, cùng phần đồng bộ sản phẩm, tồn kho. Giá xem ở trang sản phẩm, mua xong mình hỗ trợ cài đặt miễn phí.

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

Đơn lên KiotViet có trừ kho ngay không?

Plugin chỉ tạo phiếu Đặt hàng, không tạo hoá đơn. Tồn trên KiotViet đổi lúc nào là theo cách KiotViet xử lý phiếu và hoá đơn, plugin không quyết định mốc đó.

Đơn cần giao từ chi nhánh khác thì sao?

Mọi đơn vào “Chi nhánh mặc định”. Theo hướng dẫn Đặt hàng của KiotViet, phiếu ở trạng thái Phiếu tạm hoặc Đã xác nhận chuyển được sang chi nhánh khác xử lý, khi đã bật “Cho phép chuyển đơn đặt hàng sang chi nhánh khác” trong Thiết lập → Đơn hàng. Dev muốn chọn chi nhánh theo từng đơn thì sửa dữ liệu gửi lên bằng filter devvn_kiotviet_sync_order_payload.

Shop anh em nhận COD hay chuyển khoản là chính, muốn đơn lên KiotViet ở mốc nào? Để lại bình luận, mình gợi ý bộ quy tắc hợp với cách shop đang làm. Nhớ che số điện thoại, địa chỉ khách trước khi dán ảnh nhé.

Bài viết trong series

Kết nối WooCommerce với KiotViet

0/5đã đọc
  1. 1 KiotViet Sync đã đóng: web WooCommerce đang dùng nên làm gì? Đang đọc Đã đọc
  2. 2 Kết nối KiotViet với website: 3 cách và 6 bước nối WooCommerce Đang đọc Đã đọc
  3. 3 Đồng bộ tồn kho KiotViet với website: cơ chế và cách xử lý khi lệch Đang đọc Đã đọc
  4. 4 Đồng bộ sản phẩm KiotViet về WooCommerce: biến thể, ảnh, bảng giá Đang đọc Đã đọc
  5. 5 Đồng bộ đơn hàng KiotViet: đẩy đơn website thành phiếu Đặt hàng Đang đọc Đã đọc
Sản phẩm nổi bật của Toản
x