Đồng bộ sản phẩm KiotViet về WooCommerce: biến thể, ảnh, bảng giá

Một mẫu áo trên KiotViet có 3 màu, 4 size là 12 mã hàng. Gõ tay lên WooCommerce thì phải tạo thuộc tính, tạo 12 biến thể, điền giá, tải ảnh, rồi sửa lại mỗi lần KiotViet đổi giá. Web đã có sẵn sản phẩm thì còn phải nối sao cho khỏi sinh bản trùng. Bài này đi qua cách đồng bộ sản phẩm KiotViet về WooCommerce bằng plugin của mình, theo thứ tự nên làm: ánh xạ danh mục, tải hàng hoá về bảng tạm, chọn Tạo mới hay Cập nhật, nối sản phẩm cũ. Tiếp theo là biến thể, ảnh, ô ghi đè, bảng giá, hàng ngừng kinh doanh và vài giới hạn cần biết trước khi chạy hàng loạt.

Đồng bộ sản phẩm KiotViet về WooCommerce: danh mục, biến thể, ảnh và bảng giá

Plugin trong bài do mình viết (bài theo bản 1.3.4), lấy dữ liệu qua Public API của KiotViet. Phần về KiotViet mình đối chiếu tài liệu chính thức, kiểm lại tháng 10/2026; KiotViet đang chuyển sang giao diện quản lý mới 2026 nên vài tên menu có thể lệch. Ảnh plugin chụp trên site thử nối gian hàng KiotViet thật, tên hàng, giá, tồn kho đã thay bằng dữ liệu mẫu.

📦 Đồng bộ sản phẩm KiotViet về WooCommerce lấy những gì?

Mỗi hàng hoá KiotViet thành một sản phẩm WooCommerce, SKU là mã hàng KiotViet. Trường kéo về gồm tên, mô tả đầy đủ (giữ HTML), ảnh đại diện, gallery, giá thường, giá khuyến mãi, tồn kho, trọng lượng, thuộc tính và biến thể. Thương hiệu và mã vạch có ô riêng, mặc định tắt. Dữ liệu đi một chiều từ KiotViet về web: thêm hàng, đổi giá, đổi ảnh thì làm trên KiotViet.

Để duy trì blog nên mình có làm aff cho 1 số bên hosting. Nhưng dù aff mình cũng chọn 1 số nhà cung cấp uy tín về chất lượng và support nên các bạn cứ yên tâm nhé.

Nếu có mua hosting mà có trong list dưới đây các bạn click vào link trước khi mua để ủng hộ mình nhé. Mình cảm ơn nhiều

Từ ánh xạ danh mục, Mapping Giá tới Auto Mapping và hàng ngừng kinh doanh, cả quy trình có trong video khoảng hai phút dưới đây.

Tồn kho cộng từ các chi nhánh chọn ở tab “Cài đặt API”, có ô bỏ qua kho âm, trừ hàng tạm giữ và tồn số lẻ. Phần này mình viết riêng ở bài đồng bộ tồn kho KiotViet.

Trước khi bắt đầu: license đã kích hoạt, tab “Cài đặt API” đã nhập “Retailer”, “Client ID”, “Client Secret” và bấm “Kiểm tra kết nối”. Nút này tải luôn danh sách bảng giá; thiếu bước này thì mục “Mapping Giá” không có bảng giá nào để chọn. Sao lưu database trước lượt đồng bộ lớn, vì không có nút hoàn tác. Thứ tự cài đặt cả plugin có ở bài kết nối KiotViet với website.

🗂️ Bước 1: ánh xạ danh mục trước

Ở tab “Ánh xạ danh mục”, bấm Tải danh mục Kiotviet. Mỗi nhóm hàng hiện một dòng, cột “Hành động” chọn “Tạo mới” (tạo danh mục cùng tên), “Ánh xạ có sẵn” (gắn vào danh mục đang có trên web) hoặc “Bỏ qua”. Nhiều dòng giống nhau thì dùng “Áp dụng hàng loạt:”. Bấm Lưu cấu hình, nút Đồng bộ danh mục ngay hiện ra, bấm tiếp để plugin tạo và gắn danh mục.

