- Thema
- Kommandozeilen-Tools
- Codebeispiele
- Kommandozeile
- Veröffentlicht
zugcmd.exe ist das Kommandozeilen-Tool der Aloaha ZUGFeRD SDK. Damit erzeugen und verarbeiten Sie elektronische Rechnungen nach EN 16931 (ZUGFeRD, Factur-X, XRechnung) ohne eigene Programmierung: aus Batch-Dateien, geplanten Tasks, Skripten, VBA/Access oder direkt vom SQL Server. Jeder Aufruf liefert einen Rückgabewert (ExitCode), sodass sich zugcmd leicht in bestehende Abläufe einbinden lässt.
Was zugcmd kann
- ZUGFeRD aus CSV erzeugen: Verkäufer, Käufer, Positionen, Summen und Zu-/Abschläge kommen aus einfachen CSV-Dateien; heraus kommt das ZUGFeRD-/XRechnung-XML und auf Wunsch die fertige ZUGFeRD-PDF/A-3.
- XML in ein PDF einbetten: ein vorhandenes ZUGFeRD-/XRechnung-XML wird in Ihr Rechnungs-PDF eingebettet (PDF/A-3).
- PDF aus XML über eine Word-Vorlage: ohne vorhandenes PDF erzeugt zugcmd die Rechnung aus einer DOCX-Vorlage.
- E-Rechnungen nach CSV exportieren: ein ZUGFeRD-/XRechnung-XML oder ein ZUGFeRD-PDF wird wieder in die CSV-Dateien zerlegt – z. B. für den Import in Ihre Buchhaltung.
- DOCX-Visualisierung: aus dem XML entsteht ein lesbares Word-Dokument.
- ASCII-/DAT-Dateien: Rechnungsdaten im SAP-/inconso-Format („SATZART“) werden direkt nach ZUGFeRD gewandelt.
Intern nutzt zugcmd dieselben Funktionen wie Ihr eigener Code, etwa ImportCSV, MergeXMLIntoPDF und CreateDocFromXML.
Download und Einrichtung
zugcmd liegt als zugcmd.zip auf der Download-Seite – mit Beispiel-CSV-Dateien und einer ausführlichen readme.txt. Einige Funktionen der mitgelieferten Bibliothek müssen einmalig im System registriert werden: Starten Sie zugcmd dazu einmal mit Administratorrechten (z. B. mit einer ersten Rechnungserstellung) oder installieren Sie einen der Installer von der Download-Seite. Für die lizenzierten Funktionen geben Sie Ihren Lizenzschlüssel mit -l an; eine kostenlose Testlizenz erhalten Sie über info@aloaha.com.
Voraussetzung: zugcmd ab Version 11 benötigt das .NET Framework 4.7.2 (in Windows 10 ab Version 1803 und in Windows 11 bereits enthalten). Die Versionen 10 und älter laufen mit der .NET Framework 3.5 Runtime.
Parameter
Parameter beginnen mit - oder / (z. B. -x oder /x). Pfade mit Leerzeichen setzen Sie in Anführungszeichen.
Allgemein
| Parameter | Bedeutung |
|---|---|
-l <Lizenzschlüssel> | Lizenzschlüssel (für lizenzierte Funktionen erforderlich) |
-d <Pfad> | Basis-/Datenverzeichnis. Bloße Dateinamen werden gegen diesen Pfad aufgelöst; für nicht angegebene Dateien gelten die Standardnamen. |
-y <Zeichen> | Trennzeichen der CSV-Dateien, z. B. , oder ; |
-c <Zeichensatz> | Zeichensatz der Eingabe, Standard utf8 (weitere: ansi, ascii, unicode, utf7, utf32) |
-f true|false | Ausgabedatei überschreiben (Standard true); mit -f false bleibt eine vorhandene Datei erhalten |
-silent | keinerlei Ausgabe auf der Konsole |
Ein- und Ausgabedateien
| Parameter | Bedeutung | Standardname |
|---|---|---|
-x <Datei.xml> | Ausgabe-XML (ZUGFeRD/XRechnung) | OutputXML.xml |
-o <Datei.pdf> | Ausgabe-PDF (ZUGFeRD-PDF/A-3) | OutputPDF.pdf |
-i <Datei.pdf> | Eingabe-PDF, in das eingebettet wird | InputPDF.pdf |
-a <Datei> | Eingabe im ASCII-/DAT-Format (SAP/inconso „SATZART“) | – |
-r <Datei.xml|.pdf> | Export: vorhandenes XML bzw. ZUGFeRD-PDF einlesen und nach CSV schreiben | – |
-v <Datei.docx> | DOCX-Visualisierung des XML erzeugen | – |
-w <Vorlage.docx> | Ausgabe-PDF aus dem XML über diese Word-Vorlage erzeugen | – |
CSV-Dateien (Import und Export)
| Parameter | Inhalt | Standardname |
|---|---|---|
-s | Verkäufer / Rechnungssteller | Seller.csv |
-b | Käufer / Rechnungsempfänger | Buyer.csv |
-p | Rechnungspositionen | Items.csv |
-t | Summen und Beträge | Totals.csv |
-z | Zu- und Abschläge | allowances.csv |
-h | Lieferanschrift (Deliver To) | deliverto.csv |
-g | Versandanschrift (Deliver From) | deliverfrom.csv |
Den Aufbau der CSV-Dateien beschreibt der Artikel CSV-Dateien in eine ZUGFeRD-konforme X-Rechnung importieren.
Beispiele
1. ZUGFeRD aus CSV erzeugen (XML und PDF)
zugcmd.exe -x "OutputXML.xml" -o "OutputPDF.pdf" -i "InputPDF.pdf" ^ -b "Buyer.csv" -s "Seller.csv" -p "Items.csv" -t "Totals.csv" ^ -z "allowances.csv" -y "," -l <Lizenzschlüssel>
Kurzform mit Basisverzeichnis – alle Dateien tragen dort ihre Standardnamen:
zugcmd.exe -d "C:\Daten" -y "," -l <Lizenzschlüssel>
2. Vorhandenes XML in ein PDF einbetten
zugcmd.exe -x "C:\Daten\rechnung.xml" -i "C:\Daten\rechnung.pdf" ^ -o "C:\Daten\zugferd.pdf" -l <Lizenzschlüssel>
3. ZUGFeRD oder XRechnung nach CSV exportieren
zugcmd.exe -d "C:\Daten" -r "xrechnung.xml" -b "Buyer.csv" -s "Seller.csv" ^ -p "Items.csv" -t "Totals.csv" -z "allowances.csv" -y "," -l <Lizenzschlüssel>
Statt des XML kann mit -r auch direkt ein ZUGFeRD-PDF angegeben werden. Mehr dazu: ZUGFeRD-Rechnungen nach CSV konvertieren.
4. ASCII-/DAT-Datei (SAP/inconso) nach ZUGFeRD
zugcmd.exe -a "rechnung.DAT" -i "rechnung.pdf" -o "zugferd.pdf" -f true ^ -l <Lizenzschlüssel>
5. DOCX-Visualisierung
Geben Sie bei einem der Aufrufe zusätzlich -v "C:\Daten\visualisierung.docx" an; zugcmd schreibt dann eine lesbare Word-Fassung der Rechnung.
6. PDF aus XML über eine Word-Vorlage
zugcmd.exe -x "C:\Daten\rechnung.xml" -w "C:\Daten\Vorlage.docx" ^ -o "C:\Daten\rechnung.pdf" -l <Lizenzschlüssel>
Die Platzhalter der Vorlage erklärt der Artikel Word-Vorlage und Platzhalter.
7. Von CSV über die Word-Vorlage zum PDF (zwei Schritte)
CSV-Import und Word-Vorlage lassen sich nicht in einem Aufruf kombinieren. Erzeugen Sie zuerst das XML aus den CSV-Dateien und danach das PDF aus der Vorlage:
zugcmd.exe -d "C:\Daten" -x "zugferd.xml" -b "Buyer.csv" -s "Seller.csv" ^ -p "Items.csv" -t "Totals.csv" -z "allowances.csv" -y "," -l <Lizenzschlüssel> zugcmd.exe -x "C:\Daten\zugferd.xml" -w "C:\Daten\Vorlage.docx" ^ -o "C:\Daten\zugferd.pdf" -l <Lizenzschlüssel>
Wichtig für den zweiten Schritt: vollständige Pfade verwenden und -d nicht auf den CSV-Ordner zeigen lassen – sonst wird der Aufruf wieder als CSV-Import behandelt und die Vorlage ignoriert. Die Ausgabedatei darf in diesem Schritt noch nicht existieren. Im ersten Schritt kann ein Hinweis zum fehlenden Eingabe-PDF (ExitCode 57/58) erscheinen; das XML wird trotzdem geschrieben.
Rückgabewerte (ExitCode)
0 bedeutet Erfolg, jeder andere Wert einen Fehler. Damit können Batch-Dateien, VBA oder der SQL Server das Ergebnis direkt auswerten.
| ExitCode | Bedeutung |
|---|---|
| 0 | Erfolg |
| 1 | allgemeiner Fehler |
| 2 | nicht lizenziert bzw. Ausgabedatei nicht gefunden |
| 3 | Word-Vorlage oder Eingabe-PDF fehlt |
| 4 | Dateiname/XML fehlt |
| 55 | Ausgabe-PDF konnte nicht erstellt werden |
| 56 | Ausgabe-PDF existiert bereits |
| 57 | Eingabe-PDF nicht gefunden |
| 58 | Eingabedatei ist kein PDF |
| 59 | XML konnte nicht erstellt werden |
| 99 / 100 | keine (gültigen) Argumente übergeben |
| 101 | ZUGFeRD-Objekt konnte nicht erzeugt werden |
| 102 | ZUGFeRD-Bibliothek nicht geladen bzw. Struktur nicht lesbar |
| 103 / 105 | Laufzeitfehler bei der Verarbeitung |
| 12345 | sonstiger Fehler bei der PDF-Erstellung |
Ein Beispiel für eine Batch-Datei:
zugcmd.exe -d "C:\Daten" -y ";" -silent -l <Lizenzschlüssel> if errorlevel 1 echo ZUGFeRD-Erstellung fehlgeschlagen, ExitCode %errorlevel%
Weitere Kommandozeilen-Tools
- Direkte Konvertierung von doc/docx nach PDF/A
- Kommandozeilendruck von Office-doc/docx-Dokumenten
- ZUGFeRD-XML nach Word (DOCX) konvertieren
- Alle Artikel zu den Kommandozeilen-Tools
Lieber mit Oberfläche? Die Aloaha ZUGFeRD GUI erstellt und bearbeitet ZUGFeRD-Dateien per Mausklick.