API PDF theo template cho hệ thống production
Tạo PDF theo template từ dữ liệu backend có cấu trúc, không cần browser. gPdf xử lý PDF rendering; logic nghiệp vụ nằm trong hệ thống của bạn.
/api/v1/template-render Tạo PDF theo template thành PDF có thể tái tạo từ dữ liệu có cấu trúc. gPdf render tài liệu; hệ thống của bạn giữ ngữ nghĩa dữ liệu và trạng thái quy trình.
Khi nào dùng API này
- Backend đã có dữ liệu PDF theo template và cần phản hồi PDF ổn định.
- Bạn muốn tránh Chromium hoặc HTML-to-PDF cho tài liệu vận hành.
- Bạn cần output lặp lại được cho in lại, audit hoặc batch.
Những gì không thay thế
- gPdf không mua vận chuyển, khai thuế, tạo đơn hàng ngoài hoặc đóng vai trò hệ thống thuế.
- Không thay thế validation dữ liệu, business rules hoặc tích hợp marketplace.
Endpoint cần gọi
/api/v1/template-render
Template Render là đường mặc định cho workflow này.
/api/v1/pdf/render
Dùng khi workflow cần API liên quan, hợp đồng template hoặc truy vấn capability.
Request tối thiểu
/api/v1/template-render - PDF theo template
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
gPdf xử lý gì
- PDF rendering cho PDF theo template từ request có cấu trúc.
- Text, bảng, đường kẻ, barcode, trang, metadata và tùy chọn output theo request.
- Output deterministic cho retry, in lại và audit.
Hệ thống của bạn quản lý gì
- Dữ liệu đúng của PDF theo template, business rules và trạng thái vận hành.
- Authentication, lưu trữ, workflow bên ngoài và kiểm tra với hệ thống nhận.
Checklist production
- Test bằng dữ liệu thật và hệ thống sẽ nhận PDF.
- Lưu request ID và bằng chứng validation cho support, audit và in lại.
- Chuyển layout đã duyệt thành template khi nhiều hệ thống dùng lại.
Ranh giới cam kết
- gPdf render PDF từ request; không thay thế workflow sản phẩm, database hoặc business validation.
- Data semantics, retries, storage và final acceptance thuộc hệ thống của bạn.
Dạng API
API PDF theo template là workflow production chạy trên public APIs của gPdf. Request mô tả dữ liệu, layout, settings và các phần PDF cần render. gPdf tạo PDF; hệ thống của bạn giữ ngữ nghĩa nghiệp vụ.
Chọn endpoint
Endpoint mặc định của workflow này là /api/v1/template-render. Dùng Template Render khi layout đã duyệt và tái sử dụng giữa nhiều hệ thống. Chỉ dùng E-Invoice Render khi cần gói Factur-X / ZUGFeRD PDF/A-3b với EN 16931 CII XML nhúng.
Kiểm tra trước production
Kiểm tra PDF theo template bằng dữ liệu thật và downstream systems. Lưu request ID, output đã render và bằng chứng validation cho support, audit và in lại.
FAQ
- Đây có phải endpoint riêng không?
- API PDF theo template ánh xạ workflow vào một API công khai của gPdf. Trang này chỉ rõ path cần gọi và request phải sở hữu dữ liệu gì.
- Có dùng templates được không?
- Có. Dùng JSON Render khi layout còn thay đổi; dùng Template Render khi layout đã duyệt và callers chỉ gửi dữ liệu nghiệp vụ.
- Cần kiểm tra gì trước production?
- Kiểm tra bằng dữ liệu thật và printer, scanner, validator, kế toán hoặc marketplace tùy workflow.