Plugin đồng bộ KiotViet cho WooCommerce: sản phẩm, tồn kho, đơn hàng

PLUGIN ĐỒNG BỘ KIOTVIET CHO WOOCOMMERCE LÀ GÌ?

Plugin đồng bộ KiotViet cho WooCommerce là plugin WordPress nối website WooCommerce với phần mềm bán hàng KiotViet (bán lẻ, bán buôn) qua Public API của KiotViet. Sau khi cài, hàng hoá, giá và tồn kho trên web đi theo dữ liệu trên KiotViet, còn đơn khách đặt trên web lên KiotViet thành phiếu Đặt hàng để nhân viên xử lý cùng chỗ với đơn tại cửa hàng.

Plugin do DevVN (Lê Văn Toản) viết và cập nhật, không phải ứng dụng của KiotViet. Bản hiện tại là 1.3.4. Để kết nối, gian hàng KiotViet cần có Public API, mà theo bảng phí của KiotViet là gói Cao cấp.

BÁN HÀNG BẰNG KIOTVIET NHƯNG WEBSITE VẪN NHẬP TAY?

Nếu cửa hàng chạy KiotViet mà website WooCommerce chưa kết nối, mỗi ngày thường có mấy việc này:

• Khách đặt hàng trên web trong khi cửa hàng đã bán hết, shop phải gọi xin lỗi rồi huỷ đơn.
• Hàng mới tạo trên KiotViet xong lại phải tạo lần nữa trên web, đổi giá ở KiotViet là web lệch giá.
• Đơn web phải gõ lại vào KiotViet từng đơn, từ tên, số điện thoại, địa chỉ tới sản phẩm và phí ship.
• Shop có nhiều chi nhánh, nhiều bảng giá mà không rõ web nên lấy tồn kho chi nhánh nào, giá bảng nào.
• Khách mua ở cửa hàng và khách mua trên web nằm ở hai danh sách riêng.

Còn nếu bạn là lập trình viên làm web cho khách dùng KiotViet, tự nối Public API nghĩa là tự lo lấy token bằng Client ID và Client Secret (token có hạn 24 giờ), giới hạn 5.000 request GET mỗi giờ, phân trang danh sách hàng hoá có biến thể, cộng tồn theo chi nhánh, đăng ký webhook qua API vì KiotViet bán lẻ không có màn hình thiết lập webhook, trả lời webhook trong 5 giây, rồi xử lý những địa chỉ phường/xã mà KiotViet không nhận.

DỮ LIỆU ĐI GIỮA KIOTVIET VÀ WEBSITE THẾ NÀO?

Mỗi loại dữ liệu đi theo một chiều rõ ràng:

1. Danh mục, hàng hoá, biến thể, ảnh, mô tả, thương hiệu, mã vạch đi từ KiotViet về web. Bạn chọn hàng nào tạo mới, hàng nào ghép với sản phẩm đã có trên web.
2. Giá thường và giá khuyến mãi đi từ KiotViet về web, lấy theo giá niêm yết hoặc một bảng giá bạn chọn.
3. Tồn kho đi từ KiotViet về web, cộng từ các chi nhánh bạn chọn. Khi hàng hoá, giá hay tồn kho đổi trên KiotViet, KiotViet gửi webhook và plugin cập nhật web trong nền.
4. Đơn khách đặt trên web đi lên KiotViet thành phiếu Đặt hàng, khi bạn bấm nút hoặc tự động theo quy tắc bạn đặt.
5. Hai tuỳ chọn mặc định tắt: nhận trạng thái đơn (như Hoàn thành, Đã hủy) từ KiotViet về web, và đồng bộ khách hàng theo một chiều hoặc cả hai chiều.

Plugin không đẩy sản phẩm, giá hay tồn kho từ web lên KiotViet. Hàng hoá quản lý ở KiotViet, web nhận theo. Ngoài các nút đồng bộ bấm tay, thay đổi về web qua webhook; plugin không có lịch tự đồng bộ lại toàn bộ sản phẩm.

TÍNH NĂNG CỦA PLUGIN

14 nhóm tính năng dưới đây đều có trong bản 1.3.4, từ kết nối Public API, đồng bộ danh mục, sản phẩm, giá, tồn kho tới đăng đơn, khách hàng và trang thanh toán:

