Giải đáp thắc mắc

Theo bảng phí dịch vụ trên kiotviet.vn (xem ngày 12/10/2026), Public API thuộc gói Cao cấp. Gian hàng đang dùng gói Hỗ trợ hay Chuyên nghiệp thì hỏi KiotViet trước khi mua plugin. Client ID và Mã bảo mật chỉ hiện với tài khoản admin của chủ gian hàng; cách lấy ở bài Kết nối API KiotViet.

Không. Plugin chỉ kết nối với Public API của KiotViet bán lẻ, bán buôn. KiotViet FnB dùng một API riêng mà plugin không gọi tới.

Không. Plugin do DevVN viết, kết nối qua Public API mà KiotViet công bố cho các phần mềm bên ngoài. Hỗ trợ plugin do DevVN lo; câu hỏi về gói dịch vụ, mã API thì hỏi KiotViet.

Plugin KiotViet Sync đã đóng trên WordPress.org từ 04/11/2025, bản cuối là 1.8.5 và không còn được cập nhật. Website đang dùng nó chuyển sang plugin này mà không phải tạo lại sản phẩm:

1. Sao lưu website.
2. Cài plugin, kích hoạt license, kết nối API.
3. Ở cuối tab Cài đặt API, bấm Chuyển ID từ plugin cũ. Plugin đọc bảng dữ liệu KiotViet Sync để lại và gán KiotViet ID cho sản phẩm, danh mục đã có trên web. Bảng đó vẫn còn khi bạn đã tắt hay xoá KiotViet Sync.
4. Sang tab Đồng bộ sản phẩm, bấm Tải từ API KiotViet, đồng bộ thử vài sản phẩm, rồi đăng ký webhook.

Chi tiết ở bài Kết nối API KiotViet.

Kiểm theo thứ tự: tab Bắt đầu có báo xanh ở bước Đăng ký Webhook không; tab Webhook các sự kiện còn Active không; sản phẩm đó đã liên kết KiotViet chưa và có đang bật Không đồng bộ từ KiotViet không. Ô Chi nhánh ở tab Cài đặt API cũng quyết định con số: để trống là cộng mọi chi nhánh, chọn chi nhánh nào thì chỉ cộng chi nhánh đó.

Muốn nạp lại ngay: ở tab Đồng bộ sản phẩm bấm Tải từ API KiotViet trước, rồi mới bấm Đồng bộ tồn kho. Nút Đồng bộ tồn kho đọc số trong bảng tạm, bỏ bước tải thì web nhận lại số cũ.

Thay đổi trên KiotViet trong lúc đó không tự về sau. KiotViet còn có thể tắt webhook nếu website trả lỗi hoặc trả lời chậm quá 5 giây; plugin tự đăng ký lại (mặc định kiểm mỗi giờ), nhưng chỉ nhận được thay đổi từ lúc bật lại.

Website chạy lại thì: bấm Tải từ API KiotViet, bấm Đồng bộ tồn kho chọn Tất cả sản phẩm; giá hay tên cũng đổi thì lọc "Đã liên kết (cập nhật)" rồi Đồng bộ tất cả theo filter. Các bước ở bài Webhook.

Không. Ngoài lúc bạn bấm tay, thay đổi về web chỉ đi qua webhook. Lịch chạy định kỳ của plugin chỉ có kiểm license, dọn hàng đợi webhook và tự đăng ký lại webhook bị tắt.

Ô Giá khuyến mãi ở mục Mapping Giá đang để "-- Không dùng --" (mặc định). Khi đó mỗi lần sản phẩm được đồng bộ, kể cả qua webhook, giá khuyến mãi trên web bị xoá trống. Giá khuyến mãi cũng bị xoá khi nó không nhỏ hơn giá thường.

Cách giữ: tạo bảng giá khuyến mãi trên KiotViet và chọn nó ở ô Giá khuyến mãi, hoặc bật Không đồng bộ từ KiotViet cho những sản phẩm bạn tự đặt giá. Xem bài Đồng bộ sản phẩm.

Hai nguyên nhân hay gặp. Giá bạn đổi nằm ở bảng giá khác với bảng đang chọn trong Mapping Giá, nên plugin bỏ qua. Hoặc plugin bộ nhớ đệm (WP Rocket, LiteSpeed Cache...) đang giữ trang cũ; bật ô Xóa cache ở tab Cài đặt API để plugin xoá bộ nhớ đệm của sản phẩm sau mỗi lần cập nhật.

Vào tab Cài đặt API, ô Chi nhánh chọn đúng chi nhánh cần dùng rồi lưu. Để trống là cộng tồn của mọi chi nhánh. Plugin không có kiểu gán chi nhánh này cho kho kia trên web, các chi nhánh đã chọn luôn được cộng dồn thành một con số.

Sản phẩm cũ trên web có SKU khác mã hàng KiotViet và chưa được nối, nên plugin coi là hàng mới và tạo thêm. Lần sau chạy Auto Mapping, rồi Auto Mapping theo tên cho phần còn lại, trước khi đồng bộ.