Tab Ánh xạ danh mục của plugin đồng bộ KiotViet cho WooCommerce: ô Tự động tạo danh mục cha, Tự động liên kết cha-con, Bỏ qua sản phẩm thuộc danh mục Skip, nút Tải danh mục Kiotviet và bảng chọn Ánh xạ có sẵn, Tạo mới, Bỏ qua cho từng nhóm hàng
Mỗi nhóm hàng chọn Ánh xạ có sẵn, Tạo mới hoặc Bỏ qua. Tên nhóm hàng là dữ liệu mẫu.

Ô “Bỏ qua sản phẩm thuộc danh mục Skip” bật sẵn: hàng thuộc nhóm “Bỏ qua” không lên web, kể cả qua webhook. Plugin không nhận webhook nhóm hàng, nên KiotViet có nhóm mới thì quay lại bấm Làm mới từ API. Danh mục anh em gắn tay trên web vẫn được giữ nhờ ô “Giữ danh mục thủ công”, bật sẵn ở tab “Đồng bộ sản phẩm”.

⬇️ Bước 2: tải hàng hoá về bảng tạm

Tab “Đồng bộ sản phẩm”, khối “Thống kê Cache”, bấm Tải từ API KiotViet. Plugin kéo hàng hoá theo trang 100 dòng, kèm tồn kho và bảng giá, cất vào bảng tạm {prefix}kiotviet_products. Sản phẩm trên web chưa bị đụng tới, nên anh em xem trước được mình sắp nhận gì.

Bảng “Danh sách sản phẩm” đọc từ bảng tạm, lọc được theo danh mục, loại sản phẩm, tồn kho, “Liên kết WooCommerce”. Bộ lọc “Trạng thái” để sẵn “Đang hoạt động”. Hàng bị xoá trên KiotViet không tự mất khỏi bảng tạm, nên trước mỗi lượt đồng bộ tay thì bấm tải lại.

✅ Bước 3: Tạo mới, Cập nhật hay Bỏ qua lần này

Mỗi dòng có cột “Hành động” với ba lựa chọn. Dòng đã liên kết được chọn sẵn “Cập nhật”. “Tạo mới” cho dòng đã có sản phẩm thì plugin bỏ qua, không tạo bản thứ hai. Cột “WooCommerce Product” cho biết dòng đang nối với sản phẩm nào.

Bảng Danh sách sản phẩm trong tab Đồng bộ sản phẩm: nút Đồng bộ đã chọn, Đồng bộ đã chọn trong nền, Auto Mapping, Auto Mapping theo tên, bộ lọc bên trái, cột Giá, Tồn kho, Loại, WooCommerce Product và ô Hành động Cập nhật, Tạo mới, Bỏ qua lần này
Chọn hành động từng dòng rồi bấm Đồng bộ đã chọn. Tên, giá, tồn kho là dữ liệu mẫu.

Có ba nút chạy. Đồng bộ đã chọn chạy trong trình duyệt, phải để tab mở tới khi xong. Đồng bộ đã chọn trong nền giao cho Action Scheduler, đóng tab vẫn chạy tiếp, có nút “Hủy đồng bộ”. Đồng bộ tất cả theo filter xử lý mọi dòng khớp bộ lọc, kể cả trang chưa mở tới.

Lần đầu, lọc lấy 3–5 sản phẩm, chạy thử, mở ngoài web xem tên, giá, ảnh, tồn kho. Đúng rồi mới chạy hàng loạt.

🔗 Web đã có sản phẩm: Auto Mapping

Web có sẵn sản phẩm thì nối trước, đừng vội Tạo mới hàng loạt. Auto Mapping nối theo KiotViet ID và SKU, chỉ lưu KiotViet ID (meta _kiotvietID), không ghi đè tên, giá, ảnh. Sản phẩm web chưa có SKU thì dùng Auto Mapping theo tên: plugin quét, chấm “Độ khớp” từng cặp với ngưỡng 60%; bấm “Bỏ chọn < 80%” để gạt cặp khớp thấp rồi “Lưu mapping đã chọn”. Nối nhầm thì bấm “Huỷ liên kết” ở dòng đó, link này chỉ xoá KiotViet ID.

