JSON-Schema der Vorlage

Aufbau einer Definition

Eine Vorlagendefinition ist ein Objekt mit zwei Teilen: page legt das Blatt fest, elements ist die geordnete Liste der darauf gezeichneten Elemente.

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

Seitengrößen: A4 · A3 · Letter. Die Ausrichtung ist portrait oder landscape; Ränder werden in CSS-Pixeln mit 96 Pixeln pro Zoll angegeben.

Welches Element welche Felder akzeptiert

Jedes Element enthält id, type, placementMode. Alles Weitere hängt vom Typ ab. Die folgende Tabelle wird aus denselben Regeln wie der Validator erzeugt und kann daher nicht hinter dem Produkt zurückbleiben.

Ein Feld, das nicht in der Zeile seines Typs steht, führt zu einem Validierungsfehler, statt ignoriert zu werden. Ein stillschweigend verworfenes Feld wäre schlimmer: Im Dokument fehlt etwas, obwohl die Anfrage erfolgreich wirkte.

placementMode

Wie ein Element seine Position auf dem Blatt erhält. Der Modus entscheidet auch, ob layout.x und layout.y überhaupt gelesen werden.

• flow — untereinander auf der Seite angeordnet; x und y werden ignoriert und das Element wächst mit seinem Inhalt
• free — an layout.x und layout.y platziert, genau an der festgelegten Stelle
• band — auf jeder Seite im angegebenen Bereich wiederholt, etwa in Kopf- oder Fußzeile

Das dataset-Element

Ein dataset gibt eine Sammlung ohne Tabelle aus: eine Liste von Besuchen, Fotos oder Unterschriften, die gemäß dem Vorlagenlayout statt in Spalten dargestellt wird.

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

binding bezeichnet wie bei einer Tabelle das Array in Ihren Daten. Was für jeden Eintrag gezeichnet wird, bestimmen Layout und Stil. Dieselbe Sammlung kann daher in einer Vorlage eine Tabelle und in einer anderen ein dataset sein.

Ein dataset hat kein content-Feld. Es wird nur über binding gespeist. Text im früheren content-Feld gelangte nie in die Ausgabe; das Feld wurde daher entfernt, statt als wirkungsloser Eingabeplatz bestehen zu bleiben.

Daten vor der Erstellung prüfen

Der Validierungsendpunkt beantwortet dieselbe Frage wie eine Erstellung, ohne Kontingent zu verbrauchen: Erfüllen die Daten die Anforderungen der Vorlage?

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

Häufige Fehler

• Ein Feld, das nicht zum Elementtyp gehört, verursacht einen Validierungsfehler statt ignoriert zu werden. Das ist beabsichtigt: Ein still verworfenes Feld erzeugt ein unvollständiges Dokument, und niemand sucht nach dem, was fehlt.
• Bei flow-Platzierung werden layout.x und layout.y gar nicht gelesen. Sie zu setzen und sich über fehlende Bewegung zu wundern ist die häufigste Schemafrage.
• Ein dataset hat kein content-Feld und wird nur über binding gespeist. Text in content erreicht die Ausgabe nie.
• Ränder und Größen sind CSS-Pixel mit 96 pro Zoll, keine Millimeter. Eine als Millimeter gedachte 20 erscheint dreimal zu klein.
• Eine Erstellung nur zur Datenprüfung kostet eine Seite. Der Validierungsendpunkt beantwortet dieselbe Frage kostenlos.