Ist das eine HTML-to-PDF API?

Nein. gPdf akzeptiert einen strukturierten JSON DocumentRequest mit Seiten, Elementen, Koordinaten und Einstellungen. Es führt keinen Browser aus und verarbeitet kein beliebiges HTML/CSS.

Welchen Endpunkt sollte ich zuerst aufrufen?

Starten Sie mit POST /api/v1/pdf/render, wenn Sie direkte Layout-Kontrolle möchten. Wechseln Sie zu POST /api/v1/template-render, wenn das Layout ein stabiler template_id-Vertrag werden soll.

Gibt die API direkt ein PDF zurück?

Ja. Ein erfolgreicher Render gibt application/pdf zurück. Fehler nutzen das gemeinsame JSON-Fehler-Envelope mit API-XXX-Code und req_id.

Kann ich ohne Integration testen?

Nutzen Sie den gPdf Playground, um JSON-Payloads interaktiv zu testen, und übertragen Sie anschließend dieselbe DocumentRequest-Form in Ihren Backend-Client.

Entwickler-Workflows

JSON-zu-PDF API für strukturierte Dokumentgenerierung

Wandeln Sie strukturierte JSON DocumentRequest-Payloads in PDFs mit Seiten, Koordinaten, Text, Tabellen, Barcodes, Metadaten und PDF/A-Einstellungen um.

PRIMÄRE API JSON Render

ENDPOINT /api/v1/pdf/render

SYSTEME SaaS-Backend / API-Worker / AI Agent / Job-Queue

Im Playground testen Dokumentation lesen

Aufgabe im Workflow

Wandeln Sie strukturierte Anwendungsdaten in deterministische PDF-Dokumente um, ohne Browser zu betreiben, HTML/CSS auszuliefern oder Kundendateien zu speichern. Ihr System sendet Seiten, Elemente, Koordinaten, Einstellungen und Geschäftsinhalte; gPdf gibt eine application/pdf-Antwort zurück.

Wann diese API passt

Ihr Backend hat bereits strukturierte Daten und benötigt eine PDF-Antwort.
Sie möchten explizite Seiten, Koordinaten, Elemente, Barcodes und Einstellungen statt HTML-Layout.
Sie benötigen wiederholbare Ausgabe für Rechnungen, Labels, Berichte, Kontoauszüge oder generierte Dokumentpakete.
Sie möchten Payloads im Playground testen, bevor ein Token in Produktion verwendet wird.

Was sie nicht ersetzt

Sie benötigen beliebige HTML-zu-PDF-Konvertierung. gPdf nutzt DocumentRequest JSON, kein Browser-DOM.
Ihr Team möchte einen stabilen template_id-Vertrag. Nutzen Sie Template Render, nachdem das Layout veröffentlicht wurde.
Sie benötigen Factur-X- oder ZUGFeRD-E-Invoice-Paketierung. Nutzen Sie den E-Invoice Render-Endpunkt.

Welchen Endpoint aufrufen

PRIMÄR

/api/v1/pdf/render

JSON Render ist der Standardpfad für diesen Workflow.

SEKUNDÄR 1

/api/v1/template-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 - einseitiger JSON DocumentRequest.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Hello from gPdf",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        }
      ]
    }
  ]
}

Was gPdf übernimmt

DocumentRequest-Rendering aus Seiten und Elementen.
Text, Tabellen, Bilder, Vektor-Barcodes, Linien, Formen, Wasserzeichen, Metadaten und PDF/A-Einstellungen.
Font-Einbettung und Fallback für Latin, CJK, emoji-fähige und andere unterstützte Schriften.
Binäre PDF-Antwort mit gemeinsamem gPdf Fehlercode-Envelope bei Fehlern.

Was Ihr System verantwortet

Geschäftsdaten, Feldmapping und Dokumentsemantik.
Request IDs, Retry- und Idempotenzstrategie, Dateinamen und Speicherung nach der Antwort.
Alle Steuer-, Rechnungs-, Carrier-, Compliance- oder kundenspezifischen Regeln vor dem Rendering.

