# Tạo PDF đầu tiên

Render PDF từ một template HTML/CSS có sẵn: thử dữ liệu, publish và tải kết quả.

## Chuẩn bị
Để bạn dễ làm quen với Tembuilder, chúng tôi sẽ hướng dẫn bạn tạo file PDF đầu tiên từ một mẫu hóa đơn có sẵn. Bạn sẽ thử chỉnh nội dung, thay dữ liệu và xem kết quả trước khi xuất PDF — tất cả ngay trong ứng dụng.

Trước khi bắt đầu, hãy đăng nhập và vào dashboard của **Templates**. Bạn có thể thêm mẫu vào project bằng một trong hai cách dưới đây.

## 1. Chọn và mở mẫu
Bạn có thể dùng file ZIP có sẵn hoặc chọn mẫu trong Gallery.

### Cách 1: Import file ZIP

[Tải mẫu hóa đơn (.zip)](/docs/examples/invoice-template.zip), bấm **Import** trong **Templates** và chọn file vừa tải. Nhập tên và slug cho mẫu, rồi chờ import hoàn tất.

<figure class="doc-sim" aria-label="Import file ZIP, rồi mở mẫu vừa tạo trong Templates.">
<div class="sim-location"><span>Templates</span><span>TEMBUILDER</span></div>
<div class="sim-stage"><div class="sim-template-head"><strong>Templates</strong><div class="sim-actions"><span class="sim-control sim-focus">↥ &nbsp; Import</span><span class="sim-control sim-dark">＋ &nbsp; New template</span></div></div><div class="sim-template-card"><span class="sim-file">▤</span><div><strong>My first invoice</strong><small>my-first-invoice</small></div><span class="sim-badge">Draft</span><span class="sim-arrow">↗</span></div></div>
<figcaption>Templates · Import</figcaption>
</figure>

### Cách 2: Chọn mẫu từ Gallery

Mở **Gallery**, chọn một mẫu hóa đơn và xem trước thiết kế. Thêm mẫu vào project, nhập tên và slug, rồi chờ hoàn tất.

<figure class="doc-sim" aria-label="Xem trước mẫu trong Gallery và chọn Use template để thêm vào project.">
<div class="sim-stage"><div class="sim-gallery-dialog"><div class="sim-gallery-heading"><div><strong>Monochrome Service Invoice</strong><small>Gallery · Invoice</small></div><span aria-hidden="true">×</span></div><div class="sim-gallery-preview"><div class="sim-paper"><div class="sim-paper-brand">Tembuilder</div><div class="sim-invoice-title">INVOICE <small>TB-2026-0042</small></div><div class="sim-bill"><small>BILL TO</small><b>Tembuilder</b></div><div class="sim-paper-lines"><i></i><i></i><i></i></div><div class="sim-total"><small>TOTAL DUE</small><b>$597.20</b></div></div></div><div class="sim-gallery-footer"><small>A4 · 1 page</small><span class="sim-control sim-dark sim-focus">Use template</span></div></div></div>
<figcaption>Gallery → Use template</figcaption>
</figure>

### Mở mẫu trong editor

Sau khi thêm mẫu bằng một trong hai cách trên, mở mẫu trong **Templates** để bắt đầu chỉnh sửa.

Trong editor, chọn một section ở **Structure**. Các tab HTML, CSS, Props và Config tùy thuộc phần đang chọn. Thử đổi một nhãn trong Props nếu có field tương ứng, rồi xem thay đổi trên preview.

<figure class="doc-sim" aria-label="Chọn Billing Parties trong Structure → mở Props → sửa giá trị fromLabel.">
<div class="sim-location"><span>Editor / Structure → Props</span><span>TEMBUILDER</span></div>
<div class="sim-stage"><div class="sim-editor"><div class="sim-tree"><div class="sim-panel-title">▦ &nbsp; STRUCTURE <span>＋</span></div><div class="sim-tree-row">⌄ &nbsp; Global</div><div class="sim-tree-child sim-muted">▤ &nbsp; Footer</div><div class="sim-tree-row">⌄ &nbsp; 01 Invoice <small>5</small></div><div class="sim-tree-child sim-muted">▤ &nbsp; Invoice Masthead</div><div class="sim-tree-child sim-selected">▤ &nbsp; Billing Parties <small>4p</small></div><div class="sim-tree-child sim-muted">▤ &nbsp; Invoice Items</div></div><div class="sim-properties"><div class="sim-tabs"><span>HTML</span><span>CSS</span><span class="sim-active">{} Props</span><span>Config</span></div><div class="sim-prop-body"><small class="sim-label">SECTION</small><strong>Billing Parties</strong><div class="sim-prop-card"><div class="sim-prop-name"><b>fromLabel</b><small>Text <svg class="sim-chevron" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg></small></div><div class="sim-prop-value"><small class="sim-label">VALUE</small><span class="sim-input sim-focus">FROM TEMBUILDER</span><div class="sim-embed">{{ props.fromLabel }}</div></div></div></div></div></div></div>
<figcaption>Structure → Props</figcaption>
</figure>

## 2. Thử dữ liệu và xem trước
Mở **Parameters → Schema** để xem tên trường và giá trị mặc định. Giữ nguyên tên field. **Layout** cho thấy các thay đổi thiết kế đang chỉnh.

