E-Rechnungen automatisiert erstellen: Kommandozeile, JSON und XML

Mit dem kostenlosen PDF24 Creator erstellen Sie E-Rechnungen (ZUGFeRD, Factur-X, XRechnung, Peppol) auch ohne Formular: Ein Aufruf der PDF24 Toolbox macht aus einer JSON- oder XML-Datei Ihres Programms eine fertige E-Rechnung. So lässt sich die E-Rechnung an ERP, Warenwirtschaft, Access, Excel oder ein eigenes Skript anbinden. Alles läuft lokal auf Ihrem PC.

Diese Seite beschreibt den Befehl, alle Schalter, das JSON-Format mit Pflichtfeldern und ein vollständiges Beispiel, das Sie kopieren können.

Inhalt

• Was Sie brauchen
• Welcher Weg passt zu Ihrem Programm?
• Der Befehl -createInvoice
• Alle Schalter und Ausgabeformate
• XML als Eingabe: vorhandene XRechnung oder ZUGFeRD-XML
• JSON als Eingabe: das Format
• Beispiele: Stapeldatei und PowerShell
• E-Rechnung aus Access, Excel oder der Warenwirtschaft
• Exit-Codes und Fehlermeldungen
• Typische Fehler
• Ergebnis prüfen

Was Sie brauchen

• PDF24 Creator für Windows, kostenlos: PDF24 Creator herunterladen. Nehmen Sie die aktuelle Version; einige Möglichkeiten auf dieser Seite gibt es erst seit bestimmten Versionen, das steht dann dabei.
• Die Komponente „OpenJDK“ (Java). Sie ist bei der Installation vorausgewählt. Wenn Sie benutzerdefiniert installieren, lassen Sie sie angehakt, ohne sie gibt es keine E-Rechnung auf der Kommandozeile.
• Den Pfad zur PDF24 Toolbox. Bei einer Standardinstallation ist das:

C:\Program Files\PDF24\pdf24-Toolbox.exe

Haben Sie PDF24 in einen anderen Ordner installiert, nehmen Sie den Pfad von dort. Setzen Sie den Pfad immer in Anführungszeichen, weil er Leerzeichen enthält.

Die E-Rechnung entsteht auf Ihrem PC, PDF24 lädt dafür nichts hoch. Nur wenn Sie in den Rechnungsdaten ein Logo oder eine Anlage als Internetadresse angeben, lädt PDF24 diese Datei von dort.

Welcher Weg passt zu Ihrem Programm?

1. Ihr Programm erzeugt schon eine XML-Rechnung (XRechnung, ZUGFeRD oder Factur-X als CII oder UBL). Dann geben Sie die XML an. PDF24 macht daraus eine lesbare PDF mit eingebetteter XML oder bettet die XML in Ihre eigene PDF-Rechnung ein. Das ist der einfachste Weg, weil Ihr Programm die Beträge schon richtig berechnet hat. Siehe XML als Eingabe.
2. Ihr Programm kann eine Textdatei schreiben, aber keine E-Rechnungs-XML. Dann schreiben Sie die Rechnungsdaten als JSON-Datei. PDF24 rechnet Summen und Steuern selbst aus und erzeugt PDF und XML. Siehe JSON als Eingabe.
3. Sie wollen nicht programmieren, haben aber viele Rechnungen, etwa in einer Excel-Tabelle. Dann sind Serienrechnungen im E-Rechnungs-Werkzeug einfacher: Serienrechnungen ohne Programmierung.

Für einzelne Rechnungen von Hand nehmen Sie das Werkzeug „Elektronische Rechnung erstellen“ in der PDF24 Toolbox oder online: E-Rechnung erstellen. Einen Überblick gibt die Seite E-Rechnungen mit PDF24 erstellen.

Der Befehl -createInvoice

"C:\Program Files\PDF24\pdf24-Toolbox.exe" -createInvoice EINGABEDATEI AUSGABEDATEI -outputType FORMAT [weitere Schalter]

Ein Beispiel, das aus einer JSON-Datei eine ZUGFeRD-Rechnung macht:

"C:\Program Files\PDF24\pdf24-Toolbox.exe" -createInvoice "C:\Rechnungen\RE-2026-001.json" "C:\Rechnungen\RE-2026-001.pdf" -outputType zugferd:en16931

Das ist wichtig:

• Direkt nach -createInvoice folgen zwei Pfade: zuerst die Eingabedatei, dann die Ausgabedatei. Vergessen Sie die Ausgabedatei, nimmt die Toolbox das nächste Wort als Dateinamen (dann entsteht z. B. eine Datei namens „-outputType“).
• Die Eingabedatei muss auf .json oder .xml enden.
• Die Ausgabedatei wird genau unter dem Namen gespeichert, den Sie angeben, eine vorhandene Datei wird überschrieben. Nehmen Sie .pdf für PDF- und ZUGFeRD-Ausgaben und .xml für reine XML-Rechnungen, PDF24 ändert die Endung nicht.
• Pfade mit Leerzeichen gehören in Anführungszeichen. Geben Sie am besten vollständige Pfade an, dann ist egal, aus welchem Ordner Ihr Programm den Befehl startet.
• Ohne -outputType entsteht nur eine normale PDF-Rechnung ohne XML, also keine E-Rechnung.

Die Beschreibung im Handbuch des PDF24 Creators finden Sie hier: Handbuch, Abschnitt Create invoices (Englisch).

Alle Schalter und Ausgabeformate

