Tham chiếu API

Endpoints

Endpoint	Method	Mô tả
{collection}:templatePrint	POST	Render dữ liệu bản ghi vào template, trả file kết quả
printingTemplates:upload	POST	Upload template mới
printingTemplates:download	GET	Tải file template gốc
printingTemplates CRUD	GET/POST/PUT/DELETE	Quản trị metadata template (admin)

{collection}:templatePrint

Method: POST

Render dữ liệu bản ghi vào template Carbone, trả file kết quả.

Request body:

Tham số	Kiểu	Bắt buộc	Mô tả
filterByTk	string/number	Có	ID bản ghi cần in
templateName	string	Có	Tên template sử dụng
blockName	string	Không	Tên block chứa action (xác định data context)
convertedToPDF	boolean	Không	Chuyển đổi kết quả sang PDF

Response: Binary file stream (responseType: blob).

Luồng xử lý server:

1. Đọc metadata template từ DB (printingTemplates).
2. Đọc file template từ storage/print-templates/.
3. Query dữ liệu bản ghi từ DB (kèm associations, attachments).
4. Resolve hình ảnh từ attachment field.
5. Tạo QR code (nếu template chứa QR placeholder).
6. Gọi Carbone engine render data vào template.
7. Trả binary file về client.

printingTemplates:upload

Method: POST

Upload file template mới. File được lưu vào storage/print-templates/.

printingTemplates:download

Method: GET

Tải file template gốc (file admin đã upload, chưa render dữ liệu).

Database schema

Bảng printingTemplates

Cột	Kiểu	Mô tả
name	string	Tên định danh template (unique)
title	string	Tên hiển thị
collectionName	string	Collection mà template áp dụng
rootDataType	string	Loại dữ liệu gốc (single record / list)
dataSource	string	Data source sử dụng
filename	string	Tên file template trên filesystem
enabled	boolean	Template có đang hoạt động

Carbone engine

Plugin sử dụng Carbone để render dữ liệu vào template:

Tính năng	Mô tả
Placeholder	{d.field} — thay thế bằng giá trị field
Loop	{d.items[i].field} — lặp qua mảng
Format	{d.field:formatN(2)} — format số, ngày
Condition	{d.field:ifEQ(value)}...{d.field:showEnd} — hiện/ẩn block
Image	Nhúng hình ảnh từ attachment field
QR code	Tự động tạo và nhúng QR code

ACL

Quyền	Loại	Mô tả
ui.templatePrint	Snippet	Cho phép truy cập UI template print
templatePrint	Action	Cho phép user đã đăng nhập thực hiện in
On install	Strategy	Tự động thêm vào admin + member role strategies