PDF Generation API Dokumentation

Diese API wandelt eine angegebene URL in ein PDF um. Sende einen POST-Request an / mit einem JSON-Body.

Erforderliche Parameter

CallbackUrl Variante

Wenn im Request der optionale Parameter callbackUrl angegeben wird, ändert sich das Verhalten der API wie folgt:

• Sofortige Antwort: Der Service liefert sofort ein JSON-Objekt zurück, das eine zufällig generierte, 20-stellige ID enthält. Beispiel:

  {
    "id": "YbXwo7hmnMnw0zot49q1"
  }

• Asynchrone Verarbeitung: Die PDF-Erstellung erfolgt im Hintergrund und durchläuft folgende Stufen:
  • Retrieving webpage: Die angegebene URL wird mit Puppeteer geladen.
  • Converting to PDF: Die Webseite wird in ein PDF konvertiert.
  • Compressing: Das PDF wird mittels Ghostscript weiterverarbeitet.
  Der aktuelle Status und die jeweilige Stufe werden im globalen Job-Store gespeichert.
• Callback-Benachrichtigung: Sobald die Verarbeitung abgeschlossen ist – entweder erfolgreich oder mit Fehlern – wird die angegebene callbackUrl per HTTP-POST aufgerufen. Im Body des Requests werden die ID (und im Fehlerfall auch eine Fehlermeldung) übermittelt.
• /retrieve-Endpoint:
  • Bei laufender Verarbeitung: Gibt der /retrieve-Endpoint ein JSON-Objekt zurück, das den aktuellen Status und die Stufe (z.B. "retrieving webpage", "converting to PDF", "compressing") enthält.

    {
      "info": "Processing in progress: converting to PDF"
    }

  • Bei erfolgreichem Abschluss: Gibt der /retrieve-Endpoint die PDF als Datei (mit dem ursprünglich generierten Dateinamen) zurück. Danach wird der Eintrag aus dem Job-Store gelöscht.
  • Bei Fehlern: Gibt der /retrieve-Endpoint ein JSON-Objekt mit der Fehlermeldung zurück und löscht den Eintrag aus dem Job-Store.

  Sicherheit: Vor der Bearbeitung prüft der /retrieve-Endpoint, ob ein gültiger API-Key übermittelt wurde. Informationen zum Status können beliebig oft abgefragt werden, bis die PDF abgerufen oder ein Fehler gemeldet wurde.

CallbackUrl Parameter

Pagination Variante

Mit der Option substitutePageNumbers wird der PDF-Export in zwei Durchgängen durchgeführt, um ein interaktives Inhaltsverzeichnis zu erzeugen:

• Erster Durchlauf: Die Webseite wird in ein PDF umgewandelt. Dabei werden unsichtbare Marker in den Elementen eingefügt, die das Attribut data-pagemarker besitzen. Diese Marker enthalten einen eindeutigen Identifikator, z. B. %%MARKER:chapter1%%, und sind für den Nutzer unsichtbar.
• Analyse und Aktualisierung: Anschließend wird das PDF analysiert, um exakt zu ermitteln, auf welcher Seite jeder Marker erscheint. Auf Basis dieser Informationen wird der Inhaltsverzeichnisbereich der Webseite aktualisiert:
  Elemente mit dem Attribut data-pagetarget werden mit den ermittelten Seitenzahlen befüllt. Je nach Einstellung von substitutePageNumbers ergeben sich folgende Varianten:
  • "substitute": Es werden lediglich die Platzhalter in den data-pagetarget-Elementen durch die ermittelten Seitenzahlen ersetzt.
  • "navigatePageOnly": Neben der Ersetzung wird das data-pagetarget-Element direkt in einen klickbaren Link umgewandelt.
  • "navigate": Zusätzlich zur direkten Umwandlung wird rekursiv nach einem übergeordneten Element gesucht, das das Attribut data-navigation trägt. Ist ein solches Element vorhanden, so wird dieses als klickbarer Navigationslink verwendet – der ursprüngliche Inhalt bleibt erhalten.
• Zweiter Durchlauf: Nachdem die Seite dynamisch aktualisiert wurde, erfolgt ein erneuter PDF-Export. Das finale PDF enthält nun das vollständig ausgefüllte und interaktive Inhaltsverzeichnis.

Dieses Verfahren ermöglicht eine exakte, formatunabhängige Bestimmung der Seitenzahlen, da die Analyse direkt auf dem generierten PDF basiert. So wird sichergestellt, dass selbst bei wechselnden Formaten oder Orientierungen das Inhaltsverzeichnis korrekt und interaktiv ist.

Sollte kein marker gefunden werden, wird dieser Vorgang in Millisekunden übersprungen und kann üblicherweise deshalb aktiv bleiben.

Pagination Parameter

Parts Variante