Với số hàng đã trùng, lọc Liên kết WooCommerce là "Chưa liên kết (tạo mới)" để khoanh vùng. Lỡ nối nhầm thì dùng link Huỷ liên kết trong bảng sản phẩm.

Ô "Ghi đè tên sản phẩm nếu sản phẩm đã có tên" mặc định bật, nên lần đồng bộ sau lấy lại tên trên KiotViet. Tắt ô đó ở khối Tùy chọn đồng bộ, hoặc bật Không đồng bộ từ KiotViet cho riêng sản phẩm đó.

Mỗi lần KiotViet cập nhật một sản phẩm, plugin đưa sản phẩm đó trên web về Đã xuất bản và hiện trong cửa hàng. Muốn ẩn lâu dài thì bật Không đồng bộ từ KiotViet trong trang sửa sản phẩm, tab Kiểm kê kho hàng; hoặc ngừng kinh doanh hàng đó trên KiotViet để plugin xử lý theo ô Khi sản phẩm ngừng kinh doanh.

Có, nếu website đã đăng ký sự kiện product.delete (nút Đăng ký tất cả webhook có đăng ký sự kiện này). Sản phẩm hoặc biến thể bị xoá vĩnh viễn, không vào thùng rác. Không muốn vậy thì xoá dòng product.delete ở tab Webhook, hoặc bật Không đồng bộ từ KiotViet cho sản phẩm cần giữ.

Không. Sản phẩm, giá, tồn kho chỉ đi một chiều từ KiotViet về web. Muốn đổi thì đổi trên KiotViet.

Bộ lọc Trạng thái trong bảng sản phẩm mặc định là "Đang hoạt động", nên hàng ngừng kinh doanh không có trong danh sách để đồng bộ. Bấm Tải từ API KiotViet, đổi bộ lọc Trạng thái sang "Ngừng hoạt động", chọn các dòng rồi đồng bộ. Plugin xử lý theo ô Khi sản phẩm ngừng kinh doanh (mặc định chuyển sang Bản nháp). Sản phẩm có biến thể thì sản phẩm cha chỉ ngừng khi mọi biến thể đều đã ngừng.

Ô Tự động tạo sản phẩm mới ở tab Webhook mặc định tắt, nên webhook chỉ cập nhật sản phẩm đã có. Bật ô đó, hoặc tạo tay: bấm Tải từ API KiotViet, lọc "Chưa liên kết (tạo mới)", chọn Tạo mới cho dòng đó rồi đồng bộ.

Hay gặp nhất là chưa bấm Lưu cài đặt trước khi kiểm tra, ô Retailer bị gõ cả .kiotviet.vn, hoặc Client Secret dán thiếu ký tự. License chưa kích hoạt cũng làm nút này báo lỗi. Bảng thông báo và cách xử lý ở bài Kết nối API KiotViet.

Đăng nhập KiotViet bằng tài khoản admin của chủ gian hàng, vào Thiết lập → Cửa hàng → Kết nối API, bấm Chỉnh sửa. Ở dòng Mã bảo mật bấm Tạo mã để lấy mã mới, dán vào ô Client Secret, bấm Lưu cài đặt rồi Kiểm tra kết nối.

Đổi tên miền thì cần hai việc: nhắn Zalo để chuyển license sang tên miền mới, và đăng ký lại webhook vì Link Webhook chứa tên miền cũ (xoá các dòng cũ ở tab Webhook rồi bấm Đăng ký tất cả webhook).

Chỉ chuyển hosting, giữ tên miền thì link không đổi. Mở tab Bắt đầu, bấm Kiểm tra lại, xem phần Kiểm tra môi trường có báo HTTPS, đường dẫn tĩnh hay WP-Cron không, rồi đối soát tồn kho như mục mất webhook ở trên.

Đơn lên KiotViet thành 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; trừ kho hay giữ hàng theo cách KiotViet xử lý phiếu. Xem bài Đồng bộ đơn hàng.

Ô Tự động đăng đơn mặc định tắt, nên đơn chỉ lên khi bạn bấm Post to KiotViet trong trang sửa đơn. Đã bật tự động thì kiểm quy tắc có khớp trạng thái và hình thức thanh toán của đơn không, và Chi nhánh mặc định đã chọn chưa. Đơn có một sản phẩm chưa liên kết KiotViet là cả đơn không lên. Dòng Auto Sync trong hộp KiotViet Order Sync của đơn cho biết kết quả tự động đăng.

Bộ địa chỉ trong website chưa đúng với cách bạn đang ghi địa chỉ. Vào tab Cài đặt chung, mục Cập nhật dữ liệu địa chỉ, chọn Mới nhất (2 cấp) hoặc v2.0 (3 cấp) rồi bấm Cập nhật database; xem bài Danh sách kiểm tra. Dùng 3 cấp thì bấm thêm Tải / Làm mới danh sách Location ở tab Đồng bộ đơn hàng. KiotViet không nhận một phường/xã thì plugin tự chuyển phần đó vào ô địa chỉ và gửi lại, đơn trên web có ghi chú.

Không. 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 (mã ngắn [woocommerce_checkout]). Trang thanh toán dạng block vẫn có ô chọn địa chỉ 2 cấp.