Schreiben Sie die Schalter wie hier, mit Bindestrich. Seit Version 11.34.0 ist die Groß- und Kleinschreibung egal (-outputtype wirkt wie -outputType), und ein unbekannter oder vertippter Schalter bricht mit einer Meldung und Exit-Code 3 ab. Bis Version 11.33.0 zählt die Groß- und Kleinschreibung, und ein vertippter Schalter wird nicht gemeldet, sondern übergangen (siehe Typische Fehler).

-outputType: das Ausgabeformat

• zugferd:en16931 – PDF mit eingebetteter Datei factur-x.xml im Profil EN 16931 (ZUGFeRD/Factur-X). Das übliche Format für Rechnungen an Unternehmen.
• zugferd:xrechnung – PDF mit eingebetteter Datei xrechnung.xml (ZUGFeRD im Profil XRechnung).
• xrechnung:cii – nur die XML-Datei, XRechnung in der Syntax CII.
• xrechnung:ubl – nur die XML-Datei, XRechnung in der Syntax UBL.
• en16931:cii – nur die XML-Datei nach EN 16931, Syntax CII.
• en16931:ubl – nur die XML-Datei nach EN 16931, Syntax UBL.
• peppol:ubl – nur die XML-Datei für das Peppol-Netz (Peppol BIS Billing 3.0, UBL).
• pdf – nur eine lesbare PDF-Rechnung ohne XML. Das ist keine E-Rechnung. Dieser Wert gilt, wenn Sie -outputType weglassen.

Welches Format Ihr Empfänger braucht, erklärt die Seite E-Rechnungen mit PDF24 erstellen. Für Behörden ist es meist die XRechnung, für Unternehmen oft ZUGFeRD.

-pdfFile: Ihre eigene PDF verwenden

-pdfFile "C:\Rechnungen\RE-2026-001.pdf" – PDF24 erzeugt dann keine eigene PDF, sondern nimmt Ihre, wandelt sie in PDF/A-3 um und bettet die XML ein. So behält die Rechnung Ihr Layout und Briefpapier. Nur zusammen mit einem zugferd:-Format sinnvoll.

-pdfaFile: Ihre PDF/A-3-Datei verwenden

-pdfaFile "C:\Rechnungen\RE-2026-001.pdf" – wie -pdfFile, aber ohne Umwandlung. Nur für Dateien, die schon PDF/A-3 sind. Im Zweifel nehmen Sie -pdfFile.

Nach -pdfFile und -pdfaFile muss immer ein Pfad folgen. Steht der Schalter allein am Ende, meldet die Toolbox ihn seit Version 11.34.0 als unbekannte Option (Exit-Code 3); bis Version 11.33.0 wird er übergangen.

-passthrough: Ihre XML unverändert übernehmen

Nur für eine CII-XML als Eingabe mit einem zugferd:-Format. PDF24 erzeugt dann die PDF aus den Daten der XML, bettet aber Ihre XML-Datei unverändert ein, statt sie neu zu schreiben. Mit -pdfFile oder -pdfaFile brauchen Sie den Schalter nicht, dann wird Ihre CII-XML ohnehin unverändert eingebettet.

-regenerateXml: XML neu schreiben

Nur zusammen mit einer XML-Eingabe und -pdfFile oder -pdfaFile. PDF24 bettet Ihre XML dann nicht unverändert ein, sondern liest sie ein und schreibt sie neu. Seit Version 11.29.0.

-langCode: Sprache der PDF

-langCode en – die Beschriftungen der erzeugten PDF (z. B. „Rechnung“, „Rechnungsdatum“) in dieser Sprache, z. B. de, en oder fr. Ohne den Schalter ist die PDF deutsch. Die XML ist davon nicht betroffen. Seit Version 11.29.0.

-langFile: eigene Beschriftungen

-langFile "C:\Rechnungen\beschriftungen.txt" – eine Datei mit eigenen Texten für die Beschriftungen der PDF. Eine Vorlage für diese Datei bekommen Sie auf Anfrage an team@pdf24.org. Seit Version 11.29.0.

XML als Eingabe: vorhandene XRechnung oder ZUGFeRD-XML

Die Toolbox liest XML-Rechnungen in den Syntaxen CII und UBL (XRechnung, ZUGFeRD/Factur-X ab Profil EN 16931, Peppol). Damit geht Folgendes:

Lesbare PDF aus einer XML-Rechnung (z. B. um eine empfangene XRechnung auszudrucken):

"C:\Program Files\PDF24\pdf24-Toolbox.exe" -createInvoice "C:\Rechnungen\RE-4711.xml" "C:\Rechnungen\RE-4711-ansicht.pdf" -outputType pdf

Ihre PDF und Ihre XML zu einer ZUGFeRD-Rechnung verbinden:

"C:\Program Files\PDF24\pdf24-Toolbox.exe" -createInvoice "C:\Rechnungen\RE-4711.xml" "C:\Rechnungen\RE-4711-zugferd.pdf" -outputType zugferd:en16931 -pdfFile "C:\Rechnungen\RE-4711.pdf"

Eine CII-XML wird unverändert eingebettet, eine UBL-XML in CII umgewandelt (seit Version 11.31.0). Kennzeichnung und Dateiname richten sich nach Ihrer XML, nicht nach -outputType: Eine XRechnung bleibt eine XRechnung (xrechnung.xml), auch mit zugferd:en16931, eine XML im Profil EXTENDED wird als EXTENDED gekennzeichnet. Mehr dazu auf der Seite PDF-Rechnung in E-Rechnung umwandeln: Welche XML passt?