Tab “Bắt đầu” chỉ ra bước nào còn thiếu

Mở WooCommerce → Đồng bộ KiotViet, tab “Bắt đầu” xếp sẵn 10 bước cài đặt theo thứ tự. Mỗi bước hiện Hoàn thành, Cần kiểm tra hoặc Chưa làm, kèm nút “Thiết lập” để vào phần đó.

• Bước bắt buộc gồm kích hoạt license, kết nối API, đồng bộ sản phẩm lần đầu, đăng ký webhook, và cập nhật dữ liệu địa chỉ khi cửa hàng ở Việt Nam.
• Mục “Kiểm tra môi trường” soát đường dẫn tĩnh, HTTPS, WP-Cron và Action Scheduler trước khi bạn đồng bộ.
• Nút “Sao chép báo cáo” chép tình trạng cài đặt để gửi qua Zalo khi cần hỗ trợ.

Kết nối Public API KiotViet, chọn chi nhánh tính tồn kho

Dán Retailer, Client ID và Client Secret lấy từ KiotViet vào tab “Cài đặt API” rồi bấm “Kiểm tra kết nối”. Plugin tự lấy token và làm mới token trước khi hết hạn, bạn không phải nhập lại.

• Chọn một hoặc nhiều chi nhánh để cộng tồn kho; để trống thì plugin cộng tất cả chi nhánh.
• Kiểm tra kết nối xong là có danh sách bảng giá đang hoạt động để chọn ở tab “Đồng bộ sản phẩm”.
• Bật “Xóa cache” thì plugin xoá cache trang sản phẩm sau khi tồn kho đổi, với WP Rocket, W3 Total Cache, FlyingPress.

Chuyển từ plugin KiotViet Sync cũ mà giữ liên kết sản phẩm

Website đang dùng plugin KiotViet Sync (đã đóng trên WordPress.org từ 04/11/2025) bấm “Chuyển ID từ plugin cũ” ở tab “Cài đặt API”. Plugin đọc dữ liệu liên kết mà plugin cũ để lại và gán KiotViet ID cho sản phẩm, danh mục đang có trên web.

• Nút chỉ gán ID, không tạo lại sản phẩm, không sửa tên, ảnh, mô tả đang có.
• Sản phẩm, danh mục đã có KiotViet ID thì được bỏ qua.
• Sau đó bạn dùng bảng sản phẩm và webhook như một website cài mới.

Ánh xạ danh mục KiotViet với danh mục trên web

Bấm “Tải danh mục Kiotviet” để xem các nhóm hàng trên KiotViet. Với từng danh mục, bạn chọn Tạo mới, Ánh xạ có sẵn (ghép với danh mục đã có trên web) hoặc Bỏ qua; nhiều danh mục thì dùng “Áp dụng hàng loạt”.

• Ô “Bỏ qua sản phẩm thuộc danh mục Skip” bật sẵn, nên sản phẩm thuộc danh mục để Bỏ qua không về web, kể cả qua webhook.
• Có tuỳ chọn tự tạo danh mục cha và tự liên kết cha con theo cây danh mục trên KiotViet.
• Plugin không nhận webhook danh mục, nên khi thêm nhóm hàng mới thì vào tab này bấm “Đồng bộ danh mục ngay”.

Kéo hàng hoá, biến thể từ KiotViet về WooCommerce

Bấm “Tải từ API KiotViet” là plugin tải hàng hoá kèm tồn kho, bảng giá vào một bảng riêng trên website. Bạn lọc theo danh mục, loại sản phẩm, trạng thái, tồn kho, chọn sản phẩm rồi bấm “Đồng bộ đã chọn”, hoặc “Đồng bộ đã chọn trong nền” khi danh sách dài.

• Mỗi dòng chọn Tạo mới, Cập nhật hoặc Bỏ qua lần này; chọn Tạo mới cho sản phẩm đã có thì plugin bỏ qua, không tạo trùng.
• Hàng hoá cùng loại trên KiotViet thành sản phẩm biến thể, mã hàng thành SKU.
• Web có sẵn sản phẩm thì bấm “Auto Mapping” để liên kết theo SKU, hoặc “Auto Mapping theo tên” cho sản phẩm chưa có SKU và xem cột Độ khớp trước khi lưu.
• Đồng bộ trong nền có nút “Hủy đồng bộ”, và báo khi tiến trình có vẻ bị treo để bạn bấm “Tiếp tục đồng bộ”.