Mit der Option parts kann angegeben werden, dass der Endpunkt (die URL) einen part=X Parameter akzeptiert. Bei parts > 1 wird die URL nacheinander mit part=1, part=2, etc. aufgerufen, jeder Part wird in eine separate PDF umgewandelt und anschließend zu einem einzigen Dokument zusammengefügt. Beim Zusammenfügen bleiben Inhaltsverzeichnis und Bookmarks erhalten; Seitenzahlen werden allerdings stets nur innerhalb eines Parts gezählt (Part 2 und weitere fangen für sich wieder bei 1 an zu zählen).

Parts Parameter

DisplayHeader und DisplayFooter Parameter

Wichtig: Damit Header oder Footer überhaupt verarbeitet werden, muss displayHeaderFooter (Puppeteer-Parameter) auf true gesetzt sein. Dieser ist standardmäßig aus.

PaperBehavior Parameter

Background Parameter

Attachment Parameter

Puppeteer-Parameter

Ghostscript-Parameter

Details aus der Ghostscript-Dokumentation

(note 0) This parameter can be set and queried, but currently has no effect.

(note 1) AutoFilterxxxImages doesn't examine the image to decide between JPEG and LZW or Flate compression: it uses JPEG compression if the image has 8 bits per component and does not use an Indexed color space, and LZW or Flate compression otherwise.

(note 2) Because of Unisys's threats regarding the Welch patent, ps2pdf cannot actually use LZW compression: instead, it treats all requests for LZW compression as calling for Flate compression if UseFlateCompression is true and CompatibilityLevel >= 1.2, and ignores them otherwise.

(note 3) The xxxDownsampleType parameters can also have the value /Bicubic (a Distiller 4 feature), which is currently treated as equivalent to /Average.

(note 4) Currently, the transfer function is always applied. If the corresponding parameter is set to /Preserve, the function setting is also copied into the PDF file.

(note 5) Optimization (linearization) is implemented with a separate program, pdfopt input.pdf output.pdf; the Optimize parameter has no effect.

(note 6) Currently, colors for images and shadings are left in the color space specified in the PostScript input, except for ConvertCMYKImagesToRGB; the current color in the graphics state (used for fill, stroke, text, and imagemask) is always converted to the color space specified by the current value of ProcessColorModel. The intended behavior is the same as for Acrobat Distiller, except that if ColorConversionStrategy is set to /UseDeviceDependentColor, colors are converted to the color space specified by ProcessColorModel rather than always to /DeviceRGB.

(note 7) The default image parameter dictionary is:
    << /QFactor 0.9 /Blend 1 /HSamples [2 1 1 2] /VSamples [2 1 1 2] >>

(note 8) The printer ACS image parameter dictionary is:
    << /QFactor 0.55 /Blend 1 /HSamples [2 1 1 2] /VSamples [2 1 1 2] >>

(note 9) The prepress ACS image parameter dictionary is:
    << /QFactor 0.25 /HSamples [1 1 1 1] /VSamples [1 1 1 1] >>

Limitations:
- ps2pdf will sometimes convert text to high-resolution bitmapped fonts rather than to embedded outline fonts. This occurs for Type 3, CIDFontType 1, or CIDFontType 4 fonts, or Type 0 fonts referencing these; it may also occur with fonts using non-standard encodings.
- The PDF output always represents text and graphics colors in DeviceGray or DeviceRGB (or DeviceCMYK if ProcessColorModel is /DeviceCMYK); all other color spaces are converted.
- ps2pdf may convert PostScript constructs to lower-level ones even if higher-level constructs are available (e.g., using charpath for clipping), affecting performance.
- Some PostScript files (e.g., from HIGZ) may trigger a limitcheck error due to extremely large coordinates; reducing the internal resolution with -r (e.g., -r300) may help.
- ps2pdf ignores certain PDF 1.3 pdfmarks related to document structure.
- ps2pdf currently has very limited support for PDF 1.4 transparency features.
- Known problems include issues with saving/restoring Distiller parameters and potential crashes if CompressPages is changed after marks are made.
- Incremental downloading of Type 1 fonts may result in embedded fonts missing FontDescriptor information, potentially causing crashes in Acrobat Reader 4 or incorrect spacing.
  

Beispiel

Ein typischer JSON-Body für einen POST-Request. Im Beispiel werden nur Werte gesetzt, die von den Standardwerten abweichen.

{
  "apiKey": "YOUR_API_KEY",
  "url": "https://example.com",
  "callbackUrl": "https://your-callback-url.com/notify",
  "landscape": true,
  "gs_option_set": "printer",
  "gs_DownsampleColorImages": true,
  "gs_resolution": 300,
  "gs_ProcessColorModel": "/DeviceGray"
}

Weitere Details zu den PDF-Optionen findest du in der Puppeteer PDF Options Dokumentation und zu den Ghostscript-Optionen in der Ghostscript Ps2pdf Options Dokumentation.

* = Erforderlicher Parameter