Tham chiếu API

Endpoints

Endpoint	Method	Mô tả
{collection}:importXlsx	POST	Nhập dữ liệu từ file Excel (multipart/form-data)
{collection}:downloadXlsxTemplate	POST	Tải file Excel mẫu theo cấu hình field

{collection}:importXlsx

Method: POST

Content-Type: multipart/form-data (qua @koa/multer middleware)

Request parameters:

Tham số	Kiểu	Bắt buộc	Mô tả
file	File	Có	File Excel (.xlsx) upload qua multipart
columns	JSON	Có	Mapping cột Excel sang field collection
explain	boolean	Không	true = dry-run (chỉ validate, không insert)

Luồng xử lý server:

1. Multer middleware nhận file upload, lưu vào buffer.
2. Parse file Excel bằng exceljs.
3. Validate từng dòng: kiểm tra type, required, unique constraint.
4. Nếu explain: true → chỉ trả kết quả validate.
5. Nếu explain: false → insert/update bản ghi vào DB.
6. Trả kết quả: số dòng thành công, danh sách dòng lỗi.

Response thành công:

{
  "success": true,
  "data": {
    "successCount": 450,
    "failureCount": 5,
    "failures": [
      { "row": 12, "field": "email", "message": "Giá trị trùng lặp" }
    ]
  }
}

{collection}:downloadXlsxTemplate

Method: POST

Tạo file Excel mẫu theo cấu hình field của collection.

Response: Binary XLSX stream chứa header row với tên cột.

Error classes

Plugin định nghĩa hai custom error class:

Error class	Khi nào	Nội dung
ImportValidationError	Dữ liệu không hợp lệ (type, required, unique)	Danh sách dòng + lý do lỗi
ImportError	Lỗi hệ thống (DB connection, parse failure)	Mô tả lỗi kỹ thuật

Mutex

Import sử dụng async-mutex tương tự export — chỉ cho phép 1 import chạy cùng lúc trên cùng server instance để tránh race condition.

ACL

Quyền	Mô tả
importXlsx	Quyền riêng biệt cho import, thêm vào admin role khi install
downloadXlsxTemplate	Cho phép tất cả user đã đăng nhập tải template