Đồng bộ sản phẩm từ Nhanh.vn

Đồng bộ chạy thế nào

• Một chiều Nhanh.vn → website. Sửa sản phẩm trên website không đẩy ngược lên Nhanh.vn. Sản phẩm bị xoá trên Nhanh.vn không bị xoá hay ẩn trên website — plugin chỉ gỡ liên kết.
• Mỗi sản phẩm (và biến thể) trên website được ghép với Nhanh.vn qua một số gọi là ID Nhanh (Nhanh ID). Có ID Nhanh thì webhook mới cập nhật được và đơn hàng mới đăng lên Nhanh.vn đúng sản phẩm.
• Không có lịch đồng bộ định kỳ. Dữ liệu về website theo ba đường: bấm tay ở tab này, chạy trong nền khi bạn bấm nút, và webhook mỗi khi sản phẩm hay tồn kho đổi trên Nhanh.vn.

Làm xong bài Kho hàng trước — tồn kho được cộng từ danh sách kho đã kéo về.

Mở tab Đồng bộ sản phẩm

Lần đầu mở tab, plugin báo "Chưa khởi tạo bảng dữ liệu!". Bấm Khởi tạo bảng ngay — plugin tạo hai bảng riêng để lưu danh sách danh mục và sản phẩm kéo về từ Nhanh.vn.

1. Đồng bộ sản phẩm — tab này chỉ có khi dùng API v3.
2. Cài đặt — chọn trường nào được đồng bộ.
3. Bước 1: Đồng bộ danh mục.
4. Bước 2: Đồng bộ sản phẩm — mở được sau khi bước 1 đã có dữ liệu.
5. Reset toàn bộ Nhanh ID — xem cảnh báo bên dưới.

Xem video

Cài đặt — chọn những gì được đồng bộ

Mặc định mọi trường đều được đồng bộ, còn các ô Ghi đè… đều tắt — trừ ghi đè tồn kho.

1. Đồng bộ giá — giá bán và giá cũ. Sản phẩm trên Nhanh.vn có giá cũ thì giá cũ thành giá thường, giá bán thành giá khuyến mãi trên website.
2. Ảnh đại diện — tải ảnh từ Nhanh.vn về thư viện. Ảnh chưa đổi thì dùng lại, không tải lại; Nhanh.vn đổi ảnh thì tải ảnh mới (ảnh cũ vẫn nằm trong thư viện).
3. Ghi đè ảnh đại diện nếu sản phẩm đã có ảnh — tắt thì chỉ điền khi sản phẩm chưa có ảnh. Ảnh gallery có ô ghi đè tương tự. Biến thể chỉ nhận ảnh đại diện, không có gallery.
4. Mô tả đầy đủ — giữ nguyên định dạng HTML; ảnh chèn trong mô tả vẫn trỏ về máy chủ Nhanh.vn. Không bật ghi đè thì chỉ điền khi ô mô tả trên website đang trống. Mô tả ngắn cũng vậy.
5. Tạo biến thể với thuộc tính tự sinh — dành cho sản phẩm có sản phẩm con nhưng chưa khai thuộc tính trên Nhanh.vn. Plugin lấy phần tên dư của sản phẩm con làm giá trị thuộc tính (ví dụ tên cha "Áo thun", tên con "Áo thun Đỏ" → giá trị "Đỏ"); chọn một thuộc tính có sẵn hoặc gõ tên thuộc tính mới. Chỉ hỗ trợ một thuộc tính.
6. Tạo sản phẩm đơn — phương án dự phòng: không tự sinh được thuộc tính thì tạo mỗi sản phẩm con thành một sản phẩm đơn. Khi bật, có thêm ô lấy ảnh, gallery, danh mục từ sản phẩm cha nếu sản phẩm con không có.
7. Tồn kho — số tồn lấy theo cách tính ở bài Kho hàng. Trọng lượng và kích thước tự đổi từ gram, cm sang đơn vị đang cài của shop.
8. Lưu cài đặt và tiếp tục — lưu rồi sang bước 1. Hoặc bấm Bỏ qua, dùng mặc định.

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

1. Bước 1: Đồng bộ danh mục — lần đầu bấm Tải danh sách danh mục; về sau dùng Làm mới từ API để lấy lại danh sách mới nhất từ Nhanh.vn.
2. Thao tác hàng loạt — Mapping tự động, Tạo mới tất cả hoặc Bỏ qua tất cả, rồi bấm Áp dụng.
3. Danh mục WooCommerce — danh mục trên website mà dòng đó được ghép vào khi cột Thao tác chọn Mapping. Plugin tự gợi ý danh mục khớp theo liên kết cũ rồi theo tên. Chọn Tạo mới thì plugin tạo danh mục mới trên website (giữ quan hệ cha-con); Bỏ qua thì không đồng bộ danh mục đó.
4. Bắt đầu đồng bộ các mục thay đổi — chạy cho những dòng bạn vừa đổi. Bên dưới có thêm Đồng bộ các danh mục "Mapping", Tạo mới các danh mục "Tạo mới", hoặc Bỏ qua, sang bước sản phẩm.

