Template PDF API für stabile Dokumentverträge
Rendern Sie PDFs aus einer stabilen template_id und einem data-Array, wenn wiederholte Layouts einmal gepflegt und von ERP, OMS, WMS oder SaaS-Aufrufern wiederverwendet werden sollen.
/api/v1/template-render Rendern Sie wiederholte PDFs, indem Sie eine stabile template_id und ein Geschäftsdaten-Array senden, statt jeden Aufrufer bei jedem Request Seiten, Koordinaten und Layout-Elemente beschreiben zu lassen.
Wann diese API passt
- Das Dokumentlayout ist freigegeben und wird von mehreren Aufrufern oder Jobs wiederverwendet.
- Aufrufer sollen Geschäftsdaten senden, kein koordinatengenaues Layout-JSON.
- Sie benötigen Rechnungs-, Packlisten-, Versandlabel- oder Custom-Template-Ausgabe.
- Aktive Template-Revisionen sollen außerhalb des Aufrufers gesteuert werden.
Was sie nicht ersetzt
- Sie entwerfen das Layout noch. Nutzen Sie JSON Render, bis Koordinaten und Felder stabil sind.
- Sie benötigen beliebige HTML-to-PDF-Konvertierung.
- Sie benötigen E-Invoice-PDF/A-3b-Paketierung mit eingebettetem CII XML.
Welchen Endpoint aufrufen
/api/v1/template-render
Template Render ist der Standardpfad für diesen Workflow.
/api/v1/pdf/render
Nutzen Sie dies, wenn der Workflow den zugehörigen API-Pfad, einen Template-Vertrag oder eine Capability-Abfrage braucht.
Minimaler Request
POST /api/v1/template-render - eine Rechnung aus einer Vorlage rendern.
{
"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"
}
]
}
]
}
Was gPdf übernimmt
- Template-Lookup über stabile template_id.
- Rendering jedes data-Elements gegen die aktive Vorlage.
- Zusammenführen gerenderter Seiten zu einem einzelnen PDF innerhalb öffentlicher Endpunktlimits.
- Gemeinsames Authentifizierungs-, Request-ID- und Fehler-Envelope-Verhalten.
Was Ihr System verantwortet
- Template-Auswahl, Feldmapping, Geschäftsdaten und Aufrufer-Autorisierung.
- Template-Veröffentlichungsworkflow, Änderungsankündigung und Testabdeckung.
- Chunking, Queueing und Retries beim Rendern vieler Dokumente.
Produktions-Checkliste
- Behandeln Sie template_id als opaken, stabilen Vertrag.
- Validieren Sie data-Felder, bevor Sie Template Render aufrufen.
- Pflegen Sie Golden-PDF-Tests für die aktive Vorlage und repräsentative Daten.
- Teilen Sie große Batches gemäß den öffentlichen Template Render-Limits auf.
- Protokollieren Sie template_id, Request ID und die IDs der Geschäftsobjekte für Nachvollziehbarkeit.
Aussagegrenzen
- Template Render ist für sich genommen kein Design-Tool; Vorlagen müssen bereits veröffentlicht sein.
- gPdf leitet fehlende Geschäftsdaten nicht aus der Vorlage ab.
- Template Render ersetzt nicht den E-Invoice Render-Endpunkt.
Template Render ist die Vertragsebene für Produktion
JSON Render ist ideal, während ein Layout entworfen wird. Template Render ist die
Ebene, die Sie nutzen, nachdem das Layout zum Vertrag geworden ist. Aufrufer
senden template_id und Daten; die aktive Vorlage besitzt die Dokumentstruktur.
Dadurch bleiben Aufrufer kleiner, und Template-Änderungen lassen sich einfacher prüfen, testen und ausrollen.
FAQ
- Wann sollte ich Template Render statt JSON Render nutzen?
- Nutzen Sie Template Render, nachdem das Layout freigegeben ist und Aufrufer nur noch Geschäftsdaten senden sollen.
- Ist template_id stabil?
- Ja. Die Template API Docs beschreiben template_id als stabilen, aufruferseitigen Identifier.
- Kann ein Request mehrere data-Elemente rendern?
- Ja. Template Render akzeptiert innerhalb der öffentlichen Endpunktlimits ein data-Array.
- Kann Template Render E-Rechnungen erzeugen?
- Nein. Factur-X- und ZUGFeRD-PDF/A-3b-Paketierung nutzt den E-Invoice Render-Endpunkt.