Thử hình dung một shop mỹ phẩm có hai chi nhánh chạy KiotViet. Chiều thứ Bảy, chi nhánh Quận 3 bán hết lô kem chống nắng, chi nhánh Quận 1 còn hai hộp nhưng khách đã gọi giữ. Trang sản phẩm trên web WooCommerce vẫn báo còn 7 hộp, con số nhập tay từ đầu tuần. Tối đó web nhận ba đơn, sáng hôm sau nhân viên gọi xin lỗi cả ba khách. Đồng bộ tồn kho KiotViet với website là để con số trên web đi theo KiotViet mỗi khi tồn ở cửa hàng đổi. Bài này nói cơ chế bên dưới và các ô quyết định web hiện số nào, rồi chỉ cách dò khi số hai bên vẫn lệch.

Plugin nói tới trong bài là sản phẩm của mình, chạy bằng Public API của KiotViet. DevVN không có quan hệ đối tác nào với KiotViet. Thông tin về webhook mình lấy theo tài liệu Public API trên kiotviet.vn, kiểm lại tháng 10/2026. Màn hình quản lý của KiotViet đang được thay bằng giao diện 2026, chữ trên màn hình có thể đổi. Web chưa nối với KiotViet thì làm theo bài kết nối KiotViet với website trước.
🤔 Vì sao web còn bán món cửa hàng đã hết?
Trên WooCommerce, mỗi sản phẩm có ô số lượng tồn của riêng nó; KiotViet thì đếm tồn theo từng chi nhánh. Không có gì báo cho web mỗi lần KiotViet đổi số thì web đứng yên ở lần sửa tay sau cùng. Đã nối mà vẫn lệch thì xem mục dò lỗi ở cuối bài.
Để 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
- Azdigi: Giá rẻ thì dùng gói Pro Gold Hosting còn chất lượng hơn thì em khuyên dùng Business Hosting. Có điều kiện thì lên VPS nhé
- Tino hosting với mã giảm giá độc quyền lên tới 40%. Xem tại đây
- iNet
- Nước ngoài thì Vultr
⚙️ Đồng bộ tồn kho KiotViet về WooCommerce chạy thế nào?
Với plugin của mình, tồn kho về web theo hai đường: lần đồng bộ sản phẩm lúc mới cài, và webhook cho mọi thay đổi sau đó. Đường webhook đi như sau:
Cách chọn chi nhánh, các ô tồn kho, hàng đợi webhook và cách đối soát khi số lệch có trong video khoảng hai phút dưới đây.
- Quầy vừa bán một món, tồn ở chi nhánh đó đổi. KiotViet gửi sự kiện
stock.updatetới “Link Webhook” của web, kèm số tồn (OnHand) và số tạm giữ (Reserved) của chi nhánh. - Plugin cất tin vào hàng đợi rồi trả lời KiotViet. Ở chế độ “Mới (Queue + Dedup) – Khuyến nghị” (mặc định), nhiều tin của cùng một sản phẩm, một chi nhánh đang chờ thì chỉ tin về sau cùng được giữ lại.
- Action Scheduler lấy tin ra xử lý trong nền, mỗi lượt 10 dòng (“Batch size” mặc định), gặp lỗi thì chạy lại, mặc định 3 lần.
- Plugin tính tồn theo ô “Chi nhánh”. Chọn đúng một chi nhánh thì lấy số của chi nhánh đó. Để trống hoặc chọn nhiều thì gọi API lấy tồn đủ các chi nhánh của mặt hàng rồi mới cộng, vì tin
stock.updatekhông có số tổng. - Số mới ghi đè vào sản phẩm hoặc biến thể có KiotViet ID tương ứng. Bật ô “Xóa cache” thì plugin xoá luôn cache trang của sản phẩm đó.
Từ lúc bán ở quầy tới lúc web đổi số không có con số cố định, và mình không hứa con số nào. Nó phụ thuộc lúc KiotViet gửi tin (tài liệu Public API không ghi thời gian) và lúc hàng đợi tới lượt. Action Scheduler chạy theo WP-Cron, mà WP-Cron chỉ chạy khi có người vào web hoặc khi hosting gọi cron thật theo lịch; nửa đêm web vắng khách thì tin có thể nằm chờ tới lượt truy cập kế tiếp. Phía KiotViet thì đặt luật: mỗi tin phải được trả lời trong 5 giây, gặp mã 400, 401, 403, 404 hay 405 thì KiotViet thôi gửi. Vì vậy plugin chỉ ghi tin vào hàng đợi trong lúc KiotViet chờ, phần tính toán để làm sau.
🏬 Chọn chi nhánh để cộng tồn
Ô “Chi nhánh” ở tab “Cài đặt API” quyết định con số trên web. Để trống, cũng là mặc định, thì cộng tất cả chi nhánh. Chọn một hay nhiều chi nhánh thì chỉ cộng các chi nhánh đó. Ví dụ một mặt hàng còn 6 ở Chi nhánh Quận 1 và 2 ở Chi nhánh Quận 3: để trống thì web hiện 8, chọn riêng Quận 1 thì web hiện 6.
Web luôn hiện một con số tổng, không có tồn từng chi nhánh ở trang sản phẩm. Shop có kho hàng lỗi, kho bảo hành hay chi nhánh không giao online thì chọn tay các chi nhánh còn lại. Tin về mà không có chi nhánh nào khớp lựa chọn thì plugin giữ nguyên tồn cũ, không ghi 0 đè lên. Xem thêm trang cài đặt API.

