Đồng bộ sản phẩm Nhanh.vn về website WooCommerce trong 3 bước

Chào anh em! Chuỗi cửa hàng bán bằng Nhanh.vn POS mà có thêm website WooCommerce thì thường phải nhập sản phẩm hai lần: tạo mã trên Nhanh để bán tại quầy, rồi lại gõ tên, giá, ảnh, mô tả lên web. Đổi giá trên Nhanh mà quên sửa web là khách thấy giá cũ. Làm theo bài này, anh em sẽ đồng bộ sản phẩm Nhanh.vn về website WooCommerce một lượt cho cả danh mục, biến thể, giá, ảnh, mô tả, rồi để webhook giữ dữ liệu hai bên khớp nhau về sau.

Plugin dùng để kéo sản phẩm trong bài này do mình viết và bảo trì, lấy dữ liệu qua Open API của Nhanh.vn. Những gì bài nói về phía Nhanh.vn, như sự kiện webhook hay giới hạn request, mình đối chiếu với tài liệu chính thức ở developers.nhanh.group và giao diện open.nhanh.vn vào tháng 10/2026. Nhanh đổi giao diện thì tên nút có thể lệch đôi chút, anh em cứ bám theo thứ tự các bước. Ảnh plugin chụp trên site demo, sản phẩm và khách trong ảnh là dữ liệu mẫu.

Đồng bộ sản phẩm Nhanh.vn về website gồm những gì?

• Danh mục được kéo nguyên cây từ Nhanh về WooCommerce, giữ quan hệ cha con.
• Sản phẩm được nối với sản phẩm đã có trên web hoặc tạo mới, còn biến thể thành thuộc tính của WooCommerce.
• Giá lấy cả giá bán và giá cũ.
• Ảnh lấy cả ảnh đại diện và ảnh gallery.
• Mô tả đầy đủ và mô tả ngắn giữ nguyên định dạng HTML.
• Trọng lượng, kích thước trên Nhanh lưu theo gram và cm, plugin đổi sang đơn vị shop đang cài trong WooCommerce.
• Tồn kho trên web là tổng tồn của các kho đã đồng bộ về.

Sản phẩm chỉ đồng bộ một chiều, từ Nhanh.vn về website. Plugin không đẩy sản phẩm từ WooCommerce lên Nhanh và không xoá sản phẩm nào trên web. Nên coi Nhanh.vn là nơi gốc: thêm sản phẩm, đổi giá, đổi ảnh thì làm trên Nhanh, web nhận theo.

Chuẩn bị trước khi đồng bộ

• Kết nối xong tài khoản Nhanh.vn bằng API v3, vì tab đồng bộ chỉ hiện khi plugin đã có accessToken. Từng bước có ở bài kết nối Nhanh.vn với website và trang kết nối API.
• Đồng bộ kho trước bằng nút “Đồng bộ kho từ Nhanh.vn về web” trong tab “Kho hàng”. Xem trang kho hàng.
• Sao lưu website trước lần đồng bộ lớn.

⚠️ Tồn kho trên web bằng tổng tồn của các kho có trong danh sách đã đồng bộ, trừ kho được tick “Không tính tồn kho”. Chưa bấm đồng bộ kho thì danh sách trống và tồn về 0; Nhanh thêm kho mới thì nhớ bấm đồng bộ lại, không thì kho mới không được cộng. Cơ chế tồn kho theo từng kho mình viết riêng ở bài đồng bộ tồn kho Nhanh.vn.

3 bước trong tab Đồng bộ sản phẩm: Cài đặt, Bước 1, Bước 2

Với API v3, plugin kết nối Nhanh.vn với WooCommerce có tab “Đồng bộ sản phẩm” chia thành 3 phần làm lần lượt: Cài đặt, rồi Bước 1 (Đồng bộ danh mục), rồi Bước 2 (Đồng bộ sản phẩm). Lần mở tab đầu, bấm “Khởi tạo bảng ngay” để plugin tạo bảng riêng lưu danh mục và sản phẩm tải từ Nhanh. Chi tiết từng nút ở trang đồng bộ sản phẩm.

Ba phần này và phần cài đồng bộ khách hàng có trong video khoảng một phút rưỡi dưới đây.

Cài đặt: chọn trường nào lấy từ Nhanh.vn