Chọn trường lấy từ KiotViet, giữ nội dung đã viết trên web

Mỗi shop chỉnh nội dung web một kiểu, nên tab “Đồng bộ sản phẩm” cho bật tắt từng trường và chọn có ghi đè dữ liệu đang có hay không.

• Lấy được tên, mô tả đầy đủ (giữ định dạng), ảnh đại diện, gallery, trọng lượng, thương hiệu vào Brands của WooCommerce và mã vạch của sản phẩm đơn vào ô GTIN.
• Mô tả, ảnh đại diện và gallery mặc định không ghi đè, chỉ điền khi sản phẩm trên web còn trống.
• Ảnh đã tải thì không tải lại; ảnh phụ của biến thể lưu riêng cho theme có hỗ trợ, ví dụ Flatsome.
• Sản phẩm mới đặt đường dẫn theo tên hoặc theo mã hàng, hợp với tên sản phẩm không viết bằng chữ Latin.

Giá theo bảng giá bạn chọn, tồn kho theo chi nhánh

Mục “Mapping Giá” cho giá thường lấy từ giá niêm yết hoặc một bảng giá KiotViet. Giá khuyến mãi lấy từ một bảng giá, hoặc không dùng. Sửa giá trong bảng giá trên KiotViet thì web nhận theo qua webhook.

• Tồn kho cộng từ các chi nhánh đã chọn, có ô bỏ qua số âm khi cộng (bật sẵn).
• Bật “Trừ hàng tạm giữ (reserved) khỏi tồn kho” thì tồn trên web bằng tồn KiotViet trừ hàng tạm giữ.
• Bán theo kg, lít, mét thì bật tồn kho số lẻ (áp dụng cho toàn website).
• Khi cần đối soát, bấm “Tải từ API KiotViet” rồi “Đồng bộ tồn kho” để cập nhật lại tồn cho sản phẩm đã chọn hoặc tất cả.

Web tự cập nhật qua webhook, tự đăng ký lại khi KiotViet tắt

Bấm “Đăng ký tất cả webhook” một lần, KiotViet báo về website mỗi khi hàng hoá, tồn kho, bảng giá, khách hàng hay đơn hàng thay đổi (11 sự kiện). Plugin ghi từng sự kiện vào hàng đợi, phần cập nhật sản phẩm chạy nền sau đó.

• Sự kiện trùng của cùng một sản phẩm được gộp lại, giữ bản mới; gặp lỗi thì thử lại tối đa 3 lần.
• Màn hình hàng đợi cho xem sự kiện chờ xử lý, hoàn tất, thất bại và đưa sự kiện lỗi về xử lý lại.
• KiotViet có thể tắt webhook khi website trả lỗi 4xx hoặc trả lời chậm quá 5 giây. Plugin kiểm tra định kỳ (mặc định mỗi giờ) và tự đăng ký lại, quá 3 lần trong 24 giờ thì email báo admin.
• Hàng mới tạo trên KiotViet tự lên web khi bạn bật “Tự động tạo sản phẩm mới” (mặc định tắt).

Hàng ngừng bán và sản phẩm không muốn đồng bộ

Sản phẩm nào cần giữ nguyên trên web, bạn tick “Không đồng bộ từ KiotViet” ở tab Kho hàng của sản phẩm, hoặc “Không đồng bộ KiotViet” ở từng biến thể. Plugin bỏ qua sản phẩm đó ở mọi lần đồng bộ tay, đồng bộ nền và webhook.

• Bật, tắt cho nhiều sản phẩm một lúc bằng thao tác hàng loạt “KiotViet: Không đồng bộ” và “KiotViet: Đồng bộ lại”.
• Hàng ngừng kinh doanh trên KiotViet được xử lý theo cách bạn chọn: chuyển Bản nháp (mặc định), Riêng tư, đặt Hết hàng, ẩn khỏi cửa hàng hoặc chuyển vào thùng rác.
• Hàng kinh doanh lại thì sản phẩm trên web tự khôi phục.