🧮 Kho âm, hàng tạm giữ, số lẻ
Ba ô này nằm dưới ô “Tồn kho” trong khối “Tùy chọn đồng bộ” của tab “Đồng bộ sản phẩm”. Đổi xong bấm “Lưu tùy chọn”; muốn áp ngay cho cả web thì đối soát như bước 3 ở mục dưới.
Ô “Bỏ qua kho âm khi cộng dồn tồn kho nhiều chi nhánh” bật sẵn. Chi nhánh bán quá số trên hệ thống thì tồn bị âm. Quận 1 còn 6, Quận 3 âm 2: bật ô này web hiện 6, tắt thì web hiện 4. Ô chỉ có việc khi cộng từ hai chi nhánh trở lên; chọn đúng một chi nhánh mà chi nhánh đó âm thì webhook ghi đúng số âm ấy.
Ô “Trừ hàng tạm giữ (reserved) khỏi tồn kho” tắt sẵn. Bật thì tồn trên web bằng onHand - reserved; ghi chú của ô giải thích reserved là số đang tạm giữ, đang giao nhưng chưa xuất kho. Bảng tạm tải về trước lúc bật chưa có số reserved, nên bật xong bấm lại “Tải từ API KiotViet”.
Ô “Hỗ trợ tồn kho số lẻ (decimal)” tắt sẵn. Tắt thì tồn làm tròn xuống, 13,66 thành 13. Bật thì giữ phần lẻ cho hàng bán theo kg, lít, mét, nhưng ô này thêm filter woocommerce_stock_amount cho toàn site, đổi cách WooCommerce lưu số lượng của mọi sản phẩm. Web còn bán hàng không lấy từ KiotViet thì thử trên bản sao trước.

🔍 Khi số trên web lệch KiotViet: dò theo thứ tự này
Mở song song trang hàng hoá trên KiotViet và tab “Webhook” của plugin, rồi dò từ trên xuống.
1. Xem khối Thống kê của hàng đợi
Ở tab “Webhook”, phần “Cơ chế xử lý webhook (Queue)”, khối “Thống kê” đếm năm trạng thái “Chờ xử lý”, “Đang xử lý”, “Hoàn tất”, “Đã bỏ qua”, “Thất bại”; số tự làm mới mỗi 10 giây.
- 🔴 Ô “Thất bại” tăng là có tin vẫn lỗi sau các lần thử lại theo “Số lần retry tối đa” (mặc định 3). Bật “Ghi log” ở tab “Cài đặt API” (mặc định tắt, và lúc tắt thì lỗi cũng không được ghi), đọc lý do ở WooCommerce > Status > Logs, nguồn
kiotviet-webhook-logvàkiotviet-sync. Sửa xong nguyên nhân thì chọn các dòng thất bại, chọn hành động “Requeue (đưa về pending)” để chạy lại. - 🟡 Ô “Chờ xử lý” đứng yên nghĩa là hàng đợi không được chạy. Mở tab “Bắt đầu”, xem dòng WP-Cron và Action Scheduler trong “Kiểm tra môi trường”. Dòng dưới khối thống kê ghi “Không có batch nào đang chờ.” trong khi vẫn còn tin chờ thì bấm “Chạy ngay” để hẹn một lượt mới; lượt này vẫn đi qua Action Scheduler, nên cron phải chạy được.
- ⚪ Cửa hàng vừa bán mà các ô không nhúc nhích thì tin chưa về tới web. Sang bước 2.

