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.
Tính năng Import địa chỉ nhận hàng cho phép thêm hàng loạt địa chỉ giao hàng cho nhiều khách hàng từ file Excel (.xls, .xlsx) hoặc CSV. Hệ thống sẽ tự động tìm khách hàng dựa trên mã khách hàng hoặc số điện thoại, và resolve Tỉnh/Quận/Phường từ tên text sang mã khu vực hệ thố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 địa chỉ nhận 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 địa chỉ nhận hàng cần thêm.
Các cột trong file Excel
| Tên cột | Bắt buộc | Mô tả | Mã code |
|---|---|---|---|
| Mã khách hàng | Không | Mã khách hàng để định danh. Ưu tiên tìm theo mã nếu có | customer_code |
| SĐT Khách hàng | Có | Số điện thoại khách hàng để định danh. Bắt buộc | customer_phone |
| Tên hiển thị | Có | Tên hiển thị cho địa chỉ (VD: "Nhà riêng", "Công ty") | display_name |
| Họ tên | Có | Họ tên người nhận hàng | full_name |
| SĐT liên hệ | Không | Số điện thoại liên hệ nhận hàng | phone |
| Địa chỉ giao hàng | Không | Địa chỉ giao hàng (số nhà, đường) | address |
| Tỉnh/Thành phố | Không | Tên tỉnh/thành phố. Hệ thống tự động 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 |
| Thông tin địa chỉ phụ | Không | Mã căn hộ, Block, Chung cư - tòa nhà | address_line_2 |
| Chỉ dẫn giao hàng | Không | Ghi chú / hướng dẫn giao hàng dành cho shipper | delivery_note |
| Địa chỉ mặc định | Không | Có/Không — đánh dấu địa chỉ mặc định. Mặc định: Không | is_default |
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).
Danh sách tên cột tương đương (synonyms)
| Cột | Tên tương đương được nhận diện |
|---|---|
| Mã khách hàng | Mã khách hàng |
| SĐT Khách hàng | SĐT Khách hàng |
| Tên hiển thị | Tên hiển thị |
| Họ tên | Họ tên |
| SĐT liên hệ | SĐT liên hệ |
| Địa chỉ giao hàng | Địa chỉ giao hàng |
| Tỉnh/Thành phố | Tỉnh/Thành phố |
| Quận/Huyện | Quận/Huyện |
| Phường/Xã | Phường/Xã |
| Thông tin địa chỉ phụ | Thông tin địa chỉ phụ |
| Chỉ dẫn giao hàng | Chỉ dẫn giao hàng |
| Địa chỉ mặc định | Địa chỉ mặc định |
Quy tắc tìm khách hàng
Cột Mã KH / SĐT trong file Excel dùng để xác định khách hàng. Backend nhận giá trị text và tìm khách hàng theo thứ tự ưu tiên:
- Ưu tiên 1 – Tìm theo mã khách hàng (
cc_code): So khớp chính xác, không phân biệt hoa thường. - Ưu tiên 2 – Tìm theo số điện thoại (
cc_phone): So khớp chính xác. - Ưu tiên 3 – Tìm theo ID khách hàng: Nếu giá trị là số thuần, tìm khách hàng có ID khớp.
Ví dụ: Nếu khách hàng có Mã = KH001 và SĐT = 0901234567, bạn có thể nhập một trong các giá trị:
KH001→ Tìm theo mã khách hàng ✅0901234567→ Tìm theo SĐT ✅
Nếu không tìm thấy khách hàng phù hợp, dòng đó sẽ bị bỏ qua và hiển thị lỗi "Không tìm thấy khách hàng".
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 ✅.
Ngoài resolve region_id, hệ thống đồng thời lưu text gốc vào các field legacy (legacy_province_name, legacy_district_name, legacy_ward_name) để đảm bảo dữ liệu không bị mất ngay cả khi resolve thất bại.
File mẫu tải về
| File mẫu | Mô tả |
|---|---|
| customeraddress_import_template.xlsx | File mẫu import địa chỉ nhận hàng với các cột Mã KH, Tên hiển thị, Họ tên, Điện thoại, Địa chỉ, Tỉnh/Quận/Phường. |
Các bước import
- Truy cập trang Khách hàng từ menu.
- Cuộn xuống cuối bảng danh sách, nhấn nút Import địa chỉ nhận 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ý để 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
| Mã KH / SĐT | Tên hiển thị | Họ tên | Điện thoại | Địa chỉ | Tỉnh/TP | Quận/Huyện | Phường/Xã | Mặc định | |
|---|---|---|---|---|---|---|---|---|---|
| KH001 | Nhà riêng | Nguyễn Văn A | 0901234567 | [email protected] | 123 Nguyễn Trãi | Hồ Chí Minh | Quận 1 | Bến Thành | Có |
| 0987654321 | Công ty | Trần Thị B | 0987654321 | [email protected] | 45 Lê Lợi | Hà Nội | Ba Đình | Phúc Xá | Không |
| KH003 | Nhà bà ngoại | Lê Văn C | 0912345678 | 789 Trần Phú | Đà Nẵng | Hải Châu | Thạch Thang | Không |
Quy tắc xử lý giá trị
Mặc định
| Giá trị nhập | Kết quả |
|---|---|
Có, Co, Yes, 1, true | Đặt làm mặc định |
| Các giá trị khác hoặc để trống | Không mặc định |
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.
Danh sách lỗi
Import địa chỉ nhận hàng trải qua 2 giai đoạn xác thực: Frontend (resolve khu vực Tỉnh/Quận/Phường và validate dữ liệu cơ bản) và Backend (resolve khách hàng theo mã/SĐT/ID và validate trước khi lưu). Dưới đây là danh sách đầy đủ các lỗi có thể xảy ra.
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_customer_required | Mã KH / SĐT không được để trống (Dòng X) | Cột Mã KH / SĐT để trống | Điền mã khách hàng hoặc số điện thoại |
full_name | Họ tên không được để trống (Dòng X) | Cột Họ tên để trống | Điền họ tên người nhận hàng |
import_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, mỗi lần tối đa 10.000 dòng |
import_error_no_data | Không có dữ liệu để import | Tất cả các dòng đều bị lỗi, không có dòng nào hợp lệ | 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. Backend chịu trách nhiệm resolve khách hàng từ mã/SĐT.
| 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 Excel có ít nhất 1 dòng dữ liệu hợp lệ |
error_customer_required | Cột Mã KH / SĐT trống (lọt qua frontend) | Điền mã khách hàng hoặc số điện thoại |
error_customer_not_found | Không tìm thấy khách hàng. Backend đã tìm theo: 1. Mã KH (exact, case-insensitive) → 2. SĐT (exact) → 3. ID (nếu là số thuần) – đều không khớp | Kiểm tra lại mã KH/SĐT. Đảm bảo khách hàng đã được tạo trong hệ thống. Xem Quy tắc tìm khách hàng |
error_fullname_required | Cột Họ tên trống (lọt qua frontend) | Điền họ tên người nhận hàng |
error_insert_failed | Dòng dữ liệu hợp lệ nhưng 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. Text gốc vẫn được lưu vào legacy_province_name | Dữ liệu vẫn được import, nhưng khu vực không được resolve. 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. Text gốc được lưu vào legacy_district_name. Phường/Xã cũng sẽ không resolve (vì phụ thuộc Quận) | Kiểm tra tên Quận/Huyện và đảm bảo Tỉnh đã resolve thành công |
| Phường/Xã không tìm thấy | sub_sub_region_id = 0. Text gốc được lưu vào legacy_ward_name | Kiểm tra tên Phường/Xã thuộc đúng Quận đã resolve |
| Tên hiển thị để trống | Hệ thống tự lấy Họ tên làm tên hiển thị | Điền tên hiển thị để phân biệt các địa chỉ (VD: "Nhà riêng", "Công ty") |
| Mặc định không hợp lệ | Giá trị không nhận diện được → mặc định Không | Xem Quy tắc xử lý giá trị để biết các giá trị được chấp nhận |
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 đề + dòng 2 bắt đầu dữ liệu). Ví dụ: "Dòng 5" tương ứng với dòng thứ 5 trong file Excel.
Phân quyền
- Xem khách hàng: Cần quyền Xem khách hàng (
customer.view). - Import địa chỉ nhận hàng: Cần quyền Quản lý khách hàng (
customer.manage).