• Mặc định plugin bật hết các trường: giá (giá bán và giá cũ), ảnh đại diện, ảnh gallery, mô tả đầy đủ, mô tả ngắn, trọng lượng, kích thước, tồn kho. Bỏ tick trường nào thì trường đó trên web giữ nguyên.
• Ô “Ghi đè” mặc định tắt (riêng tồn kho bật). Khi tắt, mô tả chỉ được ghi vào sản phẩm đang để trống mô tả, nên mô tả anh em đã viết trên web không bị thay. Bật ghi đè thì nội dung trên Nhanh thay nội dung trên web.
• Mô tả giữ HTML; ảnh chèn trong mô tả vẫn trỏ về đường dẫn gốc của Nhanh, không tải về thư viện media.
• Biến thể không có thuộc tính có ba cách xử lý: “tạo biến thể với thuộc tính tự sinh”, “tạo sản phẩm đơn”, hoặc “lấy thông tin từ sản phẩm cha”.

Bước 1: Đồng bộ danh mục

Bấm “Tải danh sách danh mục”, plugin lấy đủ mọi trang danh mục trên Nhanh; sau này Nhanh có thay đổi thì bấm “Làm mới từ API”. Có ba thao tác cho cả danh sách: Mapping tự động (khớp theo liên kết đã lưu, rồi theo tên danh mục), Tạo mới tất cả (tạo danh mục WooCommerce, giữ quan hệ cha con) và Bỏ qua tất cả. Làm bước này trước để khi nối sản phẩm, danh mục bên web đã có chỗ gắn.

Bước 2: Mapping, Tạo mới hay Bỏ qua từng sản phẩm

Bấm “Load từ API Nhanh.vn”: plugin tải 100 sản phẩm mỗi trang, chưa hết thì có nút “Chạy tiếp” và nhớ vị trí trong 1 ngày. Có bộ lọc theo danh mục và trạng thái; mặc định plugin không tải sản phẩm đang ở trạng thái “Hết hàng”. Mỗi dòng hiện ảnh, tên, SKU, ID, tồn trên Nhanh, và anh em chọn một trong ba:

• Chọn Mapping để nối với sản phẩm đã có trên web. Cột “Sản phẩm WooCommerce” cho biết đang nối với sản phẩm nào, bấm “Đổi” để chọn lại. Liên kết được lưu bằng ID Nhanh trên sản phẩm (và từng biến thể). Mapping cập nhật giá, ảnh, mô tả, trọng lượng, kích thước, tồn kho theo phần Cài đặt; danh mục chỉ được thêm, không gỡ danh mục cũ. Tên và SKU trên web giữ nguyên.
• Chọn Tạo mới thì plugin tạo sản phẩm mới trên web. Trước khi tạo, plugin kiểm ID Nhanh rồi SKU để tránh trùng. Tên và SKU lấy từ Nhanh lúc tạo; biến thể được tạo thành thuộc tính toàn cục của WooCommerce (dạng pa_…).
• Chọn Bỏ qua thì dòng đó không được đồng bộ. Sản phẩm đã nối mà chọn Bỏ qua thì plugin chỉ gỡ ID Nhanh, không xoá sản phẩm.

⚠️ Sản phẩm tạo mới được đăng ngay, kể cả sản phẩm đang “Ngừng bán” bên Nhanh, vì plugin không đồng bộ trạng thái sản phẩm. Lọc trạng thái cho kỹ trước khi bấm tạo hàng loạt.

Ít sản phẩm thì bấm “Bắt đầu đồng bộ”, “Đồng bộ tất cả Mapping” hoặc “Tạo mới tất cả”, plugin chạy lần lượt ngay trên trang. Vài nghìn sản phẩm thì dùng nhóm “Đồng bộ trong nền” (Đã thay đổi / Tất cả Mapping / Tất cả Tạo mới), có nút “Dừng & xoá tiến trình”.

Đồng bộ lớn gọi API nhiều, nên plugin tự điều tiết: giữ khoảng 120 trên giới hạn 150 request mỗi 30 giây của Nhanh cho từng endpoint; Nhanh vẫn báo ERR_429 thì chờ hết thời gian khoá rồi gọi lại một lần.

Ảnh sản phẩm: chỉ tải lại khi Nhanh đổi ảnh