Aus einer XML eine ZUGFeRD-PDF mit von PDF24 erzeugter Rechnungsseite machen: wie oben, aber ohne -pdfFile. Mit -passthrough bleibt Ihre CII-XML dabei unverändert.

UBL in CII umwandeln (oder umgekehrt): Geben Sie die XML ein und als Format z. B. en16931:cii oder xrechnung:ubl.

Ein Logo oder andere Einstellungen für die PDF lassen sich mit einer XML-Eingabe nicht mitgeben, die XML enthält dafür keine Felder. Wenn Sie ein Logo brauchen: Nehmen Sie Ihre eigene PDF mit Logo (-pdfFile) oder liefern Sie die Daten als JSON.

Wie Sie PDF und XML ohne Kommandozeile verbinden, in der Toolbox oder online, steht auf der Seite PDF-Rechnung in eine E-Rechnung umwandeln.

Direkt beim Drucken aus Ihrem Programm

Wenn Ihr Programm die Rechnung druckt und die XML in eine Datei schreibt, kann der PDF24-Drucker beides in einem Schritt verbinden:

1. Öffnen Sie die PDF24-Einstellungen, Bereich „PDF Drucker“.
2. Stellen Sie das Speichern auf „Dokumente nach dem Drucken automatisch speichern“ und haken Sie „Steuercodes im gedruckten Dokument erkennen“ an.
3. Tragen Sie bei „Folgendes Kommando nach dem Speichern ausführen“ ein:

"C:\Program Files\PDF24\pdf24-Toolbox.exe" -createInvoice $cmdArgs -outputType zugferd:en16931 -pdfFile "$file"

4. Lassen Sie Ihr Programm auf die Rechnung einen Steuercode drucken, der die XML-Datei und die Zieldatei nennt, z. B. @@cmdargs:"C:\Rechnungen\RE-4711.xml" "C:\Rechnungen\RE-4711-zugferd.pdf"@@.

$file ist die gerade gespeicherte PDF, $cmdArgs der Inhalt des Steuercodes. Die Steuercodes beschreibt das Handbuch im Kapitel zum PDF-Drucker.

JSON als Eingabe: das Format

Die JSON-Datei ist dasselbe Format, das das E-Rechnungs-Werkzeug beim Export einer Rechnung speichert. Sie müssen aber nicht alles liefern: Summen, Steuerbeträge und vieles andere berechnet PDF24 selbst.

Tipp: eine Rechnung im Werkzeug anlegen und exportieren

Am schnellsten sehen Sie das Format so:

1. Öffnen Sie in der PDF24 Toolbox „Elektronische Rechnung erstellen“ oder online E-Rechnung erstellen.
2. Füllen Sie eine Musterrechnung aus, gern mit Logo, Anlage und allem, was Sie brauchen.
3. Öffnen Sie oben rechts das Menü (daneben steht „Importieren, exportieren, laden, speichern, ...“) und wählen Sie „Rechnung exportieren“.
4. Öffnen Sie die gespeicherte JSON-Datei mit einem Texteditor.

Mit „Rechnung importieren“ im selben Menü laden Sie eine JSON-Datei wieder ins Formular, z. B. um zu sehen, ob Ihr Programm sie richtig geschrieben hat.

Wichtig: Nehmen Sie das Werkzeug „Elektronische Rechnung erstellen“. Die JSON-Datei aus dem Werkzeug „Rechnung erstellen“ (normale Rechnung ohne XML) hat ein anderes Format und passt nicht.

Wenn Sie eine exportierte Datei als Vorlage nehmen: Löschen Sie die Abschnitte "totals" und "taxes" und bei den Positionen "netAmount", "taxAmount" und "grossAmount". Das sind die Ergebnisse der Musterrechnung. Bleiben sie stehen, übernimmt PDF24 sie auch für neue Positionen, und die Summen stimmen nicht mehr (siehe Vorgegebene Beträge).

Ein vollständiges Beispiel

Diese Datei erzeugt in allen acht Formaten eine gültige E-Rechnung (für Peppol siehe unten bei den elektronischen Adressen). Speichern Sie sie als UTF-8, z. B. als C:\Rechnungen\RE-2026-001.json:

{
    "number": "RE-2026-001",
    "typeCode": "380",
    "issueDate": "2026-11-11",
    "dueDate": "2026-11-25",
    "deliveryDate": "2026-11-10",
    "currencyCode": "EUR",
    "buyerReference": "PO-4711",
    "seller": {
        "name": "Muster GmbH",
        "vatId": "DE123456789",
        "electronicAddress": "rechnung@muster-gmbh.de",
        "address": {
            "line1": "Hauptstraße 1",
            "postCode": "10115",
            "city": "Berlin",
            "countryCode": "DE"
        },
        "contact": {
            "name": "Max Mustermann",
            "phone": "+49 30 123456",
            "email": "max@muster-gmbh.de"
        }
    },
    "buyer": {
        "name": "Beispiel AG",
        "electronicAddress": "eingang@beispiel-ag.de",
        "address": {
            "line1": "Marktplatz 5",
            "postCode": "80331",
            "city": "München",
            "countryCode": "DE"
        }
    },
    "payment": {
        "terms": "Zahlbar bis [due_date] ohne Abzug.",
        "methods": [
            {
                "typeCode": "58",
                "iban": "DE02120300000000202051",
                "accountName": "Muster GmbH"
            }
        ]
    },
    "items": [
        {
            "name": "Beratung",
            "quantity": 2,
            "unit": "HUR",
            "netUnitPrice": 120.00,
            "vatRate": 19
        },
        {
            "name": "Fachbuch",
            "quantity": 5,
            "unit": "H87",
            "netUnitPrice": 4.99,
            "vatRate": 7
        }
    ]
}

