Import sản phẩm

Tính năng Import sản phẩm cho phép thêm hoặc cập nhật hàng loạt sản phẩm và biến thể từ file Excel. Hệ thống sẽ tự động tạo hoặc cập nhật thông tin dựa trên Mã sản phẩm và SKU.

Giao diện tổng thể

• Màn hình import bao gồm 3 bước: Tải lên file, Kiểm tra dữ liệu, Xác nhận import.
• Hiển thị bảng preview dữ liệu với highlight lỗi nếu có.
• Sidebar bên phải hiển thị thống kê: Số dòng hợp lệ, số lỗi, cảnh báo.
• Nút tải file mẫu Excel nằm ở góc trên phải.

Định dạng file import

File import có thể là Excel (.xls, .xlsx) hoặc CSV (.csv). Giới hạn: dung lượng tối đa 10 MB, tối đa 20.000 dòng dữ liệu (trừ dòng tiêu đề). Tên tiêu đề cột phải khớp chính xác với file mẫu. Cột bắt buộc (phải có trong file): tất cả các cột từ Danh mục đến Mô tả trong bảng dưới, trừ 12 cột tùy chọn ở cuối (từ Mã vạch đến Khối lượng variant). Thiếu một cột bắt buộc → báo lỗi khi tải file (error_file_missing_column).

Import sản phẩm

1. Truy cập menu Sản phẩm > Tất cả sản phẩm.
2. Nhấn nút Import trên thanh công cụ, chọn tuỳ chọn "Import sản phẩm & biến thể" để tới trang Import sản phẩm.
3. Nhấn Tải file mẫu Excel trên giao diện để tải template (nếu chưa có), hoặc tải file mẫu theo ngành hàng ở mục File mẫu tải về bên dưới.
4. Chuẩn bị file Excel theo đúng định dạng các cột yêu cầu.
5. Nhấn Chọn file từ máy tính để mở cửa sổ chọn file Excel từ máy tính của bạn.
6. Nhấn Bắt đầu Import dữ liệu để upload file và bắt đầu xử lý. Nếu có lỗi thiếu cột, sai cột... thì hãy kiểm tra ở bước này.
7. Chờ hệ thống xử lý và hiển thị kết quả: Số sản phẩm đã tạo/cập nhật.

File mẫu tải về

Các file Excel mẫu theo ngành hàng để tham khảo định dạng cột và dữ liệu. Tải về, chỉnh sửa theo nhu cầu rồi dùng để import.

Quy tắc xử lý dữ liệu

Tạo mới và cập nhật

• Sản phẩm: Tìm theo Mã sản phẩm (code). Chưa tồn tại → tạo mới; đã tồn tại → cập nhật (tên, tag, visibility, weight_type, weight_sale_mode, weight_presets, status, allow_sale, allow_purchase, v.v.).
• Loại sản phẩm & Cách bán cân ký: Import cho phép thay đổi Loại sản phẩm (weight_type) và Cách bán cân ký (weight_sale_mode) trên sản phẩm đã tồn tại. VD: chuyển sản phẩm từ "Đơn vị tính" sang "Hàng cân ký" hoặc ngược lại. Khi chuyển sang cân ký, Quy cách cân ký (weight_presets) và thông tin catch-weight cũng được cập nhật theo.
• Tên sản phẩm không được trùng với sản phẩm khác trong cùng công ty; nếu trùng hệ thống báo lỗi error_import_row_name_duplicated và không lưu dòng đó.
• Mô tả: Khi cập nhật, chỉ ghi đè nếu sản phẩm hiện tại chưa có mô tả; khi tạo mới luôn lấy từ file.
• Tag: Chỉ ghi đè khi cột Tag trong file không để trống; nếu để trống khi cập nhật thì giữ nguyên tag hiện có.
• Hình ảnh: Chỉ tải và gán khi sản phẩm chưa có hình đại diện; nếu đã có ảnh thì cột Hình sản phẩm bị bỏ qua. Hình đầu tiên trong danh sách URL được đặt làm ảnh đại diện.
• Biến thể: Tìm theo cặp (sản phẩm, SKU). SKU trống → hệ thống dùng Mã sản phẩm làm SKU. Chưa tồn tại → tạo biến thể mới; đã tồn tại → cập nhật giá và thông tin biến thể. Các cột Mã vạch, Tên riêng biến thể, Ghi chú biến thể, Giá so sánh, Tồn tối thiểu, Theo dõi serial, Chiều dài (mm) / Chiều rộng (mm) / Chiều cao (mm) và Khối lượng variant (gram) được gán trực tiếp cho biến thể nếu có trong file.

Gom nhóm sản phẩm

• Các dòng có cùng Mã sản phẩm sẽ được gom thành 1 sản phẩm.
• Mỗi dòng tương ứng với 1 biến thể hoặc 1 đơn vị tính của sản phẩm đó.
• Sản phẩm có nhiều đơn vị tính: Các dòng có cùng thuộc tính nhưng khác đơn vị tính.
• Sản phẩm có nhiều biến thể: Các dòng có thuộc tính khác nhau.

Xử lý đơn vị tính

• Chỉ áp dụng cho sản phẩm đơn vị tính (Loại sản phẩm = 1). Dòng có Hệ số quy đổi = 1 là đơn vị cơ bản (cho phép tồn kho, đơn vị mặc định); hệ số > 1 là đơn vị phụ (VD: Thùng = 10 Bịch), không dùng để tồn kho.
• Giá bán trong file tương ứng với đơn vị tính của dòng đó; với hệ số > 1, giá được lưu vào bảng giá theo đơn vị (pricebyuom).