Plugin nhận diện ảnh theo đường dẫn đầy đủ, kể cả tham số phiên bản ?v=: ảnh đổi phiên bản thì tải bản mới, không đổi thì dùng lại ảnh đã có, nên chạy đồng bộ nhiều lần không làm thư viện media đầy ảnh trùng. Ảnh đại diện lặp trong gallery được tự bỏ; biến thể chỉ có ảnh đại diện. Nhanh đổi ảnh thì ảnh cũ trên web không bị xoá, muốn dọn thư viện thì xoá tay.

Sau lần đồng bộ đầu, dữ liệu giữ khớp bằng cách nào?

Plugin không có lịch đồng bộ sản phẩm định kỳ; thay đổi về sau đi bằng webhook. Trong app ở open.nhanh.vn, chọn webhook version 3.0, tick Sửa sản phẩm, Xóa sản phẩm, Cập nhật tồn kho. Plugin nhận sự kiện, lưu vào hàng đợi, trả 200 cho Nhanh rồi xử lý chạy nền:

• Sự kiện Sửa sản phẩm cập nhật giá, tồn, ảnh, mô tả, trọng lượng, kích thước theo các ô đang bật ở phần Cài đặt.
• Sự kiện Xóa sản phẩm chỉ gỡ ID Nhanh khỏi sản phẩm trên web, không xoá, không ẩn.
• Thêm sản phẩm mới trên Nhanh thì web không tự tạo theo; vào Bước 2 tải lại danh sách và chọn Tạo mới cho sản phẩm đó.

Tốc độ cập nhật phụ thuộc lúc Nhanh gửi webhook và lúc hàng đợi trên web chạy. Muốn biết sự kiện đã xử lý chưa thì mở trang Webhook Queue: có ô đếm Chờ xử lý / Hoàn thành / Thất bại, nút Retry cho mục lỗi; sự kiện trùng của cùng một sản phẩm được gộp lại. Cách khai webhook có ở bài webhook Nhanh.vn và trang webhook.

Nối hoặc cập nhật từng sản phẩm ngay trong trang sửa sản phẩm

Trang sửa sản phẩm có hộp “Đồng bộ sản phẩm từ Nhanh.vn” (API v3): mỗi dòng có Woo ID, tên, SKU, ô nhập Nhanh ID, tồn trên web và nút “Đồng bộ”, kèm nút “Đồng bộ toàn bộ”. Dòng chưa nối hiện “Chưa có Nhanh ID”; nhập ID rồi bấm “Cập nhật” sản phẩm là lưu. Tiện khi chỉ cần sửa vài sản phẩm lẻ.

Giới hạn cần biết trước

• Đồng bộ chỉ đi một chiều nên sửa giá, tồn trên web không đẩy lên Nhanh; lần đồng bộ sau lấy lại số của Nhanh.
• Xoá sản phẩm trên Nhanh thì sản phẩm trên web chỉ mất liên kết, không bị xoá theo.
• Plugin không đồng bộ trạng thái sản phẩm, nên sản phẩm “Ngừng bán” trên Nhanh không tự ẩn trên web.
• Tên và SKU chỉ lấy lúc tạo mới; Mapping, webhook, hộp trong trang sửa sản phẩm đều không đổi tên/SKU.
• Sản phẩm vừa tạo mới cần kiểm lại danh mục trong WooCommerce trước khi mở bán; chạy Mapping cho sản phẩm đó là danh mục theo Nhanh được thêm vào.
• Nút “Reset toàn bộ Nhanh ID” xoá mọi liên kết, kể cả liên kết mà phần đăng đơn lên Nhanh.vn cần để gửi đúng sản phẩm. Chỉ bấm khi muốn làm lại từ đầu.

Đồng bộ khách hàng Nhanh.vn với tài khoản trên web

Từ bản 1.6.0 có thêm tab “Đồng bộ khách hàng”. Tab này chỉ hiện khi dùng API v3, chế độ đồng bộ mặc định là Tắt; lần đầu bấm “Khởi tạo bảng ngay”. Chi tiết ở trang đồng bộ khách hàng.

Chọn chế độ và trường cần map

• Ô Chế độ đồng bộ có bốn lựa chọn: “Tắt” (mặc định), “Chỉ đẩy WP → Nhanh.vn”, “Chỉ kéo Nhanh.vn → WP” và “Hai chiều”.
• Phần Mapping field ghép trường mobile của Nhanh với billing_phone, name với họ và tên, email với billing_email, address với billing_address_1, gender với billing_gender, và anh em sửa lại được các cặp này.
• Ô Đơn hàng khách (guest) mặc định tắt.