Daraus berechnet PDF24: Positionen 240,00 und 24,95 EUR, netto 264,95 EUR, Umsatzsteuer 45,60 EUR (19 %) und 1,75 EUR (7 %), Gesamt und fällig 312,30 EUR. Aus [due_date] wird „25.11.2026“.

Aufbau der Datei

Die Datei ist ein JSON-Objekt mit diesen Abschnitten (in Klammern die Nummer im Standard EN 16931):

• Rechnungskopf: number Rechnungsnummer (BT-1), issueDate Rechnungsdatum (BT-2), typeCode Rechnungsart (BT-3, ohne Angabe 380 = Rechnung), currencyCode Währung (BT-5, z. B. EUR), dueDate Fälligkeitsdatum (BT-9), buyerReference Käuferreferenz bzw. Leitweg-ID (BT-10), deliveryDate Leistungsdatum (BT-72), billingPeriodStart und billingPeriodEnd Leistungszeitraum (BT-73, BT-74), buyerOrderReference Bestellnummer (BT-13), contractReference Vertragsnummer (BT-12), projectReference Projektnummer (BT-11), notes Bemerkungen (BT-22, Text oder Liste von Texten).
• seller, der Rechnungssteller: name (BT-27), vatId USt-IdNr. (BT-31), taxId Steuernummer (BT-32), id Verkäuferkennung (BT-29), tradeId Handelsregisternummer (BT-30), electronicAddress elektronische Adresse (BT-34), address, contact (BG-6) mit name, phone, email, dazu logoFile für das Logo.
• buyer, der Rechnungsempfänger: name (BT-44), id Kundennummer (BT-46), vatId (BT-48), electronicAddress (BT-49), address, contact.
• address (bei Verkäufer und Käufer): line1, line2, line3 Straße und Zusätze, postCode, city, countryCode (zwei Buchstaben, z. B. DE).
• payment: terms Zahlungsbedingungen (BT-20), reference Verwendungszweck (BT-83), methods eine Liste der Zahlungsarten mit typeCode (BT-81, z. B. 58 SEPA-Überweisung, 59 SEPA-Lastschrift, 10 bar), iban, bic, accountName Kontoinhaber, bei Lastschrift directDebitMandate und creditorId.
• items, die Positionen, je Position: name (BT-153), description (BT-154), quantity Menge (BT-129), unit Einheitencode (BT-130, z. B. H87 Stück, HUR Stunde, C62 Einheit; ohne Angabe H87), netUnitPrice Nettopreis je Einheit (BT-146), vatRate Steuersatz in Prozent (BT-152), vatCode Steuerkategorie (BT-151), sellerId Artikelnummer (BT-155), quantityUnitSymbol Kürzel für die PDF (z. B. „Std.“ statt „HUR“), allowances und charges für Nachlässe und Zuschläge der Position.
• allowances und charges auf Rechnungsebene: Nachlässe (BG-20) und Zuschläge (BG-21) wie Versandkosten.
• attachments: Anlagen (BG-24).
• outputOptions: Einstellungen für die PDF, siehe unten.

Datumsangaben schreiben Sie als 2026-11-11 (auch 11.11.2026 wird gelesen). Beträge und Mengen sind JSON-Zahlen mit Punkt und ohne Anführungszeichen.

Pflichtfelder

PDF24 prüft beim Aufruf nicht, ob alle Pflichtangaben da sind. Fehlt etwas, entsteht trotzdem eine Datei, die der Empfänger dann ablehnt. Welche Angaben Pflicht sind, legt das gewählte Format fest. Für eine normale Rechnung mit Umsatzsteuer gilt (getestet mit den offiziellen Prüfregeln):

Für alle Formate (ZUGFeRD zugferd:en16931, en16931:cii, en16931:ubl):

• number, issueDate, currencyCode
• deliveryDate oder billingPeriodStart/billingPeriodEnd (für ZUGFeRD Pflicht, für XRechnung empfohlen)
• dueDate oder payment.terms
• beim Verkäufer name und address mit countryCode, dazu vatId (oder bei Rechnungen ohne Umsatzsteuer taxId und id, siehe unten)
• beim Käufer name und address mit countryCode
• je Position name, quantity, netUnitPrice und vatRate

Postleitzahl (postCode) und Ort (city) verlangt die Norm noch nicht; geben Sie sie trotzdem an, sie gehören in jede vollständige Anschrift.

Zusätzlich für XRechnung (xrechnung:cii, xrechnung:ubl, zugferd:xrechnung):

• postCode und city in der address von Verkäufer und Käufer
• buyerReference, bei Behörden die Leitweg-ID
• seller.contact mit name, phone und email
• seller.electronicAddress und buyer.electronicAddress
• payment.methods mit mindestens einer Zahlungsart, bei Überweisung mit iban

Fehlen diese Angaben, melden Prüfprogramme bei einer XRechnung z. B. „[BR-DE-15] Das Element "Buyer reference" (BT-10) muss übermittelt werden.“, „[BR-DE-2] Die Gruppe "SELLER CONTACT" (BG-6) muss übermittelt werden.“ oder „[BR-DE-1] Eine Rechnung (INVOICE) muss Angaben zu "PAYMENT INSTRUCTIONS" (BG-16) enthalten.“. Was solche Meldungen bedeuten, steht auf der Seite Fehlermeldungen und häufige Probleme lösen.