2. Kiểm webhook còn được KiotViet gửi không
Ghi chú trong plugin nói rõ: KiotViet tự tắt webhook khi đường nhận trả mã 4xx hoặc phản hồi quá 5 giây. Plugin bảo mật, tường lửa của hosting hay Cloudflare mà chặn POST vào /wp-json/ thì KiotViet nhận 403; web để đường dẫn tĩnh mặc định kiểu ?p=123 thì nhận 404. Ô “Tự động đăng ký lại khi bị vô hiệu hóa” (bật sẵn) mặc định kiểm mỗi 1 giờ, thấy webhook của web bị tắt thì đăng ký lại. Mỗi sự kiện chỉ được đăng ký lại 3 lần trong 24 giờ; vượt số đó thì plugin gửi email cho admin kèm một thông báo trong trang quản trị.
Không muốn chờ lượt kiểm kế tiếp thì bấm “Kiểm tra ngay”; sửa xong nguyên nhân thì bấm “Xóa bộ đếm & cảnh báo”. Đổi tên miền thì webhook cũ vẫn trỏ địa chỉ cũ, mà phần tự đăng ký lại chỉ xét webhook trỏ về chính web này, nên phải đăng ký lại bằng tay. Từng ô của tab này có trong trang webhook của tài liệu plugin.
3. Mất webhook một lúc: đối soát bằng tay
Site sập, đang bảo trì, hay webhook bị tắt vài giờ thì thay đổi trong khoảng đó không về. Tài liệu Public API không hứa gửi bù, plugin cũng không có lịch tự quét lại, nên phải đối soát tay. Các nút nằm ở tab “Đồng bộ sản phẩm”:
- Làm mới bảng tạm bằng nút “Tải từ API KiotViet”: hàng hoá về kèm tồn kho từng chi nhánh.
- Bấm “Đồng bộ tồn kho”, chọn phạm vi “Tất cả sản phẩm”. Nút này chỉ cập nhật số tồn, mỗi lượt 50 sản phẩm.
- Chỉ vài sản phẩm lệch thì tích các dòng đó, bấm “Làm mới đã chọn từ API” (nút gọi KiotViet làm mới bảng tạm cho các dòng đã chọn), rồi “Đồng bộ tồn kho” với phạm vi “Các SP đã chọn”.
⚠️ “Đồng bộ tồn kho” lấy số từ bảng tạm, không gọi KiotViet. Bấm nó khi bảng tạm còn từ hôm trước là web nhận số của hôm trước, đè lên số webhook vừa ghi. Luôn làm mới bảng tạm trước. Trang đồng bộ sản phẩm trong tài liệu plugin nói thêm về từng nút.

4. Hàng đợi báo Hoàn tất mà một món vẫn lệch
- 🔗 Sản phẩm chưa có KiotViet ID thì webhook không biết ghi vào đâu. Trong bảng sản phẩm, cột “WooCommerce Product” ghi “Chưa đồng bộ” hay “Khớp SKU, chưa gán ID” là chưa liên kết xong. Khối “Sản phẩm trên web thiếu dữ liệu KiotViet”, lọc “Chỉ thiếu KiotViet ID” rồi bấm “Tải danh sách” để gom các món này; “Auto Mapping” ghép theo ID và SKU. Cách liên kết cho từng trường hợp nằm trong bài đồng bộ sản phẩm KiotViet về WooCommerce.
- ⛔ Sản phẩm đang bật “Không đồng bộ từ KiotViet” thì mọi cập nhật từ KiotViet bị chặn, kể cả webhook và nút “Đồng bộ tồn kho”. Ở danh sách sản phẩm, lọc “KiotViet: không đồng bộ” để xem món nào đang bật, bỏ chặn hàng loạt bằng “KiotViet: Đồng bộ lại”.
- 🏬 Số trên web là tổng các chi nhánh trong ô “Chi nhánh”, không phải số của riêng cửa hàng anh em đang đứng.
- ➖ Tồn của sản phẩm trên web ra số âm khi chọn đúng một chi nhánh và chi nhánh đó đang âm kho trên KiotViet.
- 🔑 License hết hạn thì plugin không gọi được KiotViet nữa. Gói 1 năm hết hạn thì gia hạn ở tab “License”.