Đăng đơn web lên KiotViet thành phiếu Đặt hàng

Trong trang sửa đơn, bấm “Post to KiotViet” ở khung KiotViet Order Sync. Hộp “Đăng đơn lên KiotViet” điền sẵn khách, sản phẩm, số tiền khách đã trả và dịch vụ giao hàng, bạn xem lại rồi bấm “Đăng đơn”.

• Đơn lên KiotViet là phiếu Đặt hàng ở chi nhánh mặc định. Nhân viên xử lý phiếu và xuất hoá đơn trên KiotViet.
• Ô “Ghi chú gửi KiotViet” sửa ghi chú trên phiếu mà không đổi ghi chú đơn trên web.
• Phiếu đã đăng sửa hoặc xoá được ngay từ trang đơn trên web.
• Bật giao diện danh sách đơn kiểu mới ở tab “Cài đặt chung” thì mỗi dòng đơn có nút Đăng KV, Hủy KV và mã phiếu KiotViet.

Tự động đăng đơn theo trạng thái và hình thức thanh toán

Bật “Tự động đăng đơn” (mặc định tắt) rồi thêm quy tắc ở “Quy tắc tự động đăng”. Mỗi quy tắc gồm trạng thái đơn và hình thức thanh toán; đơn khớp quy tắc nào thì tự lên KiotViet trong nền.

• Ví dụ, đơn mới thanh toán khi nhận hàng đăng lúc vừa tạo, đơn chuyển khoản đăng khi chuyển sang Đang xử lý.
• Đơn đã có mã KiotViet thì không đăng lại; đơn có sản phẩm chưa liên kết KiotViet thì không đăng.
• Ô “Ghi chú khi tự động đăng” thêm một dòng ghi chú cố định vào phiếu, dưới ghi chú của khách.
• KiotViet không nhận phường/xã hay khu vực thì plugin chuyển phần đó vào ô địa chỉ rồi gửi lại, có ghi chú vào đơn.

Phí ship, phụ thu, VAT và trạng thái đơn từ KiotViet về web

Tab “Đồng bộ đơn hàng” quyết định các khoản ngoài tiền hàng đi lên KiotViet thế nào. Phí vận chuyển và phí khác gửi lên dạng thu khác, VAT gửi theo từng sản phẩm, mã giảm giá gửi thành giảm giá trên phiếu.

• “Ánh xạ phí khác” ghép tên phí trên web, như phí thu hộ hay phí đóng gói, với khoản thu khác trên KiotViet.
• Phụ thu và VAT mặc định tắt; KiotViet cần bật “Hỗ trợ các khoản thu khác khi bán hàng” và cấu hình thuế trước.
• Chọn “Kênh bán hàng” và “Dịch vụ giao hàng mặc định” cho đơn từ web.
• Bật “Kích hoạt đồng bộ trạng thái” thì khi phiếu chuyển Hoàn thành hay Đã hủy trên KiotViet, đơn web đổi trạng thái theo bảng ánh xạ bạn đặt.

Đồng bộ khách hàng giữa website và KiotViet

Ở tab “Đồng bộ khách hàng”, chọn một trong bốn chế độ: tắt (mặc định), từ KiotViet về web, từ web lên KiotViet hoặc cả hai chiều. Chọn cả hai chiều thì khách mua ở cửa hàng và khách mua trên web nằm chung một danh sách.

