Đồng bộ tồn kho Nhanh.vn với website WooCommerce qua webhook

Chào anh em! Cảnh này chủ shop có cả cửa hàng lẫn website gặp hoài: khách đặt online đôi giày size 40, nhân viên ra kệ thì cửa hàng đã bán đôi cuối từ trưa, giờ phải gọi xin lỗi khách. Web báo còn hàng vì số tồn trên WooCommerce vẫn là số của hôm qua. Đồng bộ tồn kho Nhanh.vn với website là để số trên web đi theo số trên Nhanh.vn mỗi khi cửa hàng bán, nhập hay chuyển kho. Đọc xong, anh em biết web đang cộng tồn từ những kho nào và tự lần ra chỗ lệch khi số hai bên không khớp.

Plugin nhận webhook tồn kho nhắc tới trong bài là sản phẩm mình viết và đang bảo trì, chạy trên Open API của Nhanh.vn. Những gì bài nói về phía Nhanh.vn, như sự kiện Cập nhật tồn kho, số lần gửi lại hay mốc ngừng webhook v2, mình đối chiếu với tài liệu Open API và màn hình open.nhanh.vn vào tháng 10/2026, nên sau này Nhanh đổi giao diện thì chữ trên màn hình có thể khác. Các bước trong bài theo API v3. Website chưa kết nối thì làm theo bài kết nối Nhanh.vn với website trước.

Vì sao web báo còn hàng mà cửa hàng đã hết?

WooCommerce giữ một con số tồn riêng cho mỗi sản phẩm. Nhanh.vn giữ tồn theo từng kho, từng cửa hàng. Hai nơi, hai con số, không bên nào báo cho bên nào thì lệch chỉ là chuyện sớm muộn:

• Sửa tay cuối ngày thì trong ngày cửa hàng bán bao nhiêu, web không biết.
• Nhập Excel định kỳ thì đỡ hơn, nhưng giữa hai lần nhập vẫn có khoảng trống.
• Cộng nhầm kho là khi web cộng cả kho hàng lỗi, kho bảo hành vào số “còn bán”.

Cách bền là để Nhanh.vn chủ động báo cho web mỗi khi tồn đổi, tức là webhook, thay vì web đi hỏi theo giờ.

Đồng bộ tồn kho Nhanh.vn với website chạy thế nào?

1. Tồn của một sản phẩm trên Nhanh.vn thay đổi. Nhanh gửi sự kiện Cập nhật tồn kho (inventoryChange) tới đường dẫn webhook của website, kèm verify token ở header Authorization.
2. Plugin so verify token; sai token thì bỏ qua sự kiện.
3. Ô Chạy nền (Background Queue) ở tab Webhook bật sẵn: plugin lưu sự kiện vào hàng đợi, trả HTTP 200 cho Nhanh ngay, rồi xử lý sau bằng Action Scheduler (site không có thì dùng WP-Cron).
4. Lúc xử lý, plugin tính tồn theo các kho đã đồng bộ, chỉ ghi vào database khi số thật sự đổi, và tự bật “Quản lý kho” cho sản phẩm đơn, biến thể. Bước này không gọi thêm API của Nhanh.

Vì sao phải chạy nền: tài liệu Nhanh yêu cầu trả HTTP 200 nhanh; chậm hay lỗi thì Nhanh gửi lại tối đa 3 lần, tỉ lệ thành công thấp thì Nhanh có thể tắt webhook của app. Dòng giải thích trong plugin nói gọn: “Tránh timeout khi Nhanh.vn gửi nhiều webhook đồng thời”. Hàng đợi còn gộp sự kiện trùng: cùng một sản phẩm có nhiều sự kiện tồn kho hoặc sửa sản phẩm đang chờ thì bản cũ được đánh dấu “Đã gộp”, đỡ xử lý thừa.

⚠️ Số trên web đổi sau khi Nhanh gửi webhook và hàng đợi chạy tới lượt, nên nó đi theo nhịp đó chứ không có lịch đồng bộ định kỳ. Thêm hai điều kiện:

Có thể bạn cần

Plugin kết nối Nhanh.vn với WooCommerce: đồng bộ tồn kho, sản phẩm, đơn hàng

Plugin đồng bộ KiotViet cho WooCommerce: sản phẩm, tồn kho, đơn hàng