Web từng chạy KiotViet Sync, plugin cũ của KiotViet nay đã đóng, thì nút “Chuyển ID từ plugin cũ” ở tab “Cài đặt API” lấy lại liên kết sản phẩm, danh mục mà plugin cũ để lại. Thứ tự chuyển có ở bài KiotViet Sync đã đóng.

👕 Biến thể, ảnh, đường dẫn

Áo nhiều màu, nhiều size trên KiotViet thường là hàng hoá cùng loại, mỗi mẫu một mã hàng. Plugin gom nhóm đó thành một sản phẩm biến thể: thuộc tính toàn cục pa_…, mỗi biến thể mang SKU là mã hàng của nó, sản phẩm cha để trống SKU. Ảnh đầu của hàng hoá làm ảnh đại diện, các ảnh sau vào gallery. Plugin nhớ đường dẫn gốc từng ảnh nên chạy nhiều lần không tải trùng; ảnh cũ trong Media không bị xoá. Ảnh phụ của biến thể lưu vào meta _ux_additional_variation_images, chỉ hiện với theme đọc meta này, ví dụ Flatsome.

Ô “Đường dẫn sản phẩm mới” (từ 1.3.3) đặt slug theo tên (mặc định), chỉ mã hàng, hoặc mã hàng cộng chuỗi ngẫu nhiên. Tên hàng tiếng Nhật, tiếng Trung thì chọn theo mã hàng. Ô này chỉ áp cho sản phẩm tạo mới.

✍️ Ô Ghi đè: giữ mô tả đã viết trên web

Mỗi trường có ô con “Ghi đè … nếu sản phẩm đã có …”. Tắt thì plugin chỉ điền khi trường đó trên web đang trống. Mặc định, tên và tồn kho được ghi đè; mô tả đầy đủ, ảnh đại diện, gallery thì không. Bài mô tả anh em viết cho SEO trên web vì vậy không bị KiotViet thay. Mã vạch ghi vào ô GTIN (chỉ sản phẩm đơn), thương hiệu vào Brands của WooCommerce.

Khối Tùy chọn đồng bộ trong tab Đồng bộ sản phẩm: ô Tên sản phẩm, Đồng bộ giá, Ảnh đại diện, Ảnh gallery, Mô tả đầy đủ, Tồn kho kèm ô Ghi đè, Mã vạch, Thương hiệu, xử lý sản phẩm ngừng kinh doanh, Đường dẫn sản phẩm mới và Mapping Giá
Mỗi trường một ô bật, kèm ô Ghi đè riêng. Ảnh chụp cấu hình site thử, vài ô khác mặc định lúc cài.

💰 Đồng bộ giá KiotViet theo bảng giá

Mục “Mapping Giá” có hai ô. “Giá thường:” lấy “Giá niêm yết (Base Price)” hoặc một bảng giá KiotViet. “Giá khuyến mãi:” lấy “– Không dùng –” (mặc định), giá niêm yết, hoặc một bảng giá. Mỗi ô đúng một nguồn; plugin không có giá theo nhóm khách hay theo chi nhánh. Giá khuyến mãi chỉ được ghi khi lớn hơn 0 và thấp hơn giá thường.

Ví dụ shop có bảng giá “Giá online” và bảng “Khuyến mãi tháng 11”. Chọn bảng đầu cho giá thường, bảng sau cho giá khuyến mãi: hàng có giá ở cả hai bảng sẽ hiện giá gạch ngang trên web. Bảng làm giá thường nên có đủ hàng đang bán online, và đồng bộ xong nhớ mở vài sản phẩm kiểm giá.

