Workflow-Automatisierung # HTML skalierbar zu PDF konvertieren Erstellen Sie aus einer URL oder hochgeladenem HTML PDFs von Rechnungen, Berichten und Belegen, und sorgen Sie für reproduzierbare Ausgaben. Veröffentlicht am 13. August 2026 ## Wichtigste Erkenntnisse * Legen Sie für /html/convert das Format pdf fest; die anderen Formate erzeugen stattdessen Screenshots. * Steuern Sie mit wait\_until, wann der Snapshot erstellt wird, und verwenden Sie delay nur bei Bedarf. * Übermitteln Sie die Zugangsdaten zur Authentifizierung über Header, statt sie in die URL einzubetten. Die meisten PDF-Anforderungen beginnen mit einer Seite, die bereits im Browser korrekt dargestellt wird. Diese Seite serverseitig zu rendern ist in der Regel kostengünstiger, als ein zweites Layout in einer PDF-Bibliothek zu pflegen, sofern Zeitpunkt und Eingaben kontrolliert werden. ## In diesem Leitfaden 1. [Bereits vorhandene Seite rendern](#convert-html-to-pdf-section-1) 2. [Zeitpunkt des Snapshots steuern](#convert-html-to-pdf-section-2) 3. [Auf geschützte Seiten zugreifen, ohne Zugangsdaten offenzulegen](#convert-html-to-pdf-section-3) 4. [Neu ausgestelltes Dokument mit dem Original identisch halten](#convert-html-to-pdf-section-4) 5. [Rendering-Kosten planbar halten](#convert-html-to-pdf-section-5) 6. [Dokument prüfen, bevor Kunden es sehen](#convert-html-to-pdf-section-6) ## Worauf es besonders ankommt * Rendern Sie über eine stabile, versionierte Vorlagen-URL, damit eine Designänderung ein bereits ausgestelltes Dokument nicht verändern kann. * Führen Sie mehrteilige Dokumente mit /document/merge zusammen, statt PDFs selbst zu verketten. ## Bereits vorhandene Seite rendern Die meisten PDF-Anforderungen beginnen mit einer Seite, die bereits im Browser korrekt dargestellt wird: einer Rechnung, einem Kontoauszug oder einem Bericht. Ein zweites Layout in einer PDF-Bibliothek zu pflegen, verdoppelt diesen Aufwand und führt unweigerlich dazu, dass sich beide Versionen auseinanderentwickeln. Der Robot unter `/html/convert` rendert die Seite mit einem Headless-Browser und gibt das Ergebnis zurück. Die Einstellung `format: "pdf"` unterscheidet dabei ein Dokument von einem Screenshot. Derselbe Robot erzeugt auch `jpeg`, `jpg` und `png`. Dabei handelt es sich um Bilder der Seite und nicht um Dokumente mit Seitenaufteilung. Der Robot akzeptiert entweder eine zu rendernde `url` oder eine hochgeladene HTML-Datei. Für Dokumente, die bereits als Seiten vorliegen, ist das Rendern einer URL in der Regel die bessere Wahl, da so eine zentrale verlässliche Quelle erhalten bleibt. Das Hochladen von HTML eignet sich für Dokumente, die dynamisch erstellt werden und für die keine stabile URL vorhanden ist. Eine versionierte Rechnungs-URL als PDF rendern und das Ergebnis speichern ``` { "steps": { "rendered": { "robot": "/html/convert", "url": "https://example.com/inv/1043?v=3", "format": "pdf", "wait_until": "networkidle" }, "exported": { "use": "rendered", "robot": "/s3/store", "credentials": "my_s3_credentials", "path": "inv/1043.pdf" } } } ``` ### format: "pdf" Erzeugt das Dokument. Die anderen Formate erfassen stattdessen ein Bild der Seite. ### url oder Upload Rendern Sie eine vorhandene Seite anhand ihrer URL oder laden Sie generiertes HTML hoch, wenn keine stabile URL vorhanden ist. ### omit\_background Gilt nur für die Bildausgabe. Transparenz kann nicht in eine PDF-Datei übernommen werden. ## Zeitpunkt des Snapshots steuern Am häufigsten tritt der Fehler auf, dass ein Dokument beim manuellen Rendern korrekt aussieht, vom Robot jedoch nur halb leer ausgegeben wird, weil der Snapshot erstellt wurde, bevor die Schriftarten geladen waren oder ein Diagramm fertig gezeichnet war. `wait_until` entspricht dem Ladezustand des Browsers und drückt diese Abhängigkeit präzise aus. Mit dem richtigen Ladezustand lassen sich die meisten Timing-Probleme beheben, ohne eine feste Latenz hinzuzufügen. `delay` fügt danach eine feste Pause ein. Sie ist gelegentlich für Animationen oder Drittanbieter-Widgets erforderlich, die ihre Bereitschaft zu früh melden. Diese Pause fällt jedoch bei jedem einzelnen Render-Vorgang an, auch wenn sie nicht benötigt wird. Verwenden Sie zuerst ein spezifischeres `wait_until` und behandeln Sie `delay` als Ausweichlösung statt als Standard. ### wait\_until Drückt die tatsächliche Abhängigkeit vom Ladezustand des Browsers aus. Bevorzugen Sie diese Option. ### delay Eine feste Pause, die bei jedem Render-Vorgang anfällt. Verwenden Sie sie nur, wenn sich die Wartebedingung nicht durch einen Ladezustand ausdrücken lässt. ### Druck-Stylesheet Prüfen Sie die Seite in der Druckvorschau eines Browsers, bevor Sie sie serverseitig rendern. ## Auf geschützte Seiten zugreifen, ohne Zugangsdaten offenzulegen Da beim Rendern ein echter Browser ausgeführt wird, muss die Seite für Transloadit erreichbar sein. Dokumente liegen üblicherweise hinter einer Authentifizierung, sodass zwei praktikable Optionen bleiben. Der Parameter `headers` übermittelt die Authentifizierung mit der Anfrage und eignet sich damit für tokenbasierten Zugriff. Alternativ können Sie eine kurzlebige signierte URL ausstellen, die für einen kurzen Zeitraum Zugriff auf genau ein Dokument gewährt. Zugangsdaten sollten Sie keinesfalls in den Query-String der gerenderten URL aufnehmen. Solche URLs landen in Protokollen und im gespeicherten Datensatz des gerenderten Inhalts. Anders als ein Header lassen sie sich problemlos wiederverwenden, falls dieser Datensatz offengelegt wird. Authentifizierung mit einem Header statt mit einem Query-String ``` { "steps": { "rendered": { "robot": "/html/convert", "url": "https://example.com/reports/q3", "format": "pdf", "wait_until": "networkidle", "headers": [ "Authorization: Bearer ${fields.token}" ] } } } ``` ### headers Übermittelt Tokens mit der Anfrage statt in der URL, sodass sie nicht in Protokollen erscheinen. ### Signierte Einmal-URLs Gewährt für einen kurzen Zeitraum Zugriff auf ein einzelnes Dokument, wenn keine Header-Authentifizierung verfügbar ist. ### Niemals im Query-String Dort hinterlegte Zugangsdaten werden überall aufgezeichnet, wo die gerenderte URL gespeichert wird. ## Neu ausgestelltes Dokument mit dem Original identisch halten Eine Rechnung ist ein Dokument für rechtliche Zwecke, und die Version, die ein Kunde im März erhält, sollte im November noch identisch gerendert werden. Zwei Vorgehensweisen gewährleisten das. Rendern Sie über eine versionierte Vorlagen-URL, damit eine spätere Designänderung ein bereits ausgestelltes Dokument nicht verändern kann, und speichern Sie die resultierende Datei, statt sie bei Bedarf neu zu erzeugen. Aus mehreren Teilen zusammengesetzte Dokumente sollten Sie ausdrücklich als solche verarbeiten. `/document/merge` führt gerenderte Seiten innerhalb derselben Assembly zu einer Datei zusammen. So bleibt ihre Reihenfolge deterministisch und Sie vermeiden einen zweiten Dienst, der Zugriff auf die einzelnen Teile benötigt. Mehrteilige Dokumente innerhalb einer Assembly zusammenführen ``` { "steps": { "cover": { "robot": "/html/convert", "url": "https://example.com/stmt/cover?v=3", "format": "pdf", "wait_until": "networkidle" }, "detail": { "robot": "/html/convert", "url": "https://example.com/stmt/detail?v=3", "format": "pdf", "wait_until": "networkidle" }, "statement": { "use": ["cover", "detail"], "robot": "/document/merge" } } } ``` ### Vorlage versionieren Eine Designänderung sollte neue Dokumente erzeugen und nicht bereits ausgestellte Dokumente rückwirkend verändern. ### Speichern statt neu generieren Bewahren Sie die erzeugte Datei auf, damit eine erneute Ausgabe als Kopie statt durch neues Rendern erfolgt. ### /document/merge Führt mehrteilige Dokumente in einer Assembly mit deterministischer Reihenfolge zusammen. ## Rendering-Kosten planbar halten Das Rendern einer Seite ist aufwendiger als eine Formatkonvertierung, da dabei ein Browser gestartet wird, Unterressourcen abgerufen werden und auf den stabilen Zustand der Seite gewartet wird. Dieser Aufwand ist für ein von einem Kunden angefordertes Dokument angemessen, aber unnötig, wenn derselbe Kontoauszug jedes Mal neu gerendert wird, sobald jemand eine Listenansicht öffnet. Üblicherweise rendern Sie das Dokument daher einmal bei seiner Finalisierung und liefern anschließend die gespeicherte Datei aus. Die Massengenerierung sollte separat behandelt werden. Ein Monatsendlauf, der Tausende Kontoauszüge erzeugt, sollte nicht mit einem Render-Vorgang konkurrieren, auf den ein Kunde wartet. Zudem summiert sich ein festes `delay` in einem solchen Batch zu erheblichem Zeit- und Kostenaufwand. Wenn Sie die Kosten pro ausgestelltem Dokument statt pro Assembly messen, werden solche Muster meist schnell sichtbar. ### Bei der Finalisierung rendern Erzeugen Sie die Datei bei der Finalisierung des Dokuments und nicht bei jedem Aufruf. ### Massenläufe trennen Trennen Sie Monatsend-Batches von Render-Vorgängen, auf die eine Person wartet. ### Feste Verzögerungen prüfen Eine Pause von 1 Sekunde fällt einmal nicht auf, verursacht bei zehntausend Dokumenten jedoch hohe Kosten. ## Dokument prüfen, bevor Kunden es sehen Ein Render-Vorgang kann erfolgreich sein und dennoch ein falsches Ergebnis liefern. Der Robot gibt unabhängig davon, ob das Diagramm gezeichnet wurde, eine gültige PDF-Datei zurück. Eine Prüfung, die nur ermittelt, ob eine Datei erzeugt wurde, erkennt daher keine leere Seite. Einfache Plausibilitätsprüfungen decken die meisten Fehler ab: eine realistische Bytegröße, die erwartete Seitenzahl und das Vorhandensein einer bekannten Zeichenfolge wie der Dokumentnummer. Wenn Sie während der Entwicklung neben dem PDF auch in `png` rendern, erhalten Sie eine schnelle visuelle Kontrolle, die sich bei der Prüfung leicht mit bloßem Auge durchführen lässt. Der Vergleich eines neuen Renderings mit einem gespeicherten Referenzbild deckt zudem Layoutregressionen auf, die sich durch eine Prüfung der Bytegröße nicht erkennen lassen. Beides gehört nicht in den Produktionspfad, ist aber für die Pipeline sinnvoll, mit der Vorlagenänderungen ausgeliefert werden. ### Inhalt statt Existenz prüfen Prüfen Sie die Seitenzahl und einen bekannten Identifikator, statt nur festzustellen, ob eine Datei vorhanden ist. ### Bild-Renderings zur Prüfung erzeugen Ein `png` derselben Seite macht Vorlagenänderungen auf einen Blick überprüfbar. ### Mit einer Referenz vergleichen Ein visueller Vergleich deckt Layout-Regressionen auf, die bei Größenprüfungen unentdeckt bleiben. ## Wissenswerte technische Details * Der Parameter format akzeptiert jpeg, jpg, pdf und png. Nur pdf erzeugt ein Dokument; die übrigen Formate erfassen ein Bild der Seite. * Der Parameter omit\_background gilt für die Bildausgabe und hat keine Auswirkung, wenn format auf pdf gesetzt ist. Transparenz kann daher nicht in das Dokument übernommen werden. * Der Parameter wait\_until entspricht dem zugrunde liegenden Ladezustand des Browsers. Damit lässt sich zuverlässig warten, bis Schriftarten, Diagramme und spät geladene Daten verfügbar sind, bevor der Snapshot erstellt wird. * Der Parameter delay fügt eine feste Pause ein, nachdem der Ladezustand erreicht wurde. Dieses grobe Mittel erhöht bei jedem Rendern die Kosten und Latenz. Verwenden Sie daher nach Möglichkeit einen spezifischeren Wert für wait\_until. * Eine gerenderte Rechnung ist ein Dokument für rechtliche Zwecke. Wenn Sie über eine unveränderliche Vorlagen-URL rendern und die resultierende Datei speichern, statt sie bei Bedarf neu zu erzeugen, bleibt eine erneut ausgestellte Kopie mit dem Original identisch. * Da das Rendering in einem echten Browser erfolgt, muss die Seite für Transloadit erreichbar sein. Seiten, die durch ein Session-Cookie geschützt sind, benötigen entweder eine signierte Einmal-URL oder Zugangsdaten, die über den Parameter headers übergeben werden. ## Ein praxisnaher Ansatz 1. 1\ Erstellen Sie das Dokument als normale Seite mit einem Druck-Stylesheet und überprüfen Sie es zunächst in einem Browser. 2. 2\ Rendern Sie es mit /html/convert im Format pdf und einem explizit angegebenen wait\_until. 3. 3\ Speichern Sie das Ergebnis zusammen mit den zugehörigen Identifikatoren in Ihrem eigenen Bucket. 4. 4\ Führen Sie unterstützende Seiten mit /document/merge zu einer Datei zusammen, wenn das Dokument aus mehreren Teilen besteht. Ein vierstufiger Medien-Workflow ## Wann Transloadit hilfreich ist Verwenden Sie /html/convert mit dem Format pdf, wenn das Dokument bereits als Webseite vorliegt oder als solche gerendert werden kann. Geben Sie eine url an, oder laden Sie HTML hoch und lassen Sie den Robot die hochgeladene Datei rendern. Kombinieren Sie den Robot mit /document/merge, wenn mehrere Seiten in eine Datei gehören. ## Architekturgrenze /html/convert rendert eine Seite mit einem Headless-Browser und erzeugt daher eine paginierte visuelle Kopie statt einer barrierefreien PDF-Datei mit Tags. Dokumente, die eine auswählbare Struktur, Formularfelder oder Langzeitarchivformate wie PDF/A benötigen, sollten mit einem speziellen Dokumentgenerator erstellt werden. ## Häufig gestellte Fragen ### Warum fehlen in meiner PDF-Datei Diagramme oder Schriftarten? Der Snapshot wurde mit ziemlicher Sicherheit erstellt, bevor diese Inhalte vollständig geladen waren. Setzen Sie `wait_until` auf einen Ladezustand, der die Abhängigkeit abdeckt. Fügen Sie `delay` nur hinzu, wenn sich dies nicht durch einen Ladezustand ausdrücken lässt. Beachten Sie dabei, dass die Pause bei jedem Rendern berechnet wird. ### Kann ich eine PDF-Datei mit transparentem Hintergrund erstellen? Nein. `omit_background` wirkt sich auf die Bildausgabe aus und hat keine Wirkung, wenn `format` auf `pdf` gesetzt ist. Wenn Transparenz erforderlich ist, rendern Sie stattdessen als `png` und fügen Sie dieses Bild in ein Dokument ein. ### Wie rendere ich eine Seite, für die eine Anmeldung erforderlich ist? Übergeben Sie die Authentifizierung über den Parameter `headers` oder verwenden Sie eine kurzlebige signierte URL, deren Berechtigungsumfang auf das einzelne Dokument beschränkt ist. Platzieren Sie keine Zugangsdaten im Query-String, da die gerenderte URL überall dort aufgezeichnet wird, wo das Rendern protokolliert wird. ### Ist die Ausgabe eine barrierefreie PDF-Datei mit Tags? Nein. Ein Headless-Browser erzeugt eine paginierte visuelle Kopie und kein Dokument mit Tags, Lesereihenfolge, Formularfeldern oder PDF/A-Konformität. Für solche Anforderungen ist statt des Renderns einer Seite ein spezieller Dokumentgenerator erforderlich. ### Wie führe ich mehrere gerenderte Seiten in einer Datei zusammen? Rendern Sie jeden Teil und übergeben Sie die Ergebnisse innerhalb derselben Assembly an /document/merge. Wenn die Zusammenführung in der Assembly erfolgt, bleibt die Reihenfolge deterministisch und kein weiterer Dienst muss Zugriff auf die einzelnen Teile erhalten. ## Erstellen Sie den Workflow Entwickeln Sie das Konzept mithilfe der Robot-Dokumentation und funktionsfähiger Demos zu einer getesteten Assembly weiter. ### Relevante Robots * [/html/convert](/de/docs/robots/html-convert.md) * [/document/merge](/de/docs/robots/document-merge.md) * [Lesen Sie die API-Dokumentation](/de/docs.md) * [Entdecken Sie funktionsfähige Demos EN (English)](/demos.md) * [Kostenlosen Workspace erstellen](/c/signup/) Workflow-Automatisierung ## Mit verwandten Leitfäden fortfahren * [Medienautomatisierung: vom Upload zur zuverlässigen Ausgabe](/de/guides/media-automation.md)\ Automatisieren Sie wiederholbare Medienaufnahme, Transformation, Validierung und Export, ohne Beobachtbarkeit und Kontrolle einzuschränken. * [Vollständiger Leitfaden für Digital-Asset-Workflows](/de/guides/digital-asset-workflows.md)\ Gestalten Sie einen Digital-Asset-Workflow von Aufnahme und Verarbeitung über Prüfung und Veröffentlichung bis zu Aufbewahrung und Löschung. * [KI-Inhaltsmoderation in einem Upload-Workflow](/de/guides/ai-content-moderation-workflows.md)\ Integrieren Sie KI-Moderation mit Konfidenzschwellen und menschlicher Prüfung in einen kontrollierten Upload-Workflow. * [Automatisierte Inhaltsmoderation: Aufbau und Fehlerbehandlung](/de/guides/automated-content-moderation.md)\ Erstellen Sie automatisierte Moderation als mehrschichtiges System aus Dateiprüfungen, Klassifikatoren, Richtlinienentscheidungen und Prüfwarteschlangen. * [Automatisierte Bildanalyse mit beobachtbaren Workflows](/de/guides/automated-image-analysis.md)\ Gestalten Sie die Bildanalyse als wiederholbaren, asynchronen Workflow statt als blockierende Anfrage Ihrer Anwendung.