Produktions-Checkliste

Erzeugen und übergeben Sie ein X-Request-Id für Nachvollziehbarkeit.
Validieren Sie Payloads gegen OpenAPI oder Docs, bevor Sie Live-Traffic senden.
Halten Sie die API-Basis-URL konfigurierbar und speichern Sie den Bearer Token außerhalb des Quellcodes.
Entscheiden Sie, ob Ihre Ausgabe im Inline- oder Attachment-Modus erfolgen soll.
Ergänzen Sie Golden-PDF-Tests für kritische Layouts, damit Template- oder Datenänderungen sichtbar werden.

Aussagegrenzen

Dies ist kein HTML-to-PDF und führt kein Chromium aus.
Die API rendert das Dokument, das Sie beschreiben; sie leitet keine rechtliche oder geschäftliche Bedeutung aus Ihren Daten ab.
Für wiederholte Layouts ist Template Render meistens der bessere öffentliche Vertrag.

Wie der JSON Render-Workflow passt

JSON Render ist der niedrigste öffentliche Rendering-Pfad. Ihre Anwendung sendet die Dokumentstruktur direkt: Seitengröße, Elemente, Koordinaten, Styling, Metadaten, Ausgabemodus und optionale PDF/A-Einstellungen. Diese Ebene passt, wenn das Dokumentlayout durch Code erzeugt wird oder Ihr Team pixelgenaue Kontrolle über das PDF benötigt.

Der API-Vertrag ist explizit. Wenn Ihr System ein Textelement sendet, rendert gPdf ein Textelement. Wenn es ein Barcode-Element sendet, zeichnet gPdf den Barcode als Vektor-PDF-Inhalt. gPdf liest keine Geschäftsabsicht aus dem Payload und entscheidet nicht, ob eine Rechnungsnummer, ein Carrier-Tracking-Wert oder ein Steuerfeld korrekt ist.

Wann Sie zu Template Render wechseln

Wenn dasselbe Layout wiederholt über Systeme hinweg genutzt wird, veröffentlichen Sie es als Vorlage und rufen POST /api/v1/template-render mit template_id plus data[] auf. So liegt Layout-Verantwortung nicht mehr bei jedem Aufrufer, und ERP, OMS, WMS oder SaaS-Backend erhalten einen stabilen Feldvertrag.

Nutzen Sie JSON Render für Layout-Erstellung, Einzeldokumente und programmatisch erzeugte Dokumente. Nutzen Sie Template Render, wenn das Layout feststeht und sich pro Request nur Geschäftsdaten ändern.

Produktionsform

Behandeln Sie einen PDF-Request in Produktion wie jeden anderen wichtigen API-Aufruf: Request ID mitsenden, Timeout setzen, Retries idempotent machen, Response-Metadaten protokollieren und das zurückgegebene PDF nur in Ihrem eigenen System speichern, wenn Aufbewahrung erforderlich ist. Der gPdf Render-Pfad ist nach einer Standard-Render-Antwort zustandslos.

FAQ

Ist das eine HTML-to-PDF API?: Nein. gPdf akzeptiert einen strukturierten JSON DocumentRequest mit Seiten, Elementen, Koordinaten und Einstellungen. Es führt keinen Browser aus und verarbeitet kein beliebiges HTML/CSS.
Welchen Endpunkt sollte ich zuerst aufrufen?: Starten Sie mit POST /api/v1/pdf/render, wenn Sie direkte Layout-Kontrolle möchten. Wechseln Sie zu POST /api/v1/template-render, wenn das Layout ein stabiler template_id-Vertrag werden soll.
Gibt die API direkt ein PDF zurück?: Ja. Ein erfolgreicher Render gibt application/pdf zurück. Fehler nutzen das gemeinsame JSON-Fehler-Envelope mit API-XXX-Code und req_id.
Kann ich ohne Integration testen?: Nutzen Sie den gPdf Playground, um JSON-Payloads interaktiv zu testen, und übertragen Sie anschließend dieselbe DocumentRequest-Form in Ihren Backend-Client.