Import thông tin khách hàng
Nhập liệu hàng loạt khách hàng mới từ file Excel, tự động xử lý giới tính, ngày sinh, khu vực và kiểm tra trùng lặp SĐT/Email/Mã KH.
Tính năng Import thông tin khách hàng cho phép thêm hàng loạt khách hàng mới vào hệ thống từ file Excel (.xls, .xlsx) hoặc CSV. Hệ thống sẽ tự động normalize dữ liệu (giới tính, ngày sinh, SĐT), resolve Tỉnh/Quận/Phường từ tên text, và kiểm tra trùng lặp SĐT/Email/Mã KH trước khi lưu.
Đây là tính năng import khách hàng (tạo mới khách hàng). Nếu bạn cần import địa chỉ nhận hàng cho khách hàng đã có, xem Import địa chỉ nhận hàng.
Giao diện tổng thể
- Chức năng import nằm ở cuối bảng danh sách trong trang Khách hàng.
- Nhấn nút Import thông tin khách hàng để mở hộp thoại chọn file.
- Hệ thống sẽ đọc file, tự động mapping các cột, và cho phép bạn xem trước dữ liệu trước khi import.
Định dạng file import
File import có thể là Excel (.xls, .xlsx) hoặc CSV (.csv). Mỗi dòng trong file tương ứng với một khách hàng cần tạo mới.
Các cột trong file Excel
Thông tin cơ bản
| Tên cột | Bắt buộc | Mô tả | Mã code |
|---|---|---|---|
| Họ tên | Có | Họ tên đầy đủ của khách hàng | full_name |
| Mã KH | Không | Mã khách hàng (chỉ cho phép a-z, A-Z, 0-9, _, -, .) | code |
| Điện thoại | Không | Số điện thoại (tối thiểu 8 số). Trùng → lỗi | phone |
| Không | Địa chỉ email. Trùng → lỗi | email | |
| Giới tính | Không | Nam / Nữ / Khác. Mặc định: Không xác định | gender |
| Ngày sinh | Không | Định dạng DD/MM/YYYY | birthday |
Địa chỉ
| Tên cột | Bắt buộc | Mô tả | Mã code |
|---|---|---|---|
| Địa chỉ | Không | Địa chỉ (số nhà, đường) | address |
| Tỉnh/Thành phố | Không | Tên tỉnh/thành phố. Hệ thống tự resolve sang mã khu vực | province |
| Quận/Huyện | Không | Tên quận/huyện. Resolve dựa trên tỉnh đã tìm | district |
| Phường/Xã | Không | Tên phường/xã. Resolve dựa trên quận đã tìm | ward |
| Địa chỉ phụ | Không | Địa chỉ phụ (tầng, tòa nhà...) | address_line_2 |
| Ghi chú giao hàng | Không | Chỉ dẫn giao hàng | delivery_note |
Thông tin thêm
| Tên cột | Bắt buộc | Mô tả | Mã code |
|---|---|---|---|
| Tag | Không | Nhãn phân loại khách hàng | tag |
| Ghi chú | Không | Ghi chú về khách hàng | note |
| Tên nội bộ | Không | Tên hiển thị nội bộ (chỉ nhân viên thấy) | internal_name |
| Ghi chú nội bộ | Không | Ghi chú nội bộ (chỉ nhân viên thấy) | internal_note |
| Chức danh | Không | Chức danh / Danh xưng | salutation |
Mạng xã hội
| Tên cột | Mã code |
|---|---|
| Zalo | zalo_id |
facebook_id | |
instagram_id | |
| TikTok | tiktok_id |
| Shopee | shopee_id |
| Telegram | telegram_id |
Hóa đơn
| Tên cột | Mã code |
|---|---|
| Tên người mua | tax_buyer_name |
| Địa chỉ người mua | tax_buyer_address |
| Mã số thuế | tax_buyer_tax_number |
Tên cột trong file không cần khớp chính xác. Hệ thống hỗ trợ nhận diện tên cột tương tự (synonyms). Ví dụ: cột "Tên khách hàng", "Họ tên", "Tên KH" sẽ được tự động mapping thành cột Họ tên.
Danh sách tên cột tương đương (synonyms)
| Cột | Tên tương đương được nhận diện |
|---|---|
| Họ tên | Tên khách hàng, Họ tên, Họ và tên, Tên KH, Tên |
| Mã KH | Mã KH, Mã khách hàng, Mã thẻ, Mã thành viên |
| Điện thoại | Số điện thoại, SĐT, Điện thoại, Phone |
Email, Địa chỉ email | |
| Giới tính | Giới tính, Gender |
| Ngày sinh | Ngày sinh, Sinh nhật, Birthday |
| Địa chỉ | Địa chỉ, Address |
| Tỉnh/Thành phố | Tỉnh, Thành phố, TP, Province, City |
| Quận/Huyện | Quận, Huyện, Thị xã, District |
| Phường/Xã | Phường, Xã, Thị trấn, Ward |
| Tag | Tag, Tags, Thẻ, Nhãn |
| Ghi chú | Ghi chú, Note |
| Tên nội bộ | Tên nội bộ, Tên hiển thị nội bộ |
| Ghi chú nội bộ | Ghi chú nội bộ, Ghi chú NV |
| Chức danh | Chức danh, Danh xưng |
| Địa chỉ phụ | Địa chỉ phụ, Địa chỉ 2 |
| Ghi chú giao hàng | Ghi chú giao hàng, Chỉ dẫn giao hàng |
| Zalo | Zalo, Zalo ID |
Facebook, Facebook ID, FB | |
Instagram, Instagram ID, IG | |
| TikTok | TikTok, TikTok ID |
| Shopee | Shopee, Shopee ID |
| Telegram | Telegram, Telegram ID |
| Tên người mua | Tên người mua, Tên trên hóa đơn |
| Địa chỉ người mua | Địa chỉ người mua, Địa chỉ hóa đơn |
| Mã số thuế | MST, Mã số thuế |
Quy tắc resolve Tỉnh/Quận/Phường
Hệ thống resolve Tỉnh/Quận/Phường theo dạng cascade (bậc thang):
- Tỉnh/Thành phố: Tìm trong danh sách khu vực cấp 1 (parent_id = 0).
- Quận/Huyện: Chỉ tìm trong các khu vực thuộc Tỉnh đã resolve ở bước 1.
- Phường/Xã: Chỉ tìm trong các khu vực thuộc Quận đã resolve ở bước 2.
Thứ tự matching
Mỗi bước resolve sử dụng 3 cấp matching:
| Thứ tự | Phương thức | Mô tả |
|---|---|---|
| 1 | Exact match | Bỏ prefix (Thành phố/Tỉnh/Quận/Huyện...) + lowercase → so khớp chính xác |
| 2 | Contains match | Tìm tên chứa giá trị nhập hoặc ngược lại |
| 3 | Diacritics-insensitive | Bỏ dấu tiếng Việt rồi so khớp |
Ví dụ: Nhập Hà Nội → match với "Thành phố Hà Nội" ✅. Nhập Ha Noi → match bằng diacritics-insensitive ✅.
Quy tắc xử lý giá trị
Giới tính
| Giá trị nhập | Kết quả |
|---|---|
Nam, Male, M | Nam |
Nữ, Nu, Female, F | Nữ |
Khác, Khac, Other | Khác |
| Các giá trị khác hoặc để trống | Không xác định |
Ngày sinh
Hệ thống tự động nhận diện nhiều định dạng ngày sinh:
| Định dạng nhập | Ví dụ | Kết quả |
|---|---|---|
| DD/MM/YYYY | 15/03/1990 | 15/03/1990 ✅ |
| DD-MM-YYYY | 15-03-1990 | 15/03/1990 ✅ |
| YYYY-MM-DD (ISO) | 1990-03-15 | 15/03/1990 ✅ |
| DD/MM/YY | 15/03/90 | 15/03/2090 ✅ |
| Excel serial number | 32917 | Tự động convert ✅ |
| Các định dạng không nhận diện | March 15 | Bỏ trống |
Ngày sinh phải là ngày hợp lệ. Ví dụ: 31/02/1990 (tháng 2 không có ngày 31) sẽ bị báo lỗi error_birthday_invalid.
Số điện thoại
- Hệ thống tự động loại bỏ: khoảng trắng, dấu gạch ngang
-, dấu chấm., dấu ngoặc(). - Chỉ giữ lại chữ số.
- SĐT phải có tối thiểu 8 chữ số.
- Ví dụ:
0901-234-567→0901234567,(+84) 901 234 567→84901234567.
File mẫu tải về
| File mẫu | Mô tả |
|---|---|
| customer_import_template.xlsx | File mẫu import khách hàng với các cột Họ tên, Mã KH, SĐT, Email, Giới tính, Ngày sinh, Địa chỉ, Tỉnh/Quận/Phường và các trường mở rộng. |
Các bước import
- Truy cập trang Khách hàng từ menu bên trái.
- Cuộn xuống cuối bảng danh sách, nhấn nút Import thông tin khách hàng.
- Chọn file Excel hoặc CSV từ máy tính.
- Hệ thống hiển thị bảng mapping cột — kiểm tra và điều chỉnh mapping nếu cần.
- Nhấn Xử lý & nhập dữ liệu vào form để bắt đầu import.
- Hệ thống hiển thị kết quả: số lượng thành công và lỗi (nếu có).
- Danh sách khách hàng sẽ tự động refresh sau khi import hoàn tất.
Ví dụ file Excel mẫu
| Họ tên | Mã KH | Điện thoại | Giới tính | Ngày sinh | Địa chỉ | Tỉnh/TP | Quận/Huyện | Phường/Xã | |
|---|---|---|---|---|---|---|---|---|---|
| Nguyễn Văn A | KH001 | 0901234567 | [email protected] | Nam | 15/03/1990 | 123 Nguyễn Trãi | Hồ Chí Minh | Quận 1 | Bến Thành |
| Trần Thị B | KH002 | 0987654321 | [email protected] | Nữ | 20/08/1995 | 45 Lê Lợi | Hà Nội | Ba Đình | Phúc Xá |
| Lê Văn C | 0912345678 | Nam | 789 Trần Phú | Đà Nẵng | Hải Châu | Thạch Thang |
Kiểm tra trùng lặp
Hệ thống kiểm tra trùng lặp trên 3 trường trước khi tạo khách hàng:
| Trường | Kiểu kiểm tra | Kết quả nếu trùng |
|---|---|---|
| SĐT | Exact match (sau khi format) | Lỗi error_phone_exists |
| Exact match | Lỗi error_email_exists | |
| Mã KH | Exact match, case-sensitive | Lỗi error_code_exists |
Mỗi dòng trong file được kiểm tra độc lập với database hiện tại. Nếu trong cùng file có 2 dòng trùng SĐT, chỉ dòng đầu tiên sẽ được tạo, dòng sau sẽ bị lỗi vì SĐT đã tồn tại (do dòng đầu đã được lưu).
Giới hạn
- Tối đa 10.000 dòng mỗi lần import. Nếu file có nhiều hơn 10.000 dòng, chỉ 10.000 dòng đầu tiên được xử lý, các dòng còn lại bị bỏ qua và hiển thị cảnh báo.
Danh sách lỗi
Import khách hàng trải qua 2 giai đoạn xác thực: Frontend (validate dữ liệu cơ bản, resolve khu vực) và Backend (kiểm tra trùng lặp, validate format, lưu database).
Lỗi Frontend (xử lý trên giao diện)
Các lỗi này xảy ra khi hệ thống đọc file Excel và validate dữ liệu cơ bản. Dòng bị lỗi sẽ không gửi lên server.
| Mã lỗi | Thông báo | Nguyên nhân | Cách khắc phục |
|---|---|---|---|
error_fullname_required | Họ tên không được để trống (Dòng X) | Cột Họ tên để trống | Điền họ tên khách hàng |
warning_max_rows | File có {total} dòng, chỉ xử lý {max} dòng đầu tiên | File Excel có hơn 10.000 dòng | Chia nhỏ file thành nhiều lần import |
no_import_data | Không có dữ liệu để import | Tất cả các dòng đều bị lỗi | Kiểm tra lại toàn bộ file Excel |
Lỗi Backend (xử lý trên server)
Các lỗi này xảy ra khi server nhận dữ liệu và validate trước khi lưu vào database.
| Mã lỗi | Nguyên nhân | Cách khắc phục |
|---|---|---|
error_empty_items | Danh sách items gửi lên server rỗng | Đảm bảo file có ít nhất 1 dòng dữ liệu hợp lệ |
error_max_10000_items | Gửi vượt quá 10.000 items | Chia nhỏ file import |
error_fullname_required | Cột Họ tên trống (lọt qua frontend) | Điền họ tên khách hàng |
error_phone_exists | SĐT đã tồn tại trong hệ thống | Kiểm tra SĐT, sử dụng SĐT khác hoặc sửa SĐT cũ |
error_phone_invalid | SĐT ít hơn 8 chữ số | Kiểm tra lại SĐT, đảm bảo tối thiểu 8 số |
error_email_exists | Email đã tồn tại trong hệ thống | Kiểm tra email, sử dụng email khác |
error_email_invalid | Email không đúng định dạng | Kiểm tra lại email (VD: [email protected]) |
error_code_exists | Mã KH đã tồn tại trong hệ thống | Kiểm tra mã KH, sử dụng mã khác |
error_code_invalid | Mã KH chứa ký tự không hợp lệ | Chỉ dùng a-z, A-Z, 0-9, _, -, . |
error_birthday_format_invalid | Ngày sinh không đúng định dạng DD/MM/YYYY | Sử dụng đúng định dạng DD/MM/YYYY |
error_birthday_invalid | Ngày sinh không hợp lệ (VD: 31/02/1990) | Kiểm tra lại ngày tháng hợp lệ |
error_add | Không thể lưu vào database (lỗi hệ thống) | Thử lại hoặc liên hệ quản trị viên |
Lỗi logic (không hiển thị cảnh báo nhưng ảnh hưởng dữ liệu)
| Tình huống | Hành vi hệ thống | Lưu ý |
|---|---|---|
| Tỉnh/TP không tìm thấy | region_id = 0. Dữ liệu vẫn được import | Kiểm tra tên tỉnh/TP đúng chính tả |
| Quận/Huyện không tìm thấy | sub_region_id = 0. Phường/Xã cũng không resolve (phụ thuộc Quận) | Kiểm tra tên phường/xã và đảm bảo Tỉnh đã resolve |
| Phường/Xã không tìm thấy | sub_sub_region_id = 0 | Kiểm tra tên phường/xã thuộc đúng Quận đã resolve |
| Giới tính không nhận diện | Mặc định → Không xác định | Xem Quy tắc xử lý giới tính |
| Ngày sinh format lạ | Bỏ trống (không lưu ngày sinh) | Sử dụng định dạng DD/MM/YYYY |
| SĐT có ký tự đặc biệt | Tự động loại bỏ ký tự, chỉ giữ số | Xem Quy tắc xử lý SĐT |
Lỗi chung (file Excel)
| Lỗi | Nguyên nhân | Cách khắc phục |
|---|---|---|
| File không đọc được | File bị hỏng, sai định dạng hoặc không có dòng tiêu đề | Kiểm tra file có đuôi .xls, .xlsx hoặc .csv. Đảm bảo dòng đầu tiên là tiêu đề cột |
| Cột không được nhận diện | Tên cột trong file không nằm trong danh sách synonyms | Đổi tên cột theo danh sách tên cột tương đương |
Cách đọc lỗi: Khi import thất bại, hệ thống hiển thị số dòng trong file Excel (bắt đầu từ dòng 2, vì dòng 1 là tiêu đề). Ví dụ: "Dòng 5" tương ứng với dòng thứ 5 trong file Excel. Hệ thống chỉ hiển thị tối đa 10 lỗi đầu tiên từ server.
Phân quyền
- Xem khách hàng: Cần quyền Xem khách hàng (
customer.view). - Import khách hàng: Cần quyền Quản lý khách hàng (
customer.manage).
Import vị trí sản phẩm trong kho
Nhập liệu hàng loạt vị trí sản phẩm từ file Excel, tự động mapping nhà kho, vị trí kho theo mã hoặc tên.
Import địa chỉ nhận hàng
Nhập liệu hàng loạt địa chỉ nhận hàng cho nhiều khách hàng từ file Excel, tự động tìm khách hàng theo mã KH hoặc số điện thoại và resolve tỉnh/quận/phường.