API tạo PDF hàng loạt cho queue và job
Tạo nhiều PDF qua quy trình JSON Render hoặc Template Render an toàn cho queue, trong khi hệ thống của bạn sở hữu chunking, retries, idempotency và storage.
/api/v1/template-render Tạo nhiều PDF từ queue hoặc scheduled job bằng cách chia công việc thành các request an toàn, gửi từng tài liệu hoặc từng data item template tới gPdf, rồi lưu hoặc phân phối PDF trả về trong hệ thống của bạn.
Khi nào dùng API này
- Bạn cần tạo hóa đơn, sao kê, nhãn hoặc báo cáo theo batch định kỳ hoặc event-driven.
- Bạn có template ổn định và có thể gửi nhiều data item trong giới hạn endpoint.
- Bạn cần quy trình kết xuất thân thiện với queue mà không chạy browser workers.
- Bạn có thể tự quản lý deduplication, retries và đầu ra storage.
Những gì không thay thế
- Bạn cần gPdf làm batch scheduler, queue, hệ thống storage hoặc idempotency ledger.
- Bạn cần rate-limit headers công khai hoặc hợp đồng idempotency-key phía server.
- Bạn cần một request không giới hạn để kết xuất toàn bộ tài liệu của campaign.
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 - tạo PDF hàng loạt.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
gPdf xử lý gì
- Kết xuất PDF cho từng request JSON Render hoặc Template Render.
- Mảng data của Template Render trong giới hạn public đã document.
- Phản hồi kết xuất nhanh, stateless và phù hợp cho queue workers.
- Hành vi request ID và error envelope dùng chung.
Hệ thống của bạn quản lý gì
- Thiết kế queue, chunking, concurrency, retries, deduplication và đầu ra storage.
- Chọn đối tượng nghiệp vụ, chọn template và quy trình phân phối.
- Backoff policy, alerting và phục hồi sau lỗi một phần.
Checklist đưa vào production
- Chia công việc để mỗi request nằm trong giới hạn item và payload đã document.
- Tạo một X-Request-Id cho mỗi request và map về job ID của bạn.
- Chỉ retry lỗi network hoặc 5xx với bounded exponential backoff.
- Không retry lỗi validation 4xx nếu chưa thay đổi payload.
- Lưu đầu ra PDF hoặc dữ liệu nguồn theo retention policy của bạn.
Ranh giới tuyên bố
- gPdf là API kết xuất, không phải queue hoặc storage layer.
- Public API hiện không publish rate-limit headers hoặc server-side idempotency keys.
- Hệ thống của bạn phải làm retry an toàn.
Tạo PDF hàng loạt là một mô hình tích hợp
Tạo PDF hàng loạt là một mô hình tích hợp, không chỉ là một request lớn. Hệ thống của bạn nên chia công việc theo job ID, gửi từng chunk an toàn tới JSON Render hoặc Template Render, rồi lưu đầu ra theo policy của chính bạn.
gPdf giữ phần kết xuất nhanh và stateless. Queue, lịch chạy, idempotency, deduplication và phục hồi sau lỗi một phần vẫn thuộc hệ thống gọi. Điều này giúp batch invoices, statements, labels hoặc reports chạy ổn định mà không cần tự vận hành browser workers.
FAQ
- Đây có phải API tạo PDF hàng loạt độc lập không?
- Có. Trang này ánh xạ quy trình tạo PDF hàng loạt vào endpoint công khai POST /api/v1/template-render. Hệ thống của bạn vẫn sở hữu dữ liệu nghiệp vụ, còn gPdf chỉ tạo PDF từ request hợp lệ.
- Khi nào nên dùng Template Render?
- Dùng Template Render khi bố cục đã được duyệt và bạn muốn gọi bằng template_id cùng data thay vì gửi toàn bộ tọa độ ở mỗi request.
- API có trả PDF trực tiếp không?
- Có. Khi kết xuất thành công, API trả về application/pdf. Khi lỗi, API dùng JSON error envelope chung với mã API-XXX và req_id.
- Cần kiểm tra gì trước production?
- Hãy kiểm tra chunk size, retry policy, request ID và lưu trữ đầu ra trước production.