Datenformate

Hier erfahren Sie, in welcher Form Ihre Daten ankommen müssen. PDFgine gibt den übermittelten Wert nicht unverändert aus, sondern wendet den in der Vorlage festgelegten Formatierer in der Dokumentsprache an.

In einem Satz: Daten kommen unverändert an, PDFgine formatiert sie. Bei vorformatierten Werten liest sich das Dokument in einer Sprache richtig und in der anderen falsch.

Ein Formatierer wird an drei Stellen festgelegt: im Feld „format“ einer Tabellenspalte und einer Summenzeile, unter „dataRules.formatter“ eines Elements mit einem Einzelwert und mit den Funktionen format_date und format_money in Texten, die mehrere Felder verbinden.

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "Unternehmenswebsite", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// Auf Vorlagenseite:
// Tabellenspalte:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// Datumsspalte:    "format": { "kind": "date", "dateStyle": "short" }
// Textelement:   "{{ referenceNo }} · {{ format_date issueDate }}"

Auch IBAN, Telefon- und Steuernummern werden in kanonischer Form übermittelt: IBAN ohne Leerzeichen, Telefonnummer im E.164-Format (+442071838750). Gruppierungen gehören zur Darstellung und nicht in die Daten.

Der Name des heruntergeladenen Dokuments

Ein heruntergeladenes Dokument heißt „{document type} - {counterparty} - {reference no}“. Die drei Teile stammen aus den gesendeten Daten: document.title, customer und referenceNo. Fehlende Teile werden ausgelassen. Lässt sich daraus kein brauchbarer Name bilden, wird die Dokumentkennung verwendet, zum Beispiel quote-doc_94812af2.pdf.

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

Der Name steht zweimal im selben Header. Das erweiterte Feld bewahrt die Dokumentsprache; das klassische Feld enthält eine lesbare ASCII-Fassung für Clients, die das erweiterte Feld nicht lesen können. Zeichen, die kein Dateisystem akzeptiert (Schrägstrich, umgekehrter Schrägstrich, Doppelpunkt, Sternchen, Fragezeichen, Anführungszeichen, Kleiner-als, Größer-als, senkrechter Strich), werden zusammen mit Steuerzeichen entfernt. Die Namenslänge wird begrenzt, damit der Name in jedem Dateisystem funktioniert.

Bilder

Ein Bildelement der Vorlage kann an ein Datenfeld gebunden werden; die Quelle wird dann mit der Anfrage gesendet. Akzeptiert werden die ID einer hochgeladenen Ressource (ast_… — für wiederkehrende Logos, Stempel und Unterschriften; einmal hochgeladen, nur die ID wird übertragen) und ein Inline-Bild (data:image/png;base64,… — für einmalige Bilder). Fehlt das Feld oder ist es leer, wird das Vorlagenbild verwendet. Ist ein vorhandener Wert unbrauchbar, wird die Anfrage mit 422 abgelehnt und das Datenfeld in der Antwort genannt.

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Limits: Inline-Bilder müssen PNG, JPEG oder WebP sein; höchstens 2 MB pro Bild und 6 MB für alle Bilder eines Dokuments. Hochgeladene Ressourcen dürfen bis zu 10 MB groß sein. Geben Sie für temporäre Bilder beim Hochladen expiresInMinutes an (1 Minute bis 7 Tage); abgelaufene Ressourcen werden automatisch gelöscht.

Ressourcen

Logos, Unterschriften und Schriften werden einmal hochgeladen und per ID referenziert. Die zugehörige Seite erklärt Upload, Limits und Schriftberechtigungen.

Häufige Fehler

• Vorformatierte Werte werden unverändert ausgegeben. "1.234,56" liest sich in einer Sprache richtig und in einer anderen falsch; kein Formatierer kann das nachträglich korrigieren.
• Ein Datum muss ISO 8601 entsprechen. Lokale Formate kommen als Text an: Sie werden weder formatiert noch sortiert oder übersetzt.
• Die Währung gehört nicht in den Betrag. Senden Sie die Zahl und lassen Sie den Spaltenformatierer den ISO-Code ergänzen.
• Ein Verhältnis wird von hundert gesendet: 18 für 18%. Der Wert 0.18 ergibt null Komma achtzehn Prozent.
• Eine Bedingung liest einen booleschen JSON-Wert. Die Zeichenfolge "false" ist nicht leerer Text und zählt als vorhanden.