Mục Mapping Giá của plugin: Giá thường chọn Giá niêm yết (Base Price), Giá khuyến mãi chọn Bảng giá khuyến mãi; phía trên là các ô Ghi đè tồn kho, Bỏ qua kho âm, Hỗ trợ tồn kho số lẻ, Trừ hàng tạm giữ
Giá thường lấy giá niêm yết, giá khuyến mãi lấy từ một bảng giá. Tên bảng giá là dữ liệu mẫu.

⚠️ Giá khuyến mãi anh em tự gõ trên WooCommerce sẽ mất ở lần đồng bộ kế tiếp nếu ô “Giá khuyến mãi:” đang là “– Không dùng –“. Muốn chạy sale trên web, đặt giá sale vào một bảng giá KiotViet rồi chọn bảng đó cho ô này.

Sau lần đầu, giá đổi trên KiotViet về web qua webhook. Plugin chỉ cập nhật khi bảng giá vừa đổi đúng là bảng đang chọn ở “Mapping Giá”.

🛑 Hàng ngừng kinh doanh, sản phẩm ẩn, hàng bị xoá

Hàng ngừng kinh doanh trên KiotViet được xử lý theo ô “Khi sản phẩm ngừng kinh doanh”, mặc định “Chuyển sang Bản nháp (Draft) – khuyên dùng”; các lựa chọn khác gồm riêng tư, đặt hết hàng, ẩn khỏi Shop, thùng rác. Hàng kinh doanh lại thì ô “Tự khôi phục khi sản phẩm hoạt động lại” (bật sẵn) đưa sản phẩm về.

⚠️ Mỗi lần KiotViet cập nhật một sản phẩm, qua đồng bộ tay hay webhook, plugin đưa sản phẩm đó về “Đã xuất bản” và hiện lại trong cửa hàng. Sản phẩm anh em tự chuyển nháp trên web mà KiotViet vẫn bán sẽ hiện lại ở lần cập nhật tới. Muốn ẩn lâu dài thì bật “Không đồng bộ từ KiotViet”.

🚨 Xoá hàng hoá trên KiotViet thì nặng hơn. Nút “Đăng ký tất cả webhook” có đăng ký sự kiện product.delete; nhận sự kiện này, plugin xoá vĩnh viễn sản phẩm hoặc biến thể trên web, không qua thùng rác. Hàng không bán nữa thì cho ngừng kinh doanh thay vì xoá. Sản phẩm cần giữ trên web thì bật “Không đồng bộ từ KiotViet”, hoặc bấm “Xóa” ở dòng product.delete trong tab “Webhook” (bấm lại “Đăng ký tất cả webhook” về sau thì sự kiện này được đăng ký lại).

🙅 Không đồng bộ từ KiotViet cho sản phẩm tự quản

Từ bản 1.3.3, trang sửa sản phẩm có ô Không đồng bộ từ KiotViet ở tab kho hàng (WooCommerce tiếng Việt ghi “Kiểm kê kho hàng”). Tích vào, sản phẩm bỏ qua mọi cập nhật từ KiotViet: đồng bộ tay, đồng bộ nền, webhook, kể cả webhook xoá. Bật ở sản phẩm cha thì áp cho cả nhóm biến thể. Nhiều sản phẩm thì dùng hành động hàng loạt “KiotViet: Không đồng bộ” ở danh sách sản phẩm.

Tab Kiểm kê kho hàng trong trang sửa sản phẩm WooCommerce: ô SKU, KiotViet ID, ô Không đồng bộ từ KiotViet đã tích kèm ghi chú bỏ qua mọi cập nhật từ KiotViet, ô GTIN và số lượng tồn kho
Sản phẩm tích ô này thôi nhận cập nhật, đơn hàng vẫn đẩy lên KiotViet. SKU, mã vạch là dữ liệu mẫu.

🆕 Hàng mới trên KiotViet có tự lên web?