5. Trang quản trị đúng, trang ngoài web vẫn số cũ
Đây là cache trang. Ở tab “Cài đặt API”, bật ô “Xóa cache” (mặc định tắt) để plugin xoá cache của từng sản phẩm sau khi webhook cập nhật tồn, hàng hoá hay giá. Ghi chú của ô liệt kê các plugin cache được hỗ trợ, trong đó có WP Rocket, W3 Total Cache, FlyingPress. Cache của hosting hay Cloudflare nằm ngoài danh sách thì đặt thời gian hết hạn ngắn cho trang sản phẩm. Đối soát tay xong ở bước 3 thì tự xoá cache một lần.
🧾 Đơn web và tồn kho trên KiotViet
Khách đặt trên web thì WooCommerce tự trừ tồn trên web theo cách của nó, khi đơn ở trạng thái Đang xử lý hoặc Tạm giữ. Plugin đẩy đơn lên KiotViet thành phiếu Đặt hàng, không tạo hoá đơn. Số tồn trên web cũng không được đẩy lên KiotViet. Tồn trên KiotViet đổi lúc nào là do KiotViet xử lý phiếu đó; mình không khẳng định thay KiotViet.
Hệ quả là lần kế tiếp KiotViet gửi stock.update cho mặt hàng đó, web nhận số của KiotViet và ghi đè số WooCommerce vừa trừ. Ví dụ giả định: web còn 5, khách đặt 1 nên web còn 4. Phiếu Đặt hàng chưa làm KiotViet đổi tồn, rồi quầy bán 1, KiotViet còn 4 và gửi về; web lại hiện 4 trong khi thực tế chỉ bán được 3.
Muốn biết gian hàng của mình chạy ra sao, đặt thử một đơn trên web, đăng lên KiotViet, rồi xem tồn và số tạm giữ của mặt hàng đó trước khi xuất hoá đơn. Số tạm giữ tăng theo phiếu thì bật ô trừ hàng tạm giữ ở trên; không tăng thì xử lý phiếu Đặt hàng sớm. Các cách đăng đơn nằm trong bài đẩy đơn hàng website về KiotViet.
🛠️ Tự viết hay dùng plugin đồng bộ tồn kho WooCommerce
Dev muốn tự viết phần nhận stock.update thì code mẫu cho WordPress có ở bài webhook KiotViet. Web WooCommerce cần chạy ngay thì plugin KiotViet cho WooCommerce mình viết đã có sẵn hàng đợi, phần tự đăng ký lại và các ô tồn kho ở trên; giá xem ở trang sản phẩm, có hỗ trợ cài đặt miễn phí.
❓ Câu hỏi thường gặp
Có đồng bộ tồn kho theo lịch, ví dụ mỗi đêm, không?
Không. Ngoài các nút bấm tay, số trên web chỉ đổi khi có webhook. Việc chạy định kỳ trong plugin chỉ gồm kiểm license, dọn hàng đợi và kiểm webhook bị KiotViet tắt.
Đồng bộ dữ liệu KiotViet khác như giá, tên hàng có đi cùng đường này không?
Có. Cùng hàng đợi đó xử lý product.update (tên, giá, ảnh…) và các sự kiện bảng giá, theo đúng các ô đã chọn ở tab “Đồng bộ sản phẩm”.
Trang sản phẩm có hiện tồn từng chi nhánh không?
Không. Web hiện một con số tổng của các chi nhánh đã chọn ở ô “Chi nhánh”.
Web của anh em đang lệch kiểu nào: vài món lẻ, cả loạt sau một đêm, hay hiện số âm? Kể dưới bình luận, kèm ảnh khối Thống kê ở tab Webhook nếu có (nhớ che Link Webhook), mình xem giúp.
Bài viết trong series
Kết nối WooCommerce với KiotViet
0/5đã đọc- 1 KiotViet Sync đã đóng: web WooCommerce đang dùng nên làm gì? Đang đọc Đã đọc
- 2 Kết nối KiotViet với website: 3 cách và 6 bước nối WooCommerce Đang đọc Đã đọc
- 3 Đồng bộ tồn kho KiotViet với website: cơ chế và cách xử lý khi lệch Đang đọc Đã đọc
- 4 Đồng bộ sản phẩm KiotViet về WooCommerce: biến thể, ảnh, bảng giá Đang đọc Đã đọc
- 5 Đồng bộ đơn hàng KiotViet: đẩy đơn website thành phiếu Đặt hàng Đang đọc Đã đọc