Zusätzlich für Peppol (peppol:ubl): wie XRechnung die elektronischen Adressen, aber mit einem Peppol-Schema, siehe nächster Abschnitt. Sitzt der Verkäufer in Deutschland, gelten in Peppol zusätzlich deutsche Regeln, die unter anderem postCode und city verlangen.

Elektronische Adresse und Schema

Die elektronische Adresse (electronicAddress) ist ohne weitere Angabe eine E-Mail-Adresse (Schema EM). Das genügt für XRechnung und ZUGFeRD. Peppol erlaubt EM nicht, dort geben Sie das Schema mit electronicAddressScheme an, z. B. 9930 für eine deutsche USt-IdNr., 0204 für eine Leitweg-ID oder 0088 für eine GLN:

"electronicAddress": "DE123456789",
"electronicAddressScheme": "9930"

Welche Adresse und welches Schema der Empfänger erwartet, erfahren Sie von ihm.

Was PDF24 selbst berechnet

Lassen Sie diese Felder weg, dann rechnet PDF24 sie aus:

• je Position den Nettobetrag (Menge × Preis, abzüglich Nachlässe, zuzüglich Zuschläge), die Umsatzsteuer und den Bruttobetrag
• die Steuerkategorie einer Position: S (Normalsatz) bei einem Steuersatz über 0, E (steuerbefreit) bei 0
• die Umsatzsteueraufstellung je Steuersatz (BG-23)
• alle Summen: Summe der Positionen, Nachlässe, Zuschläge, Netto, Umsatzsteuer, Brutto und den fälligen Betrag (BT-106 bis BT-115)
• Nachlässe und Zuschläge mit percent: Grundbetrag und Betrag

In den Zahlungsbedingungen (terms) ersetzt PDF24 Platzhalter: [due_date] bzw. [Fälligkeitsdatum], [due_amount] bzw. [Endbetrag], [invoice_number] bzw. [Rechnungsnummer], [issue_date] bzw. [Rechnungsdatum], [IBAN]. Im Verwendungszweck (reference) gehen [invoice_number] und [Kundennummer].

Vorgegebene Beträge werden nicht nachgerechnet

Liefern Sie Beträge mit, etwa netAmount einer Position, den Abschnitt totals oder taxes, übernimmt PDF24 sie so, wie sie sind, und rechnet sie nicht nach. Passen sie nicht zu den Positionen, entsteht eine Rechnung mit falschen Summen, die Prüfprogramme ablehnen, z. B. mit „[BR-CO-14] Invoice total VAT amount (BT-110) = Σ VAT category tax amount (BT-117)“ oder bei Nachlässen mit Peppol-Regeln wie R120 und R040.

Darum: Liefern Sie Beträge entweder in sich stimmig, oder lassen Sie sie weg und PDF24 rechnet. Weglassen ist der sichere Weg. Ausnahme: Wenn Ihr Programm Beträge anders rundet und die Rechnung genau Ihre Beträge zeigen soll, liefern Sie alle Beträge vollständig mit.

Nachlässe und Zuschläge

Ein Rabatt auf eine Position:

{ "name": "Beratung", "quantity": 2, "unit": "HUR", "netUnitPrice": 120.00, "vatRate": 19,
  "allowances": [ { "percent": 10, "reason": "Rabatt" } ] }

Versandkosten als Zuschlag auf die ganze Rechnung, auf derselben Ebene wie items:

"charges": [ { "netAmount": 5.90, "reason": "Versand", "vatCode": "S", "vatRate": 19 } ]

Bei Nachlässen und Zuschlägen auf Rechnungsebene geben Sie immer vatCode und vatRate an. Anders als bei Positionen leitet PDF24 die Steuerkategorie dort nicht aus dem Steuersatz ab, ohne vatCode lehnen Prüfprogramme die Rechnung ab. Nachlässe einer Position übernehmen die Steuer der Position.

Logo und Anlagen

Auf der Kommandozeile dürfen Logo und Anlagen auf Dateien auf Ihrem PC zeigen, Sie müssen sie nicht base64-kodieren:

"seller": {
    "name": "Muster GmbH",
    "logoFile": "C:\\Rechnungen\\logo.png",
    ...
},
"attachments": [
    {
        "file": "C:\\Rechnungen\\Leistungsnachweis.pdf",
        "filename": "Leistungsnachweis.pdf",
        "description": "Leistungsnachweis Oktober"
    }
]

• Im JSON wird jeder Backslash verdoppelt: C:\\Rechnungen\\logo.png.
• Statt logoFile geht logoUrl (Internetadresse), statt file geht url. Eine exportierte Datei enthält Logo und Anlagen base64-kodiert (logoData, base64), das funktioniert ebenfalls.
• Geben Sie bei einer Anlage immer filename an. Ohne den Namen bricht die Erstellung ab.
• Dateipfade und Internetadressen werden nur beim Aufruf mit -createInvoice gelesen. Öffnen Sie eine solche JSON-Datei im PDF24 Creator, bleiben Logo und Anlagen aus Dateipfaden weg (seit Version 11.31.0, damit fremde Rechnungsdaten keine Dateien Ihres PCs in eine PDF bringen).

Die Anlagen stehen in der ZUGFeRD-PDF als eingebettete Dateien neben der XML und werden auf der Rechnung unter „Anlagen“ aufgeführt.

Aussehen der PDF: outputOptions

Mit dem Abschnitt outputOptions steuern Sie die erzeugte PDF, z. B.:

"outputOptions": {
    "addressWindowMode": "din5008",
    "logoSizeMode": "large",
    "noteSubjectCodeDisplayMode": "hidden",
    "langCode": "en"
}