Mặc định là không. Ô “Tự động tạo sản phẩm mới” ở tab “Webhook” đang tắt, nên webhook chỉ cập nhật sản phẩm đã có. Bật ô này thì hàng mới trên KiotViet tự thành sản phẩm trên web. Để tắt hợp với shop muốn xem hàng trước khi đăng: mỗi đợt hàng mới, tải lại bảng tạm, lọc “Liên kết WooCommerce” lấy dòng chưa liên kết, chọn “Tạo mới”. Hàng đợi webhook có giải thích ở trang webhook trong tài liệu plugin.

🚧 Giới hạn nên biết

  • ⛔ Sửa sản phẩm, giá, tồn trên WooCommerce không đẩy ngược lên KiotViet.
  • 🧾 Không lấy giá vốn, đơn vị tính, kích thước, mô tả ngắn.
  • ⏰ Không có lịch đồng bộ định kỳ. Ngoài thao tác tay chỉ có webhook, xử lý nền theo WP-Cron, nên thời gian về web tuỳ lúc KiotViet gửi và cron của hosting.
  • 🏪 Chỉ dùng cho KiotViet bán lẻ, bán buôn, không hỗ trợ KiotViet FnB.

🔧 Lỗi hay gặp

Dấu hiệuCách xử lý
“Mapping Giá” trốngBấm “Kiểm tra kết nối” ở tab “Cài đặt API”.
Giá sale trên web tự mất“Giá khuyến mãi:” đang để “– Không dùng –“.
Mô tả không đổi theo KiotVietÔ ghi đè mô tả đang tắt, đúng mặc định.
Sản phẩm nháp tự hiện lạiBật “Không đồng bộ từ KiotViet” cho sản phẩm đó.
Không thấy hàng trong bảngXem bộ lọc “Trạng thái”, nhóm hàng bị “Bỏ qua”, hoặc tải lại bảng tạm.

Từng nút của hai tab có ảnh và giải thích ở trang ánh xạ danh mục và đồng bộ sản phẩm trong tài liệu plugin. Sản phẩm phải liên kết xong thì đơn web mới lên KiotViet được. Phần đẩy đơn mình viết ở bài đẩy đơn hàng website về KiotViet.

Muốn bỏ khâu nhập hàng hai nơi thì xem plugin đồng bộ KiotViet cho WooCommerce. Giá xem ở trang sản phẩm, mua xong mình hỗ trợ cài đặt miễn phí.

❓ Câu hỏi thường gặp

Sửa giá trên web có đẩy ngược lên KiotViet không?

Không. Giá sửa tay trên WooCommerce giữ tới lần đồng bộ sau rồi bị thay bằng giá KiotViet, trừ sản phẩm đã bật “Không đồng bộ từ KiotViet”.

Chạy đồng bộ nhiều lần có sinh sản phẩm trùng?

Dòng đã liên kết chỉ được cập nhật, “Tạo mới” cho dòng đã có sản phẩm thì bị bỏ qua. Web có sẵn sản phẩm chưa nối thì chạy “Auto Mapping” trước lượt Tạo mới hàng loạt.

Shop anh em có bao nhiêu mã hàng trên KiotViet, web đã có sẵn sản phẩm hay làm từ đầu? Kể dưới bình luận, mình góp ý nên Auto Mapping hay Tạo mới cho đỡ việc. Nhớ che Client ID, Client Secret trước khi dán ảnh nhé.

Bài viết trong series

Kết nối WooCommerce với KiotViet

0/5đã đọc
  1. 1 KiotViet Sync đã đóng: web WooCommerce đang dùng nên làm gì? Đang đọc Đã đọc
  2. 2 Kết nối KiotViet với website: 3 cách và 6 bước nối WooCommerce Đang đọc Đã đọc
  3. 3 Đồng bộ tồn kho KiotViet với website: cơ chế và cách xử lý khi lệch Đang đọc Đã đọc
  4. 4 Đồng bộ sản phẩm KiotViet về WooCommerce: biến thể, ảnh, bảng giá Đang đọc Đã đọc
  5. 5 Đồng bộ đơn hàng KiotViet: đẩy đơn website thành phiếu Đặt hàng Đang đọc Đã đọc
Sản phẩm nổi bật của Toản
x