Đồng bộ KiotViet cho WooCommerce
Plugin kéo sản phẩm, giá và tồn kho từ KiotViet về WooCommerce, rồi đưa đơn hàng từ website lên KiotViet thành phiếu Đặt hàng. Khách hàng đồng bộ được theo chiều bạn chọn. Trang này là lộ trình cài đặt từ lúc kích hoạt tới khi chạy tự động.
Cần chuẩn bị gì
- Website chạy WordPress 5.0 trở lên, PHP 7.2 trở lên và đã bật WooCommerce 6.0 trở lên. Bật hay tắt HPOS (bảng đơn hàng mới của WooCommerce) đều chạy được.
- Gian hàng KiotViet bán lẻ, bán buôn có Public API. Theo bảng phí dịch vụ của KiotViet (xem ngày 12/10/2026), Public API thuộc gói Cao cấp. Plugin không dùng được với KiotViet FnB.
- Tài khoản admin của chủ gian hàng KiotViet. Chỉ tài khoản này thấy mục tạo Client ID và Mã bảo mật.
- Mã license đã mua tại levantoan.com.
- Website chạy HTTPS, đường dẫn tĩnh không để dạng Plain, WP-Cron hoạt động hoặc hosting đã cài cron thật. Webhook và đồng bộ trong nền cần cả ba, tab Bắt đầu tự kiểm giúp bạn.
Lần đồng bộ đầu có thể tạo mới hoặc ghi đè hàng nghìn sản phẩm, và không có nút hoàn tác. Sao lưu mã nguồn cùng cơ sở dữ liệu trước khi bấm đồng bộ lần đầu.
Lộ trình 10 bước
Plugin có sẵn tab Bắt đầu tự kiểm bạn đã làm tới đâu. Thứ tự dưới đây trùng với thứ tự trong tab đó, cứ đi lần lượt từ trên xuống.
Chưa kích hoạt thì mọi lệnh gọi sang KiotViet đều bị chặn.
Chọn bộ địa chỉ 2 cấp hoặc 3 cấp rồi bấm Cập nhật database. Bắt buộc khi cửa hàng đặt ở Việt Nam.
Nhập Retailer, Client ID, Client Secret rồi kiểm tra kết nối.
Chọn chi nhánh lấy tồn kho. Để trống là cộng tồn của mọi chi nhánh.
Quyết định nhóm hàng KiotViet vào danh mục nào của WooCommerce.
Tải sản phẩm về bảng tạm rồi đưa sang WooCommerce.
Chọn chi nhánh, kênh bán và quy tắc tự động đăng đơn lên KiotViet.
Chọn khoản "thu khác" trên KiotViet để nhận tiền phí ship.
Chọn chiều đồng bộ khách hàng. Mặc định đang tắt.
Không có webhook thì thay đổi trên KiotViet không tự về website.
Bước 2 chỉ bắt buộc khi địa chỉ cửa hàng trong WooCommerce đặt ở Việt Nam. Năm bước còn lại bật khi bạn cần. Bật từng thứ một, có trục trặc thì biết ngay do đâu.
Plugin hoạt động thế nào
Biết dữ liệu đi chiều nào thì dễ đoán nguyên nhân khi có trục trặc.
| Chiều dữ liệu | Chạy khi nào | Dùng cho |
|---|---|---|
| KiotViet → Website qua webhook | Khi có thay đổi trên KiotViet. Plugin xếp vào hàng đợi rồi xử lý trong nền, thường mất từ vài giây tới khoảng một phút tuỳ WP-Cron của hosting. | Tồn kho, giá theo bảng giá, thông tin sản phẩm, xoá sản phẩm. Khách hàng và trạng thái đơn khi bạn bật. |
| KiotViet → Website bấm tay | Khi bạn bấm trong tab Đồng bộ sản phẩm. | Lần cài đầu, hoặc đối soát lại sau khi website lỡ webhook. |
| Website → KiotViet | Khi bạn bấm đăng đơn, hoặc khi đơn khớp quy tắc tự động đăng. | Đơn hàng (thành phiếu Đặt hàng). Khách hàng khi bạn chọn chiều này. |
| Website → KiotViet | Không có. | Sản phẩm, giá, tồn kho sửa trên web không đẩy ngược lên KiotViet. |
Tên, giá, tồn kho bạn sửa trên web bị ghi đè ở lần đồng bộ sau, theo các ô ghi đè ở tab Đồng bộ sản phẩm. Sản phẩm cần giữ nguyên như trên web thì bật ô Không đồng bộ từ KiotViet cho riêng sản phẩm đó.
Giới hạn nên biết trước khi dùng
- Plugin không có lịch đồng bộ định kỳ. Ngoài lúc bạn bấm tay, mọi thay đổi về web đều đi qua webhook. Website sập hay bảo trì làm lỡ webhook thì đối soát theo bài Webhook.
- Đơn từ web lên KiotViet là phiếu Đặt hàng. Plugin không tạo hoá đơn; xác nhận phiếu, giao hàng, xuất hoá đơn làm trên KiotViet.
- Xoá hàng hoá trên KiotViet thì sản phẩm trên web bị xoá vĩnh viễn, không vào thùng rác, nếu website đã đăng ký sự kiện
product.delete. - Mỗi lần KiotViet cập nhật một sản phẩm, sản phẩm đó trên web được đưa về trạng thái Đã xuất bản và hiện lại trong cửa hàng.
- Ô Giá khuyến mãi để mặc định "-- Không dùng --" thì giá khuyến mãi bạn tự đặt trên web bị xoá ở lần đồng bộ sau.
- Chặn đơn rác (reCAPTCHA, chặn IP, chặn từ khoá) và kiểm số điện thoại Việt Nam ở tab Cài đặt chung chỉ chạy ở trang thanh toán cổ điển, không chạy ở trang thanh toán dạng block.
- License hết hạn hoặc chưa kích hoạt thì mọi lệnh plugin gọi sang KiotViet bị chặn. Dữ liệu đã đồng bộ vẫn nằm nguyên trên web.
Có gì mới ở bản 1.3.x
- Ô Không đồng bộ từ KiotViet cho từng sản phẩm, từng biến thể, kèm thao tác hàng loạt trong danh sách sản phẩm (1.3.3). Xem Đồng bộ sản phẩm.
- Link Huỷ liên kết trong bảng sản phẩm của plugin, gỡ KiotViet ID mà không đụng dữ liệu khác (1.3.3).
- Ô Đường dẫn sản phẩm mới cho phép đặt đường dẫn theo mã hàng thay cho tên, hợp với tên tiếng Nhật, tiếng Trung (1.3.3).
- Tên phường/xã được viết lại theo cách KiotViet đang dùng; KiotViet vẫn không nhận thì plugin chuyển phần đó vào ô địa chỉ và gửi lại ngay. Địa chỉ khách ở Nhật Bản gửi theo khu vực giao hàng của KiotViet Nhật (1.3.3). Xem Đồng bộ đơn hàng.
- Ô Ghi chú gửi KiotViet trong hộp thoại đăng đơn và ô Ghi chú khi tự động đăng trong tab Đồng bộ đơn hàng (1.3.4).
- Bài Hook cho lập trình viên liệt kê 17 filter có trong mã nguồn, kèm ví dụ chạy được.
Đang dùng plugin KiotViet Sync cũ
Plugin KiotViet Sync đã đóng trên WordPress.org từ 04/11/2025, bản cuối là 1.8.5. Website đang dùng nó chuyển sang được mà không tạo lại sản phẩm: nút Chuyển ID từ plugin cũ ở tab Cài đặt API đọc bảng dữ liệu plugin cũ để lại và gán KiotViet ID cho sản phẩm, danh mục đã có. Các bước ở bài Kết nối API KiotViet.
Tab Cài đặt chung
Tab này chứa phần trang thanh toán Việt Nam dùng chung với các plugin vận chuyển của DevVN: ô chọn Tỉnh/Thành, Phường/Xã, gộp họ tên, kiểm số điện thoại, Google reCAPTCHA, chặn đơn theo IP và từ khoá. Hai chỗ liên quan tới KiotViet là mục Cập nhật dữ liệu địa chỉ (bước 2, xem bài Danh sách kiểm tra) và ô Thay đổi giao diện trang đơn hàng. Ô này mặc định tắt; bật lên thì danh sách đơn có thêm nhãn trạng thái KiotViet cùng hai nút Đăng KV, Hủy KV.
Bắt đầu từ đâu
Mở Danh sách kiểm tra để xem website đang thiếu bước nào, rồi làm tiếp License và cập nhật.