Template PDF API voor stabiele documentcontracten
Render PDF's vanuit een stabiel template_id en een data-array wanneer herhaalde lay-outs één keer beheerd en door ERP-, OMS-, WMS- of SaaS-aanroepers hergebruikt moeten worden.
/api/v1/template-render Render herhaalde PDF's door een stabiel `template_id` en een array met bedrijfsdata te sturen, in plaats van elk aanroepend systeem bij elke request pagina's, coördinaten en lay-outelementen te laten beschrijven.
Wanneer deze API past
- De documentlay-out is goedgekeurd en wordt door meerdere aanroepende systemen of jobs hergebruikt.
- Aanroepende systemen moeten bedrijfsdata sturen, geen lay-out-JSON op coördinatenniveau.
- U hebt output nodig voor facturen, paklijsten, verzendlabels of maatwerksjablonen.
- U wilt actieve template-revisies buiten het aanroepende systeem beheren.
Wat dit niet vervangt
- U ontwerpt de lay-out nog. Gebruik JSON Render totdat coördinaten en velden stabiel zijn.
- U hebt willekeurige HTML-naar-PDF-conversie nodig.
- U hebt E-Invoice-PDF/A-3b-packaging met ingebedde CII XML nodig.
Welk endpoint aanroepen
/api/v1/template-render
Template Render is het standaardpad voor deze workflow.
/api/v1/pdf/render
Gebruik dit wanneer de workflow een verwant API-pad, templatecontract of capability lookup nodig heeft.
Minimale request
POST /api/v1/template-render - render één factuur vanuit een 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"
}
]
}
]
}
Wat gPdf afhandelt
- Template lookup via stabiel `template_id`.
- Rendering van elk `data`-item tegen de actieve template.
- Samenvoegen van gerenderde pagina's tot één PDF binnen de limieten van het publieke endpoint.
- Gedeeld gedrag voor authenticatie, request-ID en foutenvelop.
Wat uw systeem beheert
- Templatekeuze, veldmapping, bedrijfsdata en autorisatie van aanroepende systemen.
- Publicatieproces voor templates, communicatie over wijzigingen en testdekking.
- Chunking, queueing en retries bij het renderen van veel documenten.
Productiechecklist
- Behandel `template_id` als een opaak stabiel contract.
- Valideer `data`-velden voordat u Template Render aanroept.
- Houd golden-PDF-tests bij voor de actieve template en representatieve data.
- Splits grote batches volgens de publieke Template Render-limieten.
- Log `template_id`, request-ID en de bedrijfsobject-ID's voor traceerbaarheid.
Grenzen van de claim
- Template Render is op zichzelf geen ontwerptool; templates moeten al gepubliceerd zijn.
- gPdf leidt ontbrekende bedrijfsdata niet af uit de template.
- Template Render vervangt het E-Invoice Render-endpoint niet.
Template Render is de productielaag voor contracten
JSON Render is ideaal terwijl de lay-out wordt ontworpen. Template Render is de
laag die u gebruikt nadat de lay-out een contract is geworden. Aanroepende
systemen sturen template_id en data; de actieve template beheert de
documentstructuur.
Zo blijven aanroepende systemen kleiner en worden templatewijzigingen eenvoudiger te reviewen, te testen en uit te rollen.
FAQ
- Wanneer gebruik ik Template Render in plaats van JSON Render?
- Gebruik Template Render nadat de lay-out is goedgekeurd en aanroepende systemen alleen bedrijfsdata moeten sturen.
- Is template_id stabiel?
- Ja. De documentatie voor de Template API beschrijft template_id als de stabiele identifier voor aanroepende systemen.
- Kan één request meerdere data-items renderen?
- Ja, Template Render accepteert een data-array binnen de limieten van het publieke endpoint.
- Kan Template Render e-invoices maken?
- Nee. Factur-X- en ZUGFeRD-PDF/A-3b-packaging gebruikt het E-Invoice Render-endpoint.