Batch PDF generation API สำหรับ queue และ job
สร้าง PDF จำนวนมากผ่านเวิร์กโฟลว์ JSON Render หรือ Template Render ที่เหมาะกับ queue ขณะที่ระบบของคุณดูแล chunking, retry, idempotency และ storage
/api/v1/template-render เรนเดอร์ PDF จำนวนมากจาก queue หรือ scheduled job โดยแบ่งงานเป็น request ที่ปลอดภัย ส่งเอกสารแต่ละชุดหรือข้อมูลเทมเพลตแต่ละรายการไปยัง gPdf แล้วจัดเก็บหรือส่งต่อ PDF ที่ได้ในระบบของคุณเอง
ควรใช้ API นี้เมื่อใด
- คุณต้องสร้าง invoice, statement, ฉลาก หรือรายงานแบบ scheduled หรือ event-driven batch
- คุณมีเทมเพลตที่เสถียรและส่งข้อมูลหลายรายการได้ภายในขีดจำกัดของ endpoint
- คุณต้องการเรนเดอร์ที่เหมาะกับ queue โดยไม่ต้องรัน browser worker
- คุณสามารถเป็นเจ้าของ deduplication, retry และ output storage ได้เอง
สิ่งที่ไม่ได้ทดแทน
- คุณต้องการให้ gPdf เป็น batch scheduler, queue, storage system หรือ idempotency ledger ของคุณ
- คุณต้องการ rate-limit header ที่เผยแพร่ไว้หรือ contract idempotency-key ฝั่ง server
- คุณต้องการ request เดียวแบบไม่จำกัดเพื่อเรนเดอร์ทุกเอกสารใน campaign
ควรเรียก endpoint ใด
/api/v1/template-render
Template Render คือ path หลักสำหรับเวิร์กโฟลว์นี้.
/api/v1/pdf/render
ใช้เมื่อเวิร์กโฟลว์ต้องการ API path ที่เกี่ยวข้อง สัญญาเทมเพลต หรือการค้นหา capability.
Minimal request
POST /api/v1/template-render - batch ขนาดเล็กพร้อมข้อมูล invoice 2 รายการ
{
"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 จัดการอะไร
- การเรนเดอร์ PDF สำหรับแต่ละ request ของ JSON Render หรือ Template Render
- data array ของ Template Render ภายในขีดจำกัด public ที่ documented
- render response แบบ stateless ที่เร็วและเหมาะกับ queue worker
- พฤติกรรม request ID และ error envelope ร่วมกัน
ระบบของคุณรับผิดชอบอะไร
- การออกแบบ queue, chunking, concurrency, retry, deduplication และ output storage
- การเลือก business object, การเลือกเทมเพลต และ workflow การส่งมอบ
- นโยบาย backoff, alerting และการกู้คืนหลัง partial failure
Production checklist
- แบ่งงานให้แต่ละ request อยู่ในขีดจำกัด item และ payload ที่ documented
- สร้าง X-Request-Id หนึ่งรายการต่อ request และ map เข้ากับ job ID ของคุณ
- retry เฉพาะ network หรือ 5xx failure ด้วย bounded exponential backoff
- อย่า retry 4xx validation failure โดยไม่เปลี่ยน payload
- จัดเก็บ output PDF หรือ source data ตามนโยบาย retention ของคุณ
ขอบเขตของ claim
- gPdf คือ render API ไม่ใช่ queue หรือ storage layer
- public API วันนี้ยังไม่เผยแพร่ rate-limit header หรือ server-side idempotency key
- ระบบของคุณต้องทำให้ retry ปลอดภัยเอง
Batch generation คือ integration pattern
Batch PDF generation ไม่ใช่ endpoint แยก แต่เป็นวิธีที่ queue ของคุณใช้งาน public render APIs ทำให้ job มีขนาดเล็ก สังเกตได้ และ retry ได้อย่างปลอดภัย
สำหรับ layout ที่ใช้ซ้ำ Template Render มักให้ contract ที่สะอาดที่สุด ส่วนเอกสารแบบ programmatic ที่มี layout เฉพาะ JSON Render ยังใช้งานได้
FAQ
- gPdf มี batch job API แยกหรือไม่
- ไม่มี scheduler สำหรับ batch แยกต่างหาก ใช้ JSON Render หรือ Template Render จาก queue หรือ worker system ของคุณเอง
- Template Render รับข้อมูลหลายรายการได้หรือไม่
- ได้ ภายในขีดจำกัดของ public endpoint งานที่ใหญ่กว่านั้นควรถูกแบ่งเป็นหลาย request
- ใครเป็นเจ้าของ retries
- ระบบของคุณเป็นเจ้าของ retries, backoff, deduplication และ idempotency ส่วน gPdf echo request ID เพื่อช่วย trace
- เรนเดอร์ layout หลายแบบใน request เดียวได้หรือไม่
- ใช้ request แยกเมื่อ layout หรือ template ID ต่างกัน รักษาแต่ละ request ให้เรียบง่ายและ trace ได้