**Save** mẫu trước khi mở tab **PDF**. PDF preview dùng nội dung mẫu đã lưu và dữ liệu parameter của editor, ban đầu lấy từ Default. Sau lần lưu tiếp theo, tạo lại PDF preview để xem thay đổi; bản PDF cũ không tự cập nhật. Preview không tính quota render.

Dữ liệu nhập trong **Run** tách riêng với PDF preview. Để thử giá trị mới ở Run, tạo PDF rồi mở kết quả của lần chạy đó ở bước 3–4.

<figure class="doc-sim" aria-label="Parameters hiển thị cấu trúc dữ liệu. PDF preview cho biết bố cục khi xuất PDF.">
<div class="sim-location"><span>Editor / Parameters → PDF preview</span><span>TEMBUILDER</span></div>
<div class="sim-stage"><div class="sim-preview-layout"><div class="sim-data"><div class="sim-tabs"><span class="sim-active">Parameters <small>11</small></span></div><div class="sim-schema-tabs"><span>⚙ Schema</span><span>{} Payload</span></div><div class="sim-fields"><div><b>invoiceNumber</b><small>Text</small></div><span class="sim-input">TB-2026-0042</span><div><b>customer</b><small>Object</small></div><div class="sim-nested"><b>company</b><span class="sim-input">Tembuilder</span></div><div><b>lineItems</b><small>Array</small></div></div></div><div class="sim-preview"><div class="sim-tabs"><span>Layout</span><span class="sim-active">PDF</span></div><div class="sim-paper"><div class="sim-paper-brand">Tembuilder</div><div class="sim-invoice-title">INVOICE <small>TB-2026-0042</small></div><div class="sim-bill"><small>BILL TO</small><b>Tembuilder</b></div><div class="sim-paper-lines"><i></i><i></i><i></i></div><div class="sim-total"><small>TOTAL DUE</small><b>$597.20</b></div></div></div></div></div>
<figcaption>Parameters · Schema → PDF</figcaption>
</figure>

[Dữ liệu JSON mẫu](/docs/examples/invoice-data.json) dùng các field `invoiceNumber`, `seller`, `customer`, `lineItems`, khớp với ZIP ở trên. Với mẫu khác, xem Parameters của chính mẫu đó. Khi gọi API, đặt object dữ liệu vào `parameters`.

## 3. Lưu, publish và tạo PDF
1. **Lưu** thay đổi, chọn đúng version và **publish** version đó.
2. Tạo API key trong project với quyền `template:render` nếu chưa có.
3. Mở **Run**, chọn key, version, variant và điền dữ liệu.
4. Bấm **Render**, đợi công việc hoàn tất.

<figure class="doc-sim" aria-label="Lưu và publish version → chọn key, version, variant trong Run → Render.">
<div class="sim-location"><span>Editor / Publish → Run</span><span>TEMBUILDER</span></div>
<div class="sim-stage"><div class="sim-publish-bar"><div><strong>My first invoice</strong><span class="sim-badge">v1</span></div><div class="sim-actions"><span class="sim-control">Save</span><span class="sim-control sim-dark sim-focus">Publish</span></div></div><div class="sim-run"><div class="sim-panel-title">ϟ &nbsp; RUN</div><div class="sim-run-body"><div class="sim-pickers"><div><small class="sim-label">API KEY</small><span class="sim-input">My project key <svg class="sim-chevron" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg></span></div><div><small class="sim-label">VERSION</small><span class="sim-input">v1 <svg class="sim-chevron" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg></span></div><div><small class="sim-label">VARIANT</small><span class="sim-input">Standard <svg class="sim-chevron" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg></span></div></div><div class="sim-code"><span>{</span><span>  "invoiceNumber": "TB-2026-0042",</span><span>  "customer": {</span><span>    "company": "Tembuilder"</span><span>  }, …</span><span>}</span></div><div class="sim-render-footer"><span class="sim-badge sim-success">● Published</span><span class="sim-control sim-dark sim-focus">ϟ &nbsp; Render</span></div></div></div></div>
<figcaption>Publish → Run → Render</figcaption>
</figure>

> Render thật cần version đã publish. Mỗi lần render thành công tính quota; xem được preview chưa có nghĩa mẫu đã sẵn sàng để render.

## 4. Tải và kiểm tra kết quả
Khi trạng thái thành công, mở kết quả và tải PDF. Có thể tìm lại lần chạy trong **Renders**. Kiểm tra trang đầu, trang cuối và các dòng dữ liệu trong file tải về.

<figure class="doc-sim" aria-label="Mở lần render thành công để tải PDF. Tìm lại kết quả trong Renders.">
<div class="sim-location"><span>Run / History · Renders</span><span>TEMBUILDER</span></div>
<div class="sim-stage"><div class="sim-result"><div class="sim-result-top"><span class="sim-success-mark">✓</span><div><strong>My first invoice</strong><small>v1 · Standard</small></div><span class="sim-badge sim-success">Completed</span></div><div class="sim-result-file"><span class="sim-file">PDF</span><div><strong>invoice.pdf</strong><small>application/pdf</small></div><span class="sim-control sim-dark sim-focus">↓ &nbsp; Download</span></div></div></div>
<figcaption>Renders → Download</figcaption>
</figure>

Nếu thất bại, mở chi tiết lỗi trước khi thử lại. Mỗi lần bấm Render có thể tạo một công việc mới. Xem [cách xử lý lỗi thường gặp](/docs/vi/help/common-errors/) nếu chưa xác định được nguyên nhân.