API PDF theo template cho hợp đồng tài liệu ổn định
Kết xuất PDF từ template_id ổn định và mảng data khi bố cục lặp lại cần được sở hữu một lần rồi tái sử dụng bởi ERP, OMS, WMS hoặc hệ thống gọi SaaS.
/api/v1/template-render Render các PDF lặp lại bằng cách gửi template_id ổn định và mảng dữ liệu nghiệp vụ, thay vì yêu cầu mọi hệ thống gọi mô tả pages, tọa độ và bố cục elements trong từng request.
Khi nào dùng API này
- Bố cục tài liệu đã được duyệt và được nhiều hệ thống gọi hoặc job dùng lại.
- Hệ thống gọi chỉ nên gửi dữ liệu nghiệp vụ, không gửi JSON bố cục ở mức tọa độ.
- Bạn cần đầu ra hóa đơn, packing list, nhãn vận chuyển hoặc template tùy chỉnh.
- Bạn muốn revision template đang active được kiểm soát ngoài hệ thống gọi.
Những gì không thay thế
- Bạn vẫn đang thiết kế bố cục. Hãy dùng JSON Render cho đến khi tọa độ và trường ổn định.
- Bạn cần chuyển HTML tùy ý sang PDF.
- Bạn cần đóng gói PDF/A-3b hóa đơn điện tử với CII XML nhúng.
Endpoint cần gọi
/api/v1/template-render
Template Render là đường mặc định cho quy trình này.
/api/v1/pdf/render
Dùng khi quy trình cần API liên quan, hợp đồng mẫu hoặc truy vấn năng lực.
Request tối thiểu
POST /api/v1/template-render - kết xuất PDF từ template_id.
{
"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ì
- Tra cứu template bằng template_id ổn định.
- Render từng data item với template đang active.
- Ghép các trang đã kết xuất thành một PDF trong giới hạn public endpoint.
- Hành vi authentication, request ID và error envelope dùng chung.
Hệ thống của bạn quản lý gì
- Chọn template, ánh xạ trường, dữ liệu nghiệp vụ và phân quyền hệ thống gọi.
- Quy trình publish template, truyền thông thay đổi và test coverage.
- Chunking, queueing và retries khi render nhiều tài liệu.
Checklist đưa vào production
- Xem template_id là hợp đồng ổn định và opaque.
- Xác thực các trường data trước khi gọi Template Render.
- Giữ golden-PDF tests cho template active và dữ liệu đại diện.
- Chia batch lớn theo giới hạn public của Template Render.
- Log template_id, request ID và ID đối tượng nghiệp vụ để truy vết.
Ranh giới tuyên bố
- Bản thân Template Render không phải công cụ thiết kế; template phải được publish trước.
- gPdf không suy luận dữ liệu nghiệp vụ bị thiếu từ template.
- Template Render không thay thế endpoint E-Invoice Render.
Template Render là lớp hợp đồng trong production
Template Render phù hợp khi bố cục đã qua review và đội ngũ muốn biến nó thành hợp đồng ổn định. Hệ thống gọi gửi template_id cùng dữ liệu nghiệp vụ; gPdf áp dụng template đang active và trả về PDF.
Mô hình này tách trách nhiệm rõ ràng: designer hoặc owner tài liệu quản lý bố cục, còn ERP, OMS, WMS, job queue hoặc backend SaaS chỉ gửi trường cần thiết. Nếu bố cục vẫn đang thử nghiệm, hãy tiếp tục dùng JSON Render cho đến khi trường và tọa độ ổn định.
FAQ
- template_id có phải hợp đồng ổn định không?
- Có. template_id nên được xem như hợp đồng public ổn định giữa bố cục đã publish và các hệ thống gọi gửi data.
- Có thể dùng JSON Render thay vì Template Render không?
- Có. Dùng JSON Render khi bố cục còn đang được thiết kế hoặc cần kiểm soát từng tọa độ; dùng Template Render khi bố cục đã ổn định.
- Template Render có thay thế E-Invoice Render không?
- Không. Nếu cần PDF/A-3b có CII XML nhúng cho Factur-X / ZUGFeRD, hãy dùng E-Invoice Render.
- Ai chịu trách nhiệm về dữ liệu đầu vào?
- Hệ thống của bạn chịu trách nhiệm ánh xạ trường, phân quyền hệ thống gọi, kiểm thử và dữ liệu nghiệp vụ cho PDF theo template.