• "addressWindowMode": "din5008" – Layout nach DIN 5008 für Fensterbriefumschläge
• "logoSizeMode": "large" oder "xlarge" – größeres Logo; "logoDisplayMode": "right" – Logo rechts über den Zahlungsdetails
• "noteSubjectCodeDisplayMode": "hidden" – Kürzel wie „AAB“ vor den Bemerkungen ausblenden
• "quantityUnitDisplayMode": "hidden" – keine Einheit hinter der Menge
• "langCode" – Sprache der PDF, wie der Schalter -langCode

Am einfachsten stellen Sie die Ausgabeoptionen im Werkzeug ein, exportieren eine Rechnung und übernehmen den Abschnitt outputOptions aus der Datei. Ein ganz eigenes Layout geht nicht über JSON. Dafür erstellen Sie die PDF selbst und geben sie mit -pdfFile an.

Rechnung ohne Umsatzsteuer (Kleinunternehmer)

Für Rechnungen ohne Umsatzsteuerausweis setzen Sie bei jeder Position "vatRate": 0 (PDF24 wählt dann die Kategorie E, steuerbefreit) und geben auf oberster Ebene den Grund an. Hat der Verkäufer keine USt-IdNr., tragen Sie die Steuernummer in taxId und eine Verkäuferkennung in id ein (z. B. den Firmennamen), sonst meldet die Prüfung BR-CO-26:

"taxExemptionReason": "Kein Ausweis von Umsatzsteuer, da Kleinunternehmer gemäß § 19 UStG",
"seller": {
    "name": "Muster GmbH",
    "taxId": "12/345/67890",
    "id": "Muster GmbH",
    ...
}

Welche Steuerkategorie und welcher Text für Ihre Rechnungen richtig sind, klärt Ihr Steuerberater.

Hinweise zum Schreiben der Datei

• Zeichensatz UTF-8. In einer Datei im Windows-Zeichensatz (ANSI) werden Umlaute ohne Meldung zu falschen Zeichen. UTF-8 mit oder ohne BOM geht beides.
• Zahlen ohne Anführungszeichen und mit Punkt: "netUnitPrice": 120.50. Ein Betrag als Text ("120.50") wird ohne Meldung als 0 gelesen, ein Komma (120,50) macht die Datei ungültig.
• Texte mit Anführungszeichen oder Backslash müssen maskiert werden: \" und \\. Ein Zeilenumbruch im Text wird zu \n.
• Nur echtes JSON: keine Kommentare, kein Komma nach dem letzten Eintrag einer Liste.

Beispiele: Stapeldatei und PowerShell

Alle JSON-Dateien eines Ordners (Stapeldatei)

Speichern Sie das als erechnungen.cmd. Es erzeugt aus jeder JSON-Datei in C:\Rechnungen\json eine ZUGFeRD-PDF mit gleichem Namen in C:\Rechnungen\pdf und schreibt Fehler in eine Logdatei:

@echo off
set TOOLBOX="C:\Program Files\PDF24\pdf24-Toolbox.exe"
for %%f in ("C:\Rechnungen\json\*.json") do (
  %TOOLBOX% -createInvoice "%%f" "C:\Rechnungen\pdf\%%~nf.pdf" -outputType zugferd:en16931 >> "C:\Rechnungen\protokoll.txt" 2>&1
  if errorlevel 1 echo Fehler bei %%~nxf >> "C:\Rechnungen\fehler.txt"
)

In einer Stapeldatei wartet Windows jeweils, bis die Toolbox fertig ist, bevor die nächste Rechnung beginnt.

PDF und XML paarweise verbinden (Stapeldatei)

Liegen in einem Ordner zu jeder Rechnung eine PDF und eine XML mit gleichem Namen (RE-4711.pdf, RE-4711.xml), entsteht daraus je eine RE-4711-zugferd.pdf:

@echo off
set TOOLBOX="C:\Program Files\PDF24\pdf24-Toolbox.exe"
for %%f in ("C:\Rechnungen\paare\*.xml") do (
  if exist "%%~dpnf.pdf" %TOOLBOX% -createInvoice "%%f" "%%~dpnf-zugferd.pdf" -outputType zugferd:en16931 -pdfFile "%%~dpnf.pdf"
)

Alle JSON-Dateien eines Ordners (PowerShell)

In PowerShell wartet der einfache Aufruf mit & nicht, bis die Toolbox fertig ist. Nehmen Sie deshalb Start-Process mit -Wait:

$toolbox = 'C:\Program Files\PDF24\pdf24-Toolbox.exe'
Get-ChildItem 'C:\Rechnungen\json\*.json' | ForEach-Object {
    $out = Join-Path 'C:\Rechnungen\pdf' ($_.BaseName + '.pdf')
    $p = Start-Process -FilePath $toolbox -Wait -PassThru -NoNewWindow `
        -ArgumentList "-createInvoice `"$($_.FullName)`" `"$out`" -outputType zugferd:en16931"
    if ($p.ExitCode -ne 0) { Write-Warning "Fehler bei $($_.Name)" }
}

E-Rechnung aus Access, Excel oder der Warenwirtschaft

Eine fertige Anbindung für Access oder bestimmte Warenwirtschaften gibt es nicht, aber der Weg ist immer derselbe: Ihr Programm schreibt die Rechnungsdaten als JSON-Datei (oder eine XML-Rechnung) und ruft dann die Toolbox auf. Wichtig ist, dass Ihr Programm wartet, bis die Toolbox fertig ist, und den Exit-Code auswertet.

Access und Excel (VBA)