Bước 2 — Đồng bộ sản phẩm

1. Load từ API Nhanh.vn — tải danh sách sản phẩm, 100 sản phẩm mỗi lượt. Đang tải mà dừng giữa chừng thì có nút Chạy tiếp tải nối từ chỗ dừng.
2. Thao tác hàng loạt — như bước 1. Nút Lấy thông tin từ API bên cạnh tải thêm chi tiết (mô tả, ảnh…) cho các sản phẩm đang hiện.
3. Mapping / Tạo mới / Bỏ qua — Mapping ghép vào sản phẩm có sẵn trên website (khớp theo ID Nhanh, rồi theo SKU; bấm Đổi để chọn sản phẩm khác). Tạo mới tạo sản phẩm mới trên website. Bỏ qua không đồng bộ sản phẩm đó.
4. Bắt đầu đồng bộ — chạy ngay trên trình duyệt, phải để nguyên trang tới khi xong. Có thêm Đồng bộ tất cả "Mapping" và Tạo mới tất cả "Tạo mới".
5. Đồng bộ trong nền — Đã thay đổi, Tất cả "Mapping" hoặc Tất cả "Tạo mới". Chạy trên máy chủ, đóng trình duyệt vẫn chạy; có thanh tiến trình và nút Dừng & xoá tiến trình. Nên dùng khi có nhiều sản phẩm.

Cột trái lọc theo danh mục và trạng thái trên Nhanh.vn. Mặc định plugin không tải sản phẩm ở trạng thái Hết hàng; tích ô đó nếu bạn muốn đưa cả chúng về.

Trước khi bấm Tạo mới

• Tên và SKU chỉ được đặt lúc tạo mới. Về sau Mapping hay webhook không đổi tên, SKU trên website — sửa tên trên website thoải mái.
• Plugin không đồng bộ trạng thái sản phẩm: sản phẩm tạo mới được đăng bán ngay, kể cả sản phẩm đang "Ngừng bán" trên Nhanh.vn. Bỏ tích Ngừng bán ở bộ lọc trạng thái nếu không muốn đưa chúng lên.
• Trước khi tạo, plugin kiểm tra ID Nhanh rồi SKU để không tạo trùng sản phẩm đã có.
• Tạo xong, kiểm tra danh mục của các sản phẩm vừa tạo. Chạy thêm một lượt Đồng bộ tất cả "Mapping" để plugin gắn danh mục theo bước 1.

Đồng bộ tồn kho bằng tay

Nút Đồng bộ tồn kho ở cột phải mở hộp "Chỉ đồng bộ tồn kho cho các sản phẩm đã Mapping", nguồn Cache Nhanh.vn hoặc Từ WooCommerce. Cả hai nguồn đều đọc danh sách đã tải về lần gần nhất, không hỏi lại Nhanh.vn.

Ô Nhanh ID trong trang sửa sản phẩm

Mở một sản phẩm bất kỳ, cuộn xuống hộp Đồng bộ sản phẩm từ Nhanh.vn. Dùng khi chỉ cần ghép hoặc đồng bộ vài sản phẩm.

1. Nhanh ID — nhập ID của sản phẩm (hoặc từng biến thể) bên Nhanh.vn, rồi bấm Cập nhật sản phẩm để lưu.
2. Đồng bộ — đồng bộ riêng dòng đó. Dòng chưa có ID hiện "Chưa có Nhanh ID".
3. Đồng bộ toàn bộ — đồng bộ mọi dòng của sản phẩm (cả biến thể) theo cài đặt ở tab Đồng bộ sản phẩm.

Website đang dùng API v2

Với API v2, thay cho tab trên là tab Đồng bộ thông tin sản phẩm:

• Chỉ cập nhật sản phẩm đã ghép (theo ID Nhanh, rồi theo SKU), không tạo mới.
• Chỉ ô Đồng bộ tồn kho bật sẵn; giá, ảnh, gallery, mô tả, khối lượng, kích thước phải tự tích.
• Hai nút: (Trực tiếp) chạy trên trình duyệt, (Cronjob) chạy nền trên máy chủ.
• Bảng sản phẩm bên dưới có ô nhập ID Nhanh và nút Lưu cho từng sản phẩm, lọc được "Chưa có NhanhID / Đã có NhanhID".

Nên chuyển sang v3 trước 30/11/2026 — xem bài kết nối API.

Kiểm tra đã đúng chưa

1. Cột Trạng thái ở bước 2 hiện "Đã đồng bộ" cho các dòng Mapping.
2. Mở một sản phẩm trên website: hộp Đồng bộ sản phẩm từ Nhanh.vn có ID Nhanh, tồn kho khớp tổng các kho trên Nhanh.vn.
3. Đổi giá thử một sản phẩm trên Nhanh.vn, chờ vài giây: giá trên website đổi theo (cần webhook đã bật).

Lỗi thường gặp

Tiếp theo: khai webhook để sản phẩm và tồn kho tự cập nhật.