Đẩy lên Nhanh.vn và kéo về web

• Việc đẩy khách từ WP lên Nhanh chạy khi khách đăng ký tài khoản, sửa hồ sơ hoặc đặt hàng. Khách phải có tên và số điện thoại Việt Nam hợp lệ mới được gửi; địa chỉ gửi theo mã của Nhanh, nhận cả 2 cấp lẫn 3 cấp. Nút “Đẩy toàn bộ tài khoản WP lên Nhanh.vn” chạy nền, tối đa 2.000 tài khoản, có nút dừng. Lúc khách đặt hàng, việc đẩy chạy ngay trong lượt đặt, nên Nhanh phản hồi chậm thì bước đặt hàng chậm theo.
• Kéo khách từ Nhanh về WP không theo thời gian thực, vì Nhanh chưa có webhook cho khách hàng. Anh em bấm tay hoặc đặt lịch “Mỗi giờ” / “Mỗi ngày” (mặc định chỉ thủ công). Mỗi lần chỉ kéo phần thay đổi từ lần trước. Kéo về không ghi tỉnh/huyện/xã và không đổi email đăng nhập của tài khoản.

Khách không khớp thì chờ admin duyệt

Plugin khớp khách theo liên kết đã lưu, rồi số điện thoại, rồi email; ở chế độ hai chiều, bản cập nhật mới hơn được giữ. Plugin không tự tạo tài khoản WordPress: khách không khớp nằm ở trạng thái “Chờ duyệt” trong bảng mapping, admin chọn “Tạo tài khoản WP mới”, liên kết với một tài khoản có sẵn, hoặc “Bỏ qua khách này”. Tài khoản tạo mới có tên đăng nhập nhanh_<SĐT>, vai trò khách hàng, không gửi email cho khách; khách thiếu email thì dùng địa chỉ tạm dạng <SĐT>@placeholder.local.

Site cũ đang dùng API v2

Với Version 2, tab tên là “Đồng bộ thông tin sản phẩm”: chỉ cập nhật sản phẩm đã khớp (theo ID Nhanh, rồi SKU), không tạo mới, mặc định chỉ bật tồn kho; không có đồng bộ khách hàng. Trên open.nhanh.vn, Nhanh ghi webhook “version 2.0 (Ngừng hỗ trợ sau 31-08-2026)”, nên mình khuyên chuyển sang v3; nhớ cấp quyền lại để lấy token v3, vì token v2 gọi API v3 bị báo ERR_INVALID_VERSION.

Lỗi hay gặp khi đồng bộ

• Không thấy tab “Đồng bộ sản phẩm” thường do chưa có accessToken, đang chọn Version 2, hoặc license chưa kích hoạt (các tab tự chuyển về tab License).
• Tồn kho về 0 sau khi đồng bộ thường do chưa đồng bộ kho, hoặc hàng nằm ở kho mới chưa kéo về.
• Thiếu sản phẩm trong danh sách tải về khi sản phẩm đang “Hết hàng” (mặc định không tải) hoặc bộ lọc danh mục, trạng thái đang hẹp.
• Sửa trên Nhanh mà web không đổi thường do chưa tick sự kiện Sửa sản phẩm trong app, chưa bấm lưu verify token ở tab Nhanh.vn, hoặc mục trong Webhook Queue đang Thất bại (bấm Retry).
• Mô tả không cập nhật khi sản phẩm trên web đã có mô tả và ô Ghi đè đang tắt. Plugin chủ ý làm vậy, không phải lỗi.

Ngoài đồng bộ sản phẩm, plugin Nhanh.vn cho WooCommerce còn đăng đơn, lấy phí ship theo hãng trên Nhanh, hiện cửa hàng còn hàng; giá xem ở trang sản phẩm.

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

Có phải chạy lại đồng bộ mỗi ngày không?

Không có lịch tự chạy, và thường cũng không cần: sửa giá, ảnh, tồn trên Nhanh đã có webhook lo. Việc cần làm tay là tải lại danh sách khi Nhanh có sản phẩm mới, và đồng bộ lại kho khi Nhanh thêm kho.

Anh em vướng chỗ nào cứ để lại bình luận, nhớ che App ID, Secret Key và token trước khi dán ảnh nhé. Mong đợt đổi giá tới, anh em chỉ cần sửa một chỗ trên Nhanh là web tự theo 🚀