• Ô “Tồn kho” trong phần Cài đặt của tab Đồng bộ sản phẩm phải đang bật (mặc định bật), vì webhook tồn kho làm theo ô này.
• Sản phẩm trên web phải khớp với Nhanh, tức là mỗi sản phẩm, biến thể có ID Nhanh.vn, thì sự kiện mới biết ghi vào đâu. Theo tài liệu, Nhanh chỉ gửi webhook cho thay đổi phát sinh sau khi cấp quyền, nên tồn đang có được kéo về một lần lúc đồng bộ sản phẩm. Cách khớp theo SKU, ID và tạo mới mình viết ở bài đồng bộ sản phẩm Nhanh.vn về WooCommerce.

Tồn trên web được tính theo kho nào?

Công thức: tồn của một sản phẩm trên web bằng tổng số khả dụng (available) ở các kho đã đồng bộ về tab Kho hàng, trừ các kho tích “Không tính tồn kho”. Ví dụ shop có ba kho: Hoàn Kiếm còn 9, Quận 1 còn 5, kho hàng lỗi còn 4 và được tích “Không tính tồn kho”, thì web hiện 14.

• Ô Không tính tồn kho loại kho khỏi tổng, hợp với kho hàng lỗi, kho bảo hành, kho không bán online.
• Ô Ẩn khỏi danh sách chỉ ẩn kho khỏi hộp “Showroom còn hàng” ở trang sản phẩm, kho đó vẫn được cộng vào tổng.
• Hai mục Đặt làm kho chính và Khu vực bán hàng dùng khi tính phí ship và đăng đơn, không đổi cách cộng tồn.
• Plugin không có chế độ “chỉ lấy tồn một kho”, nên muốn web chỉ bán theo một kho thì tích “Không tính tồn kho” cho các kho còn lại.

⚠️ Đồng bộ kho trước, không thì tồn về 0

Công thức trên chỉ cộng kho có trong danh sách, nên thứ tự làm quan trọng:

1. Tab Kho hàng, bấm Đồng bộ kho từ Nhanh.vn về web trước khi đồng bộ sản phẩm.
2. Đếm số thẻ kho, so với số kho trên Nhanh.vn.
3. Tích “Không tính tồn kho” cho kho không bán online, đặt một kho chính, rồi lưu.
4. Mỗi lần Nhanh.vn thêm kho, cửa hàng mới: quay lại bấm đồng bộ kho.

🚨 Danh sách kho trống thì tồn mọi sản phẩm tính ra 0, web báo hết hàng hàng loạt. Kho mới mà chưa kéo về thì hàng ở kho đó không được cộng. Nếu lúc bấm đồng bộ API Nhanh lỗi, plugin giữ nguyên danh sách cũ. Xem thêm trang kho hàng trong tài liệu plugin.

Khi tồn trên web lệch Nhanh.vn, kiểm ở đâu?

Mở tab Webhook Queue (tab này hiện khi bật chạy nền). Trên cùng là các ô đếm Tất cả, Chờ xử lý, Đang xử lý, Hoàn thành, Đã gộp, Thất bại; ô tìm nhận ID sản phẩm, ID đơn hoặc chữ bất kỳ trong dữ liệu sự kiện. Gõ ID Nhanh của sản phẩm đang lệch rồi đi theo trạng thái:

• Gặp dòng Thất bại thì đọc cột Lỗi, rồi bấm Retry ở dòng đó hoặc Retry tất cả failed. Trước khi đánh dấu Thất bại, plugin đã tự thử lại tới 3 lần. Cột Lỗi ghi ERR_429 là lúc Nhanh đang giới hạn số lần gọi API (150 request mỗi 30 giây cho từng API; plugin tự giữ khoảng 120, gặp ERR_429 thì chờ hết thời gian khoá rồi gọi lại một lần), đợi một lúc rồi Retry.
• Sự kiện nằm ở Chờ xử lý mãi thì kiểm cron của website có chạy không, vì hàng đợi chạy bằng Action Scheduler hoặc WP-Cron. Dòng kẹt ở Đang xử lý quá 5 phút được tự trả về Chờ xử lý.
• Sự kiện đã Hoàn thành mà số vẫn lệch thường do kho chưa đồng bộ đủ, có kho tích nhầm “Không tính tồn kho”, hoặc sản phẩm chưa có ID Nhanh. Trong trang sửa sản phẩm, hộp Đồng bộ sản phẩm từ Nhanh.vn cho thấy Nhanh ID từng dòng (dòng thiếu hiện “Chưa có Nhanh ID”) và nút Đồng bộ để kéo lại riêng sản phẩm đó. Thêm một trường hợp: sự kiện về không kèm chi tiết từng kho thì plugin lấy tổng của Nhanh, lúc đó kho loại trừ không bị trừ.
• Không có sự kiện nào nghĩa là webhook không về. Kiểm app trên open.nhanh.vn: công tắc Bật webhooks còn bật (Nhanh có thể tắt khi tỉ lệ lỗi cao), đã tích Cập nhật tồn kho, version 3.0 khớp Version 3 trong plugin, verify token khớp và đã lưu bên plugin. Phía website thì xem tường lửa hay plugin bảo mật có chặn đường dẫn /wp-json/ không, và license còn hạn không (hết hạn thì đường dẫn webhook trả 404).