Xử lý thuộc tính

• Định dạng: Tên thuộc tính : Giá trị. Nhiều cặp cách nhau bởi dấu phẩy (,) hoặc dấu sổ dọc (|). VD: Màu: Đen, Size: XL hoặc Màu: Đen|Size: XL.
• Hệ thống tự động tạo thuộc tính (option) và giá trị (option value) nếu chưa tồn tại. Các option của biến thể được gộp lại hiển thị trên sản phẩm.

Lưu ý đối với sản phẩm cân ký

• Loại sản phẩm = 3 (Hàng cân ký). Với loại này, cột Đơn vị tính trong file không dùng; hệ thống dùng đơn vị Gram từ cài đặt.
• Cách bán cân ký bắt buộc = 3 (Bán theo khối lượng) hoặc 5 (Bán theo số lượng). Nếu để trống hoặc = 0 khi Loại = 3, mặc định là 3. Nếu nhập giá trị khác 3 hoặc 5 sẽ báo lỗi error_import_row_invalid_for_weighted_product_missing_weight_sale_mode.
• Catch-weight (Cân & đếm): Khi Cách bán cân ký = 5, có thể khai báo thêm Đơn vị catchweight (VD: "Trái") và Hệ số catchweight (VD: 2500 gram). Hệ thống sẽ tự tạo đơn vị tính nếu chưa tồn tại, gán physical_catch_weight_uom_id và tạo preset cân ký tương ứng. Nếu 2 cột này để trống, sản phẩm vẫn tạo được nhưng thiếu thông tin catch-weight.
• Giá bán trong file là giá cho 1 kg; hệ thống lưu giá cho 1 gram (chia 1000).
• Khối lượng (gram) không dùng cho sản phẩm cân ký; hệ thống tự đặt = 1 (1 gram).
• Sản phẩm cân ký không tạo bản ghi đơn vị tính (ProductUom); chỉ sản phẩm đơn vị tính mới dùng Đơn vị tính, Hệ số quy đổi, Khối lượng (gram) trong file.

Trạng thái & hành vi hệ thống

• Trạng thái sản phẩm mặc định = 3 (Đang kinh doanh) nếu để trống hoặc = 0. Hiển thị mặc định = 1 (Hiển thị).
• Loại sản phẩm mặc định = 1 (Đơn vị tính) nếu để trống hoặc = 0. Cách bán cân ký mặc định = 3 (Bán theo khối lượng) khi Loại = 3 và không khai báo.
• Cách tính giá hỗ trợ nhập từ file: 1 = Giá chuẩn (mặc định), 3 = Báo giá sau. Nếu để trống → mặc định Giá chuẩn. Cách mua hàng vẫn đặt cố định (Mua theo tồn kho).
• Danh mục (3 cấp, phân cách >>) được tự tạo nếu chưa có. Thương hiệu và Nhà cung cấp (nhiều nhà cung cấp cách nhau dấu phẩy) tự tạo nếu chưa tồn tại.
• Hình ảnh chỉ tải và gán khi sản phẩm chưa có hình đại diện. Tag chỉ ghi đè khi cột Tag không trống; tag mới được tạo nếu chưa có trong hệ thống.
• Luồng xử lý: Sau khi tải file, hệ thống tạo nhiệm vụ import (DataTask) và chia dữ liệu thành các trang (page). Import chạy từng trang qua queue; khi một trang lỗi nghiêm trọng (page error), toàn bộ nhiệm vụ có thể bị hủy.

Lưu ý – Giới hạn – Lỗi thường gặp

• Giới hạn file: Định dạng .xls, .xlsx, .csv; dung lượng ≤ 10 MB; số dòng dữ liệu ≤ 20.000. Tiêu đề cột phải khớp chính xác với file mẫu. File phải có đủ 20 cột bắt buộc (từ Danh mục (3 cấp) đến Mô tả); thiếu một cột bắt buộc sẽ báo lỗi khi tải file (error_file_missing_column). 13 cột tùy chọn (Quy cách cân ký, Đơn vị catchweight, Hệ số catchweight, Mã vạch, Tên riêng biến thể, … đến Khối lượng variant (gram)) — có thể không có trong file.
• Mã sản phẩm và SKU được chuẩn hóa plaintext; tránh ký tự đặc biệt. Tên sản phẩm không được trùng với sản phẩm khác trong cùng công ty (lỗi error_import_row_name_duplicated).
• Giá bán nhập số (số nguyên); với sản phẩm cân ký là giá/1 kg, hệ thống tự chia 1000 khi lưu.
• URL hình ảnh phải hợp lệ và truy cập được; hệ thống tạo/tìm file từ URL. Nếu sản phẩm đã có hình đại diện thì cột Hình sản phẩm bị bỏ qua.
• Import chỉ tạo mới và cập nhật; không xoá sản phẩm. Sản phẩm không nằm trong file không bị thay đổi.
• Lỗi thường gặp: Khi tải file: error_file_missing_column (thiếu cột bắt buộc). Khi xử lý từng dòng: error_import_row_name_duplicated, error_import_row_invalid_for_weighted_product_missing_uom_setting_gram, error_import_row_invalid_for_weighted_product_missing_weight_sale_mode, error_product_added / error_product_updated, error_product_variant_added / error_product_variant_updated, error_product_uom_added / error_product_uom_updated. Kết quả từng dòng trả về trong result.rows với success, error, object_id (sản phẩm), object_id_more (biến thể).

Phân quyền

• Xem: Cần quyền Xem sản phẩm.
• Import: Cần quyền Quản lý sản phẩm.