Bequem ist eine Vorlage: Exportieren Sie eine Musterrechnung aus dem E-Rechnungs-Werkzeug (siehe Tipp oben), löschen Sie totals, taxes und die Beträge der Positionen, ersetzen Sie die wechselnden Werte durch Platzhalter wie "{{NUMMER}}" und die Positionen durch "items": []. Ihre festen Angaben (Firma, Bankverbindung, Logo) bleiben in der Vorlage stehen.

Dieses Modul füllt die Vorlage, speichert die JSON-Datei als UTF-8 und erzeugt die ZUGFeRD-Rechnung:

Private Const TOOLBOX As String = "C:\Program Files\PDF24\pdf24-Toolbox.exe"

' Text für JSON maskieren (ohne die umgebenden Anführungszeichen)
Public Function JsonText(ByVal text As String) As String
    text = Replace(text, "\", "\\")
    text = Replace(text, """", "\""")
    text = Replace(text, vbCrLf, "\n")
    text = Replace(text, vbLf, "\n")
    text = Replace(text, vbCr, "\n")
    text = Replace(text, vbTab, "\t")
    JsonText = text
End Function

' Zahl für JSON: immer mit Punkt, egal welche Ländereinstellung
Public Function JsonNum(ByVal wert As Double) As String
    JsonNum = Replace(Format(wert, "0.00##"), ",", ".")
End Function

Private Function LeseUtf8(ByVal pfad As String) As String
    With CreateObject("ADODB.Stream")
        .Type = 2: .Charset = "utf-8": .Open
        .LoadFromFile pfad
        LeseUtf8 = .ReadText
        .Close
    End With
End Function

Private Sub SpeichereUtf8(ByVal pfad As String, ByVal inhalt As String)
    With CreateObject("ADODB.Stream")
        .Type = 2: .Charset = "utf-8": .Open
        .WriteText inhalt
        .SaveToFile pfad, 2
        .Close
    End With
End Sub

' Startet die Toolbox, wartet auf das Ende und gibt True zurück, wenn die Datei erstellt wurde
Public Function ErzeugeERechnung(ByVal jsonDatei As String, ByVal pdfDatei As String) As Boolean
    Dim befehl As String
    befehl = """" & TOOLBOX & """ -createInvoice """ & jsonDatei & """ """ & pdfDatei & _
             """ -outputType zugferd:en16931"
    ' 0 = ohne Fenster, True = warten; Rückgabewert ist der Exit-Code
    ErzeugeERechnung = (CreateObject("WScript.Shell").Run(befehl, 0, True) = 0)
End Function

Beispiel für Access mit einer Tabelle Rechnungen und einer Tabelle Positionen (Feldnamen an Ihre Datenbank anpassen):

Public Sub RechnungAlsERechnung(ByVal rechnungId As Long)
    Dim re As DAO.Recordset, pos As DAO.Recordset
    Dim positionen As String, json As String, nr As String

    Set re = CurrentDb.OpenRecordset("SELECT * FROM Rechnungen WHERE ID = " & rechnungId)
    Set pos = CurrentDb.OpenRecordset("SELECT * FROM Positionen WHERE RechnungID = " & rechnungId)
    nr = Nz(re!RechnungsNr, "")

    Do Until pos.EOF
        If Len(positionen) > 0 Then positionen = positionen & ","
        positionen = positionen & "{""name"": """ & JsonText(Nz(pos!Bezeichnung, "")) & """" & _
            ", ""quantity"": " & JsonNum(pos!Menge) & _
            ", ""unit"": ""H87""" & _
            ", ""netUnitPrice"": " & JsonNum(pos!Einzelpreis) & _
            ", ""vatRate"": " & JsonNum(pos!MwStSatz) & "}"
        pos.MoveNext
    Loop

    json = LeseUtf8("C:\Rechnungen\vorlage.json")
    json = Replace(json, "{{NUMMER}}", JsonText(nr))
    json = Replace(json, "{{DATUM}}", Format(re!Rechnungsdatum, "yyyy-mm-dd"))
    json = Replace(json, "{{LEISTUNGSDATUM}}", Format(re!Leistungsdatum, "yyyy-mm-dd"))
    json = Replace(json, "{{KUNDE}}", JsonText(Nz(re!Kundenname, "")))
    json = Replace(json, """items"": []", """items"": [" & positionen & "]")

    SpeichereUtf8 "C:\Rechnungen\" & nr & ".json", json
    If Not ErzeugeERechnung("C:\Rechnungen\" & nr & ".json", "C:\Rechnungen\" & nr & ".pdf") Then
        MsgBox "Die E-Rechnung " & nr & " konnte nicht erstellt werden."
    End If
End Sub

In Excel funktioniert dasselbe Modul. Statt der Datensätze lesen Sie die Werte aus den Zellen, z. B. Cells(zeile, 2).Value, und Nz(...) lassen Sie weg.

Hinweise:

• Shell(...) wartet nicht und liefert keinen Exit-Code. Nehmen Sie CreateObject("WScript.Shell").Run(befehl, 0, True) wie oben.
• Print # schreibt im Windows-Zeichensatz, nicht in UTF-8. Nehmen Sie zum Schreiben ADODB.Stream wie oben.
• Format(wert, "0.00") schreibt in deutschen Einstellungen ein Komma. Darum ersetzt JsonNum das Komma durch einen Punkt.

Warenwirtschaft, ERP und eigene Programme

Jede Programmiersprache, die eine Datei schreiben und ein Programm starten kann, kann so E-Rechnungen erzeugen. Kann Ihr Programm selbst XRechnung- oder ZUGFeRD-XML (CII) ausgeben, nehmen Sie diese XML als Eingabe, dann müssen Sie kein JSON schreiben. Fragen Sie im Zweifel beim Hersteller Ihrer Software nach.

Exit-Codes und Fehlermeldungen

Seit Version 11.33.0 meldet die Toolbox das Ergebnis über den Exit-Code:

• 0 – die Ausgabedatei wurde geschrieben.
• 1 – es wurde keine Datei geschrieben. Die Meldung nennt den Grund, z. B. Input file does not exist: … (Eingabedatei nicht gefunden) oder Invoice creation failed, no file written: …. Darüber steht die Fehlermeldung der Verarbeitung, z. B. bei einem Tippfehler im JSON MalformedJsonException: Unterminated object at line 3 column 6 path $.number mit Zeile und Spalte.
• 3 – ein unbekannter oder vertippter Schalter (seit Version 11.34.0). Die Meldung nennt ihn, z. B. pdf24-Toolbox.exe: unknown option: -ouputType; es wird keine Datei geschrieben.

In älteren Versionen war der Exit-Code immer 0. Prüfen Sie dort, ob die Ausgabedatei neu entstanden ist, oder aktualisieren Sie PDF24.

Die Meldungen erscheinen in der Konsole, aus der Sie die Toolbox starten. Fehlermeldungen der Verarbeitung gehen auf die Fehlerausgabe (stderr). In einer Stapeldatei leiten Sie beides mit >> protokoll.txt 2>&1 in eine Datei um.

Wichtig: Exit-Code 0 heißt nur, dass eine Datei entstanden ist. Ob die E-Rechnung alle Regeln erfüllt, prüft der Befehl nicht. Siehe Ergebnis prüfen.

Typische Fehler

Es entsteht eine PDF, aber ohne XML. Dann fehlt -outputType. Seit Version 11.34.0 weist die Toolbox darauf hin (Note: no -outputType given - a plain PDF invoice is created, without e-invoice XML.), meldet einen vertippten Schalter wie -ouputType als unbekannte Option mit Exit-Code 3 und versteht -outputtype oder -OutputType in jeder Groß- und Kleinschreibung. Bis Version 11.33.0 übergeht die Toolbox unbekannte Schalter ohne Meldung und erzeugt dann eine normale PDF; dort entsteht das Problem auch, wenn -outputType vertippt (z. B. -ouputType) oder anders geschrieben ist (-outputtype, -OutputType). Prüfen Sie dann die Schreibweise genau oder aktualisieren Sie auf 11.34.0 oder neuer.

Es entsteht eine Datei namens „-outputType“. Die Ausgabedatei fehlt im Befehl, die Toolbox hat das nächste Wort als Dateinamen genommen.

-pdfaFile oder -pdfFile ohne Pfad. Nach diesen Schaltern muss Ihre PDF folgen. Soll PDF24 die PDF selbst erzeugen, lassen Sie den Schalter ganz weg.

-outputType zugferd ohne Zusatz. Das ergibt ZUGFeRD im Profil XRechnung mit xrechnung.xml. Für das Profil EN 16931 mit factur-x.xml schreiben Sie zugferd:en16931.

Die JSON-Datei kommt aus „Rechnung erstellen“. Das Werkzeug für normale Rechnungen hat ein anderes JSON-Format. Exportieren Sie aus „Elektronische Rechnung erstellen“.

Summen falsch, obwohl die Positionen stimmen. Die Datei enthält noch totals, taxes oder netAmount aus einer Vorlage. Löschen Sie diese Felder (siehe Vorgegebene Beträge).

Ein Preis ist 0. Der Betrag steht in Anführungszeichen. Schreiben Sie ihn als Zahl.

Umlaute falsch. Die Datei ist nicht als UTF-8 gespeichert.

Fehler „Could not read invoice data file“. Die Eingabedatei endet nicht auf .json oder .xml.

Fehler „Unsupported date format“. Ein Datum hat ein anderes Format als 2026-11-11 oder 11.11.2026.

Abbruch bei Anlagen. Bei einer Anlage fehlt filename.

Das Programm macht weiter, bevor die Rechnung fertig ist. PowerShell mit & oder VBA mit Shell warten nicht. Nehmen Sie Start-Process -Wait bzw. WScript.Shell.Run … , True (siehe Beispiele und Access/Excel).

Der Empfänger lehnt die Rechnung ab. Pflichtangaben des Formats fehlen, z. B. Leitweg-ID oder Kontakt bei XRechnung. Siehe Pflichtfelder und die Seite Fehlermeldungen und häufige Probleme lösen.

Ergebnis prüfen

Prüfen Sie die ersten Rechnungen, die Ihr Programm erzeugt, und nach jeder Änderung am Ablauf:

• In der PDF24 Toolbox mit dem Werkzeug „E-Rechnung prüfen“, oder online: E-Rechnung prüfen. Beide prüfen XRechnung, ZUGFeRD/Factur-X und Peppol, als XML oder PDF, mit den offiziellen Regeln und erklären die Meldungen.
• Ob in einer PDF eine XML steckt, sehen Sie im PDF24 Reader unter „Anhänge“ (im Adobe Acrobat Reader unter „Anlagen“, Büroklammer). Dort muss factur-x.xml oder xrechnung.xml stehen.

Wenn etwas nicht funktioniert, wie es hier beschrieben ist, schreiben Sie uns an team@pdf24.org. Senden Sie den vollständigen Befehl, die Eingabedatei (gern mit geänderten Namen und Beträgen) und die Meldungen aus der Konsole mit.