⚠️ Đừng dùng popup Đồng bộ tồn kho ở tab Đồng bộ sản phẩm để chữa lệch. Popup này (“Chỉ đồng bộ tồn kho cho các sản phẩm đã Mapping”) đọc bảng dữ liệu lưu tạm, không gọi API, nên có thể ghi số cũ đè lên số mới mà webhook vừa cập nhật. Chi tiết hàng đợi xem trang webhook.

Tự làm hay dùng plugin?

• Sửa tay hay nhập Excel tạm ổn với shop ít mã hàng, ít đơn online.
• Tự code nghĩa là tự viết phần nhận webhook, kiểm token, trả 200 nhanh, xếp hàng đợi và tính tồn theo kho. Làm được, nhưng anh em phải tự lo đủ các tình huống ở mục trên.
• Dùng plugin thì phần đó có sẵn: plugin nhận webhook Cập nhật tồn kho, đưa sự kiện vào hàng đợi chạy nền, tính tồn theo các kho đã đồng bộ, và có tab Webhook Queue để xem sự kiện nào thất bại rồi bấm Retry.

Ai muốn tự viết phần nhận sự kiện thì xem bài webhook Nhanh.vn, có code mẫu cho WordPress. Còn web WooCommerce cần chạy ngay thì plugin Nhanh.vn cho WooCommerce của mình đã có sẵn các phần trên, kèm đồng bộ sản phẩm và đăng đơn từ web lên Nhanh.vn.

Cách cài đồng bộ tồn kho trong plugin, từ đồng bộ kho tới theo dõi Webhook Queue và nút xem cửa hàng còn hàng, có trong video dưới.

Cho khách xem cửa hàng nào còn hàng

Tồn trên web là con số tổng. Muốn khách thấy từng cửa hàng còn bao nhiêu thì bật nút xem cửa hàng còn hàng ở tab Kho hàng (mặc định tắt): khách bấm, plugin hỏi trực tiếp Nhanh.vn và hiện hộp “Showroom còn hàng” kèm địa chỉ, nút “Chỉ đường”. Cách bật và các tuỳ chọn mình viết ở bài hiển thị tồn kho theo cửa hàng WooCommerce.

Mẫu website nổi bật của tôi

Mẫu website bán trái cây, thực phẩm tươi

Mẫu website cửa hàng kính mắt

Mẫu website bán vật tư kim khí

Mẫu website bánh kem mới nhất

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

Cửa hàng bán xong thì web đổi số ngay không?

Web đổi khi Nhanh gửi webhook Cập nhật tồn kho và hàng đợi xử lý tới sự kiện đó. Không có lịch quét định kỳ, nên cron của website chạy đều thì số theo kịp; cron đứng thì sự kiện nằm ở Chờ xử lý.

Khách mua trên web thì tồn trên Nhanh.vn có giảm không?

Plugin không đẩy số tồn từ web lên Nhanh.vn. Đơn web vào Nhanh.vn qua nút đăng đơn, đăng hàng loạt hoặc tự động; sau đó đơn đi theo quy trình xử lý của Nhanh.vn, và khi tồn trên Nhanh đổi thì webhook mang số mới về web.

Site đang dùng API v2 có đồng bộ tồn kho được không?

Được, webhook tồn kho chạy với cả v2 lẫn v3 (ở v2 là ô “Đồng bộ tồn kho” trong tab Đồng bộ thông tin sản phẩm). Nhưng open.nhanh.vn ghi webhook version 2.0 “Ngừng hỗ trợ sau 31-08-2026”, nên anh em nên chuyển sang v3 sớm.

Anh em đang gặp cảnh tồn lệch kiểu khác chưa có trong bài thì để lại bình luận, kèm ảnh tab Webhook Queue (che token, tên khách) để mình xem giúp nhé. Bấm đồng bộ kho xong rồi thì chúc ô Thất bại trong Webhook Queue của anh em cứ nằm yên ở số 0! 📦