DevVN Docs Đồng bộ KiotViet

Đồng bộ KiotViet cho WooCommerce

Plugin kéo sản phẩm, tồn kho và giá từ KiotViet về website, đồng thời đẩy đơn hàng và khách hàng ngược lại. Trang này là lộ trình cài đặt từ lúc mới kích hoạt cho tới khi chạy tự động.

Phiên bản plugin 1.2.8 Cập nhật 05.09.2026 Thời gian cài đặt khoảng 30 phút

Cần chuẩn bị gì

  • Website WordPress đã cài và kích hoạt WooCommerce.
  • Tài khoản KiotViet có quyền tạo kết nối API (thường là chủ cửa hàng hoặc quản lý).
  • Mã license plugin đã mua tại levantoan.com.
  • Đường dẫn tĩnh (permalink) của website không để ở dạng mặc định — webhook cần đường dẫn tĩnh mới hoạt động.
Làm trên website thật thì sao lưu trước

Lần đồng bộ đầu tiên có thể tạo mới hoặc ghi đè hàng nghìn sản phẩm. Hãy sao lưu mã nguồn và 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 tra 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.

1Bắt buộc
Kích hoạt License

Chưa kích hoạt thì mọi kết nối tới KiotViet đều bị chặn.
2Bắt buộc
Cập nhật dữ liệu địa chỉ

Đơn vị hành chính phải khớp với KiotViet, nếu không địa chỉ đơn hàng sẽ sai.
3Bắt buộc
Kết nối API KiotViet

Nhập Retailer, Client ID, Client Secret rồi kiểm tra kết nối.
4Tuỳ chọn
Chọn chi nhánh

Giới hạn lấy tồn kho và giá từ những chi nhánh cụ thể.
5Tuỳ chọn
Ánh xạ danh mục

Quyết định danh mục KiotViet sẽ vào danh mục nào của WooCommerce.
6Bắt buộc
Đồng bộ sản phẩm lần đầu

Tải sản phẩm về bộ nhớ đệm rồi đưa sang WooCommerce.
7Tuỳ chọn
Đồng bộ đơn hàng

Chọn chi nhánh, kênh bán và quy tắc tự đẩy đơn lên KiotViet.
8Tuỳ chọn
Phí vận chuyển & phụ thu

Chọn khoản "thu khác" trên KiotViet để nhận tiền phí ship.
9Tuỳ chọn
Đồng bộ khách hàng

Chọn chiều đồng bộ khách hàng giữa WooCommerce và KiotViet.
10Bắt buộc
Đăng ký Webhook

Không có webhook thì thay đổi trên KiotViet sẽ không tự về website.
Bước 1, 3, 6 và 10 là tối thiểu để chạy được

Sáu bước còn lại chỉ bật khi bạn thật sự cần. Cài quá nhiều thứ cùng lúc sẽ khó biết lỗi nằm ở đâu khi có sự cố.

Plugin hoạt động thế nào

Hiểu sơ nguyên lý sẽ giúp bạn tự đoán được nguyên nhân khi có trục trặc:

Chiều dữ liệuChạy khi nàoDùng cho
KiotViet → Website
qua Webhook		 Ngay khi có thay đổi ở KiotViet, mất 3–5 giây Tồn kho, giá, thông tin sản phẩm
KiotViet → Website
đồng bộ thủ công		 Khi bạn tự bấm trong tab Đồng bộ sản phẩm Lần đầu cài đặt, hoặc khi cần nạp lại toàn bộ
Website → KiotViet Khi có đơn mới hoặc đơn đổi trạng thái Đơn hàng, khách hàng
KiotViet là nguồn dữ liệu chính

Với sản phẩm đã liên kết, sửa tên hay tồn kho ở WooCommerce sẽ bị ghi đè ở lần đồng bộ kế tiếp. Muốn đổi gì thì đổi bên KiotViet.

Bắt đầu từ đâu

Mở Danh sách kiểm tra để xem website của bạn đang thiếu bước nào, rồi làm tiếp Kết nối API KiotViet.

Hỗ trợ Zalo