Kết nối API KiotViet

Gian hàng KiotViet cần gói nào

Plugin dùng Public API của KiotViet bán lẻ, bán buôn. 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 khác thì hỏi KiotViet trước khi mua plugin. Plugin không kết nối được với KiotViet FnB (nhà hàng, quán cà phê) vì FnB dùng API riêng.

Xem video

Lấy Client ID và Mã bảo mật trên KiotViet

Làm bằng tài khoản admin của chủ gian hàng, vì chỉ tài khoản này thấy mã API. Các bước theo hướng dẫn Kết nối API của KiotViet:

1. Từ màn hình quản lý KiotViet, vào Thiết lập → Cửa hàng.
2. Ở menu trái chọn Kết nối API, bấm Chỉnh sửa.
3. Nhập số điện thoại trên hợp đồng, bấm Nhận mã xác thực, nhập mã rồi bấm Tiếp tục.
4. Ở dòng Mã bảo mật, bấm Tạo mã, đọc điều khoản rồi tích đồng ý.
5. Tích ô cho phép truy xuất thông tin khách hàng, hoá đơn, đặt hàng từ gian hàng, rồi bấm Lưu.
6. Chép lại Client ID và Mã bảo mật.

KiotViet đang chuyển sang giao diện quản lý mới trong năm 2026, vị trí menu có thể khác đôi chút. Không thấy mục Kết nối API thì liên hệ chăm sóc khách hàng của KiotViet.

Bạn không phải lo mã truy cập (token). KiotViet cấp token có hạn 24 giờ, plugin tự lấy và tự làm mới trước khi hết hạn.

Mở tab Cài đặt API

Trong trang quản trị WordPress, vào WooCommerce → Đồng bộ KiotViet. Lần đầu mở menu, plugin vào thẳng tab Cài đặt API.

1. Tab Cài đặt API là nơi khai thông tin kết nối. Các tab khác chỉ làm việc được sau khi tab này kết nối thành công.

Điền thông tin và lưu

1. Ô Retailer nhận đúng tên gian hàng, chỉ phần trước .kiotviet.vn, không kèm https://.
2. Ô Client ID nhận nguyên chuỗi chép từ KiotViet, không dư dấu cách ở đầu hay cuối.
3. Ô Client Secret nhận Mã bảo mật. Ô này che ký tự nên hãy dán, đừng gõ tay.
4. Ô Chi nhánh Tuỳ chọn chọn một hoặc nhiều chi nhánh để lấy tồn kho. Để trống thì tồn trên web là tổng của mọi chi nhánh; chọn nhiều thì cộng dồn các chi nhánh đã chọn. Nút làm mới bên cạnh tải lại danh sách chi nhánh, danh sách chỉ có sau khi đã lưu và kết nối được.
5. Nút Kiểm tra kết nối thử đọc một sản phẩm từ KiotViet, đồng thời tải danh sách bảng giá đang hoạt động để dùng ở mục Mapping Giá của tab Đồng bộ sản phẩm. Nút này chỉ đọc, không ghi gì lên KiotViet.
6. Nút Lưu cài đặt ghi lại thông tin. Kiểm tra kết nối dùng thông tin đã lưu chứ không đọc chữ đang gõ dở, nên phải lưu trước.
7. Nút Chuyển ID từ plugin cũ chỉ dùng khi website từng chạy plugin KiotViet Sync cũ. Cách làm ở mục Chuyển ID từ plugin KiotViet Sync cũ bên dưới.

Trong cùng biểu mẫu còn hai ô không đánh số. Ô Ghi log (mặc định tắt) ghi hoạt động của plugin vào WooCommerce → Trạng thái → Nhật ký, nguồn kiotviet-sync và kiotviet-webhook-log. Tắt ô này thì cả lỗi cũng không được ghi, nên bật lên khi cần dò lỗi. Ô Xóa cache (mặc định tắt) tự xoá bộ nhớ đệm trang của từng sản phẩm sau khi webhook cập nhật tồn kho hoặc giá; website dùng WP Rocket, LiteSpeed Cache, W3 Total Cache hay FlyingPress thì nên bật để khách không thấy số cũ.

Kết quả kiểm tra kết nối

Bấm Kiểm tra kết nối, sau vài giây hiện một hộp thoại:

Thấy hộp thoại này là xong bước 3.

Chuyển ID từ plugin KiotViet Sync cũ

Phần này chỉ dành cho website đang hoặc từng dùng plugin KiotViet Sync (đã đóng trên WordPress.org từ 04/11/2025). Plugin cũ lưu liên kết sản phẩm, danh mục trong hai bảng riêng kiotviet_sync_products và kiotviet_sync_categories. Bản 1.8.5 không xoá hai bảng này khi gỡ plugin, nên tắt hay xoá plugin cũ rồi vẫn chuyển được.

1. Kết nối API xong như trên, chưa đồng bộ sản phẩm.
2. Kéo xuống cuối tab Cài đặt API, khối Chuyển dữ liệu từ plugin cũ (kvsync), bấm Chuyển ID từ plugin cũ (số 7 trong ảnh ở mục Điền thông tin và lưu).
3. Plugin đọc từng lượt 100 dòng, gán KiotViet ID vào đúng sản phẩm, biến thể và danh mục đã có trên web. Dữ liệu của plugin cũ giữ nguyên; sản phẩm, danh mục đã có ID thì bỏ qua.
4. Sang tab Đồng bộ sản phẩm, bấm Tải từ API KiotViet, lọc Liên kết WooCommerce để xem sản phẩm nào đã liên kết, rồi đồng bộ thử vài sản phẩm.

Chuyển ID trước khi đồng bộ thì plugin cập nhật đúng sản phẩm cũ thay vì tạo thêm một bộ mới. Không có bảng của plugin cũ thì nút báo "Không tìm thấy bảng dữ liệu sản phẩm của plugin cũ (kiotviet_sync_products)".

Xem video

Khi báo lỗi thì xử lý thế nào

Kết nối xong thì sang Ánh xạ danh mục, hoặc thẳng Đồng bộ sản phẩm nếu không cần ánh xạ. Còn vướng thì xem Giải đáp thắc mắc.