• Plugin ghép khách theo liên kết đã có, rồi số điện thoại (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 đè.
• Khách đăng ký mới, sửa hồ sơ hoặc đặt hàng không đăng nhập ở trang thanh toán cổ điển tự lên KiotViet khi bạn bật từng ô.
• Khách mới tạo trên KiotViet tự thành tài khoản trên web khi bật “Tự động tạo user”.
• Trang Thành viên của WordPress có cột KiotViet để tạo, đồng bộ lại hoặc huỷ liên kết từng người.

Trang thanh toán Việt Nam, địa chỉ 2 cấp theo địa giới mới

Plugin kèm sẵn phần trang thanh toán cho khách Việt Nam: ô chọn Tỉnh/Thành, Phường/Xã theo địa giới mới (34 tỉnh, 3.321 phường/xã), dữ liệu nằm sẵn trong plugin. Chọn bộ địa chỉ 2 cấp ở tab “Cài đặt chung” và bấm “Cập nhật database” một lần; bộ 3 cấp cũ vẫn chọn được.

• Tên phường/xã gửi lên KiotViet được viết lại theo cách KiotViet dùng, ví dụ dấu kiểu Hòa, Thủy.
• Ô Họ và tên gộp làm một ở cả checkout block lẫn trang thanh toán cổ điển.
• Trang thanh toán cổ điển có thêm kiểm số điện thoại Việt Nam, không bắt buộc email, reCAPTCHA và chặn đơn theo IP, từ khoá.
• Đơn của shop bán ở Nhật có địa chỉ Nhật (47 tỉnh, 1.559 thành phố) đổi sang khu vực giao hàng của KiotViet Nhật.

Xem giá & mua

LÀM TAY VÀ DÙNG PLUGIN KHÁC NHAU THẾ NÀO?

CÁCH KẾT NỐI KIOTVIET VỚI WOOCOMMERCE TRONG 6 BƯỚC

Không cần biết lập trình. Mỗi bước có hướng dẫn kèm ảnh trong tài liệu plugin:

1. Cài plugin như mọi plugin WordPress rồi nhập mã license ở tab “License”. Plugin nằm ở menu WooCommerce → Đồng bộ KiotViet, tab “Bắt đầu” liệt kê các bước còn thiếu. Xem Kích hoạt license và Bắt đầu.
2. Trên KiotViet, tài khoản admin của chủ gian hàng tạo Client ID và Mã bảo mật ở mục Kết nối API. Dán Retailer (tên gian hàng), Client ID, Client Secret vào tab “Cài đặt API”, bấm “Kiểm tra kết nối” rồi chọn chi nhánh tính tồn kho. Xem Cài đặt API.
3. Ở tab “Ánh xạ danh mục”, chọn Tạo mới, Ánh xạ có sẵn hoặc Bỏ qua cho từng danh mục KiotViet. Xem Ánh xạ danh mục.
4. Ở tab “Đồng bộ sản phẩm” chọn trường cần lấy và bảng giá, bấm “Tải từ API KiotViet”, chọn sản phẩm rồi bấm “Đồng bộ đã chọn trong nền”. Xem Đồng bộ sản phẩm.
5. Ở tab “Webhook”, bấm “Đăng ký tất cả webhook” để web tự nhận thay đổi từ KiotViet. Xem Webhook.
6. Ở tab “Đồng bộ đơn hàng”, chọn “Chi nhánh mặc định” nhận đơn web, bật tự động đăng đơn nếu cần. Khách hàng cài ở tab “Đồng bộ khách hàng”. Xem Đồng bộ đơn hàng và Đồng bộ khách hàng.

Cần người cài giúp? Hỗ trợ cài đặt miễn phí qua Zalo. Muốn đọc kỹ trước khi mua thì xem tổng quan tài liệu plugin.

ĐANG DÙNG PLUGIN KIOTVIET SYNC CŨ?

Plugin KiotViet Sync (tác giả KiotViet) trên WordPress.org đã đóng từ 04/11/2025 theo yêu cầu của tác giả. Bản cuối là 1.8.5 và không còn được cập nhật. Website còn dùng plugin đó chuyển sang plugin của DevVN được mà không phải tạo lại sản phẩm:

1. Cài plugin của DevVN, kích hoạt license, nhập thông tin API như bước 2 ở trên.
2. Ở tab “Cài đặt API”, bấm “Chuyển ID từ plugin cũ”. Plugin đọc dữ liệu liên kết mà KiotViet Sync để lại trong cơ sở dữ liệu, gán KiotViet ID cho sản phẩm và danh mục đang có trên web, bỏ qua mục đã có ID. Nút này cần dữ liệu plugin cũ còn trong cơ sở dữ liệu, nên làm trước khi dọn plugin cũ.
3. Lọc “Liên kết WooCommerce” ở tab “Đồng bộ sản phẩm” để xem sản phẩm nào đã liên kết, rồi làm tiếp bước webhook và đơn hàng như cài mới.

Plugin của DevVN là sản phẩm riêng, không phải bản mới của KiotViet Sync. Cần chuyển giúp thì nhắn Zalo, hỗ trợ cài đặt miễn phí.

AI NÊN DÙNG PLUGIN NÀY?

• Chủ shop và chuỗi cửa hàng bán lẻ đang dùng KiotViet, có website WooCommerce, muốn giá và tồn kho trên web đi theo KiotViet, đơn web vào KiotViet mà không phải gõ lại.
• Lập trình viên, đơn vị làm web cho khách dùng KiotViet, không muốn tự viết và bảo trì phần Public API, vì plugin có sẵn filter để sửa dữ liệu đơn, khách, giao hàng, địa chỉ trước khi gửi lên KiotViet.
• Shop đang dùng plugin KiotViet Sync cũ, cần chuyển sang plugin còn cập nhật mà giữ liên kết sản phẩm, xem cách chuyển ở trên.
• Shop muốn giữ website WordPress đang có giao diện, bài viết và thứ hạng Google, thay vì dựng lại website trên nền khác.

Plugin dùng Public API của KiotViet bán lẻ, bán buôn, không dùng được cho KiotViet FnB (nhà hàng, quán cà phê). Đang dùng Nhanh.vn thay vì KiotViet? Xem plugin kết nối Nhanh.vn với WooCommerce.

XEM PLUGIN HOẠT ĐỘNG

Video hướng dẫn kết nối qua 6 bước, quay trên website thử với dữ liệu mẫu. Bốn video ngắn về tồn kho, sản phẩm, đơn hàng và chuyển từ KiotViet Sync nằm ở các trang tương ứng trong tài liệu plugin.

YÊU CẦU HỆ THỐNG VÀ TƯƠNG THÍCH

• WordPress 5.0 trở lên, đã kiểm tra tới WordPress 6.9.4.
• WooCommerce 6.0 trở lên, đã kiểm tra tới WooCommerce 11.1.2.
• PHP 7.2 trở lên, MySQL 5.7 trở lên hoặc MariaDB tương đương.
• KiotViet bán lẻ, bán buôn có Public API. Theo bảng phí của KiotViet, Public API thuộc gói Cao cấp.
• WP-Cron chạy được (hoặc cron thật trên hosting), vì webhook, đồng bộ nền và tự động đăng đơn chạy qua Action Scheduler của WooCommerce.
• Tương thích HPOS (cách lưu đơn hàng mới của WooCommerce), bật hay tắt đều chạy.
• Checkout block có ô chọn Tỉnh/Thành, Phường/Xã theo địa chỉ 2 cấp. Kiểm tra số điện thoại, reCAPTCHA, chặn đơn theo IP và từ khoá chạy ở trang thanh toán cổ điển.

Tab “Bắt đầu” có mục “Kiểm tra môi trường” soát sẵn đường dẫn tĩnh, HTTPS, WP-Cron và Action Scheduler trên website của bạn.

Lập trình viên có filter để tuỳ biến mà không sửa lõi plugin: sửa toàn bộ dữ liệu đơn gửi lên KiotViet (devvn_kiotviet_sync_order_payload), từng dòng sản phẩm, khối khách hàng, khối giao hàng, ghi chú đơn, phụ thu, tên khu vực và phường/xã. Danh sách filter và ví dụ nằm ở trang Hook cho lập trình viên trong tài liệu plugin.

CHỌN GÓI PHÙ HỢP

Đổi tên miền? Nhắn Zalo để được gỡ liên kết tên miền cũ.

Xem giá & chọn gói

CÂU HỎI THƯỜNG GẶP

Còn thắc mắc về cài đặt? Xem trang Hỏi đáp trong tài liệu plugin.

MUA VÀ CÀI ĐẶT

Mua xong, mã license gửi qua email. Bạn cài theo 6 bước ở trên, hoặc nhắn Zalo để được cài giúp miễn phí.

Xem giá & mua

Cần tư vấn trước khi mua? Nhắn Zalo 0965 419 096.

LỊCH SỬ CẬP NHẬT