Rechnungs-PDF-API für Abrechnungs- und Finanzsysteme
Erzeugen Sie normale Rechnungs-PDFs aus Abrechnungsdaten mit JSON Render oder Template Render, während Steuer- und Buchhaltungslogik in Ihrem System bleibt.
/api/v1/pdf/render Rechnungsdaten aus einem Abrechnungs-, ERP- oder SaaS-System in eine lesbare PDF-Rechnung umwandeln, während Nummerierung, Steuer, Zahlungsstatus und Buchhaltungssemantik im aufrufenden System bleiben.
Wann diese API passt
- Sie benötigen normale Rechnungs-PDFs für Kunden, Belege, Kontoauszüge oder Buchhaltungsexporte.
- Ihr System besitzt Rechnungsnummern, Steuerberechnung, Positionen und Zahlungsstatus bereits.
- Sie möchten Tabellen, Summenblöcke, Metadaten und optionale PDF/A-Einstellungen ohne Browser betreiben.
- Sie möchten einen template_id-Vertrag für wiederkehrende Rechnungslayouts.
Was sie nicht ersetzt
- Sie benötigen ein rechtliches E-Rechnungspaket wie Factur-X oder ZUGFeRD. Nutzen Sie E-Invoice Render.
- Sie erwarten, dass gPdf Steuern berechnet, Buchhaltungsregeln validiert oder Zahlungen abstimmt.
- Sie möchten beliebige HTML-Rechnungen konvertieren statt strukturierter JSON-Daten oder Templates.
Welchen Endpoint aufrufen
/api/v1/pdf/render
JSON Render ist der Standardpfad für diesen Workflow.
/api/v1/template-render
Nutzen Sie dies, wenn der Workflow den zugehörigen API-Pfad, einen Template-Vertrag oder eine Capability-Abfrage braucht.
/api/v1/e-invoice/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/pdf/render - minimaler Rechnungskopf mit Summe.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
Was gPdf übernimmt
- Rechnungs-PDF-Rendering aus JSON-Seiten oder Template-Daten.
- Text, Tabellen, Summenblöcke, Paginierung, Metadaten und optionale PDF/A-Ausgabe.
- Template Render für stabile Rechnungslayouts, die mehrere Systeme nutzen.
- Binäre PDF-Antwort und konsistenter API-Fehlerumschlag.
Was Ihr System verantwortet
- Rechnungsnummern, Zahlungsstatus, Steuerberechnung, Rabatte, Gutschriften und Ledger-Bedeutung.
- Kunden- und Ausstellerdaten, Mapping der Positionen, Währungen und Rundungsregeln.
- Aufbewahrung, Zustellung, E-Mail, Zahlungslinks und Abgleich mit dem Buchhaltungssystem.
Produktions-Checkliste
- Bestätigen Sie, dass jedes sichtbare Rechnungsfeld auf Quell-Abrechnungsdaten gemappt ist.
- Testen Sie Positionsüberläufe, lange Kundennamen, mehrseitige Rechnungen und Summen.
- Entscheiden Sie, ob das Layout in JSON Render oder in eine veröffentlichte Vorlage gehört.
- Halten Sie normale Rechnungs-PDF-Erzeugung getrennt von rechtlicher E-Rechnungspaketierung.
- Speichern Sie Request-IDs und Ausgabedateinamen mit Ihren Rechnungsdatensätzen.
Aussagegrenzen
- Normale Rechnungs-PDFs sind nicht dasselbe wie gesetzliche E-Rechnungspflichten.
- gPdf rendert das Rechnungsdokument; es berechnet keine Steuer und keinen Buchhaltungsstatus.
- Factur-X- / ZUGFeRD-Ausgabe gehört auf POST /api/v1/e-invoice/render.
Normale Rechnungen versus E-Rechnungen
Ein normales Rechnungs-PDF ist das Dokument, das Ihr Kunde liest. Es kann mit JSON Render oder Template Render erzeugt werden. Ihr System entscheidet über Rechnungsnummer, Steuern, Positionen, Währung und Zahlungsstatus; gPdf rendert daraus das sichtbare PDF.
Eine rechtliche E-Rechnung ist etwas anderes. Factur-X und ZUGFeRD kombinieren
eine lesbare PDF/A-3b-Rechnung mit eingebettetem EN 16931 CII XML. Nutzen Sie
POST /api/v1/e-invoice/render für dieses Paket.
Template Render ist meist der Produktionsendpunkt
Finanzteams möchten selten, dass jeder Service Rechnungskoordinaten neu
aufbaut. Der übliche Weg ist, die Rechnung einmal zu gestalten, als Template zu
veröffentlichen und Aufrufern eine stabile template_id plus Datenschema zu
geben. JSON Render bleibt für individuelle Layouts, interne Tools und
Template-Prototyping nützlich.
Buchhaltungslogik bleibt upstream
gPdf sollte finale Anzeigewerte erhalten, keine ungeklärten Buchhaltungsentscheidungen. Berechnen Sie Steuern, Rabatte, Rundung, Zahlungsstatus und Rechnungsfähigkeit, bevor Sie die Render API aufrufen. So wird die PDF-Ausgabe deterministisch und das Finanzsystem bleibt die maßgebliche Quelle.
FAQ
- Ist ein Rechnungs-PDF dasselbe wie eine E-Rechnung?
- Nein. Ein normales Rechnungs-PDF ist menschenlesbare Ausgabe. Eine Factur-X- oder ZUGFeRD-E-Rechnung bettet zusätzlich EN 16931 CII XML in einen PDF/A-3b-Wrapper ein.
- Welchen Endpunkt sollten wiederkehrende Rechnungen nutzen?
- Nutzen Sie Template Render, wenn das Rechnungslayout stabil ist und Aufrufer nur template_id plus data senden sollen. Nutzen Sie JSON Render, wenn Code das Layout besitzt.
- Berechnet gPdf Steuern?
- Nein. Ihr Abrechnungs- oder Buchhaltungssystem berechnet Steuern, Summen, Rabatte und Zahlungsstatus, bevor es Renderdaten sendet.
- Können Rechnungs-PDFs PDF/A nutzen?
- Ja, JSON Render unterstützt PDF/A-Einstellungen. Nutzen Sie E-Invoice Render gezielt, wenn die Rechnung als Factur-X oder ZUGFeRD paketiert werden muss.