Template PDF API for stable document contracts
Render PDFs from a stable template_id and data array when repeated layouts should be owned once and reused by ERP, OMS, WMS, or SaaS callers.
/api/v1/template-render Render repeated PDFs by sending a stable template_id and business data array instead of asking every caller to describe pages, coordinates, and layout elements on each request.
When to use this API
- The document layout is approved and reused by multiple callers or jobs.
- Callers should send business data, not coordinate-level layout JSON.
- You need invoice, packing list, shipping label, or custom template output.
- You want active template revisions to be controlled outside the caller.
What it does not replace
- You are still designing the layout. Use JSON Render until the coordinates and fields are stable.
- You need arbitrary HTML-to-PDF conversion.
- You need e-invoice PDF/A-3b packaging with embedded CII XML.
Which endpoint to call
/api/v1/template-render
Template Render is the default path for this workflow.
/api/v1/pdf/render
Use this when the workflow needs the related API path, template contract, or capabilities lookup.
Minimal request
POST /api/v1/template-render - render one invoice from a 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"
}
]
}
]
}
What gPdf handles
- Template lookup by stable template_id.
- Rendering each data item against the active template.
- Concatenating rendered pages into a single PDF within public endpoint limits.
- Shared authentication, request ID, and error envelope behavior.
What your system owns
- Template selection, field mapping, business data, and caller authorization.
- Template publication workflow, change communication, and test coverage.
- Chunking, queueing, and retries when rendering many documents.
Production checklist
- Treat template_id as an opaque stable contract.
- Validate data fields before calling Template Render.
- Keep golden-PDF tests for the active template and representative data.
- Split large batches according to the public Template Render limits.
- Log template_id, request ID, and the business object IDs for traceability.
Claim boundaries
- Template Render is not a design tool by itself; templates must already be published.
- gPdf does not infer missing business data from the template.
- Template Render does not replace the E-Invoice Render endpoint.
Template Render is the production contract layer
JSON Render is ideal while the layout is being designed. Template Render is the
layer to use after the layout becomes a contract. Callers send template_id and
data; the active template owns the document structure.
This keeps callers smaller and makes template changes easier to review, test, and roll out.
FAQ
- When should I use Template Render instead of JSON Render?
- Use Template Render after the layout is approved and callers should only send business data.
- Is template_id stable?
- Yes. The template API docs describe template_id as the stable caller-facing identifier.
- Can one request render multiple data items?
- Yes, Template Render accepts a data array within the public endpoint limits.
- Can Template Render create e-invoices?
- No. Factur-X and ZUGFeRD PDF/A-3b packaging uses the E-Invoice Render endpoint.