zugcmd – l'outil en ligne de commande pour ZUGFeRD et XRechnung

Exemples de code

Ligne de commande

Publié le

2026-10-12

zugcmd.exe est l'outil en ligne de commande du SDK Aloaha ZUGFeRD. Il permet de créer et de traiter des factures électroniques selon EN 16931 (ZUGFeRD, Factur-X, XRechnung) sans écrire de code : depuis des fichiers batch, des tâches planifiées, des scripts, VBA/Access ou directement depuis SQL Server. Chaque appel renvoie un code retour, ce qui facilite l'intégration de zugcmd dans les processus existants.

Ce que zugcmd sait faire

• Créer du ZUGFeRD à partir de CSV : vendeur, acheteur, lignes, totaux et remises/charges proviennent de simples fichiers CSV ; le résultat est le XML ZUGFeRD/XRechnung et, si nécessaire, le PDF/A-3 ZUGFeRD finalisé.
• Intégrer un XML dans un PDF : un XML ZUGFeRD/XRechnung existant est intégré dans votre facture PDF (PDF/A-3).
• PDF à partir du XML via un modèle Word : sans PDF existant, zugcmd crée la facture à partir d'un modèle DOCX.
• Exporter des factures électroniques en CSV : un XML ZUGFeRD/XRechnung ou un PDF ZUGFeRD est redécomposé en fichiers CSV – par ex. pour l'import dans votre comptabilité.
• Visualisation DOCX : un document Word lisible est créé à partir du XML.
• Fichiers ASCII/DAT : les données de facture au format SAP/inconso (« SATZART ») sont converties directement en ZUGFeRD.
• Signature (nouveau en 11.0.0.3) : signer des PDF existants ou la facture ZUGFeRD qui vient d'être créée – avec un certificat local ou via la signature à distance CodeB (PAdES) de la CodeB EUID Wallet, même en un seul appel.

En interne, zugcmd utilise les mêmes fonctions que votre propre code, comme ImportCSV, MergeXMLIntoPDF, CreateDocFromXML et SignPDFRemote.

Téléchargement et mise en place

zugcmd est disponible sous forme de zugcmd.zip sur la page de téléchargement – avec des fichiers CSV d'exemple et un readme.txt détaillé. Certaines fonctions de la bibliothèque fournie doivent être enregistrées une fois dans le système : exécutez zugcmd une fois avec des droits d'administrateur (par ex. avec une première facture) ou installez l'un des programmes d'installation de la page de téléchargement. Pour les fonctions sous licence, transmettez votre clé de licence avec -l ; vous obtenez une licence d'essai gratuite auprès de info@aloaha.com.

Prérequis : zugcmd à partir de la version 11 nécessite le .NET Framework 4.7.2 (déjà inclus dans Windows 10 à partir de la version 1803 et dans Windows 11). Les versions 10 et antérieures fonctionnent avec le runtime .NET Framework 3.5.

Intégration dans votre propre application : la construction des fichiers CSV, le lancement de zugcmd depuis Delphi, VB6 ou un autre langage et l'évaluation du code retour sont décrits dans Créer des factures électroniques par CSV et zugcmd depuis votre application – avec des fichiers d'exemple testés.

Paramètres

Les paramètres commencent par - ou / (par ex. -x ou /x). Mettez entre guillemets les chemins contenant des espaces.

Général

Fichiers d'entrée et de sortie

Fichiers CSV (import et export)

Signature (à partir de la version 11.0.0.3)

La signature à distance passe par le CodeB Remote Signature Service – qui fait partie du logiciel CodeB EUID Wallet, désormais utilisé aussi pour ZUGFeRD.

Avec -i seul (et éventuellement -o), zugcmd signe un PDF existant. Combiné à la création ZUGFeRD – intégration XML, CSV, modèle Word ou ASCII –, le PDF de sortie généré est signé tout à la fin, de sorte que le XML intégré reste inchangé. Si -remoteurl est défini, la signature à distance a priorité sur -cert.

Si la signature échoue, aucun PDF non signé ne reste sous le nom cible : zugcmd le renomme en <nom>.pdf.unsigned (code retour 60 ou 1). Si une signature a été demandée mais qu'aucun PDF de sortie n'a été créé, zugcmd se termine avec le code retour 62. Ainsi, un processus en aval qui ne cherche que le fichier PDF ne peut jamais transmettre par erreur une facture non signée.

La structure des fichiers CSV est décrite dans l'article Importer des fichiers CSV dans une XRechnung conforme à ZUGFeRD (en allemand).

Exemples

1. Créer du ZUGFeRD à partir de CSV (XML et 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 <clé-de-licence>

Forme courte avec un répertoire de base – tous les fichiers qui s'y trouvent portent leurs noms par défaut :

zugcmd.exe -d "C:\Daten" -y "," -l <clé-de-licence>

2. Intégrer un XML existant dans un PDF

zugcmd.exe -x "C:\Daten\rechnung.xml" -i "C:\Daten\rechnung.pdf" ^
  -o "C:\Daten\zugferd.pdf" -l <clé-de-licence>

3. Exporter ZUGFeRD ou XRechnung en CSV

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 <clé-de-licence>

Au lieu du XML, -r accepte aussi directement un PDF ZUGFeRD. Pour en savoir plus : Convertir des factures ZUGFeRD en CSV (en allemand).

4. Fichier ASCII/DAT (SAP/inconso) vers ZUGFeRD

zugcmd.exe -a "rechnung.DAT" -i "rechnung.pdf" -o "zugferd.pdf" -f true ^
  -l <clé-de-licence>

5. Visualisation DOCX

Ajoutez -v "C:\Daten\visualisierung.docx" à n'importe lequel des appels ; zugcmd écrit alors une version Word lisible de la facture.

6. PDF à partir du XML via un modèle Word

zugcmd.exe -x "C:\Daten\rechnung.xml" -w "C:\Daten\Vorlage.docx" ^
  -o "C:\Daten\rechnung.pdf" -l <clé-de-licence>

Les espaces réservés du modèle sont expliqués dans l'article Modèle Word et espaces réservés (en allemand).

7. De CSV vers PDF via le modèle Word (en deux étapes)

L'import CSV et le modèle Word ne peuvent pas être combinés en un seul appel. Créez d'abord le XML à partir des fichiers CSV, puis le PDF à partir du modèle :

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 <clé-de-licence>

zugcmd.exe -x "C:\Daten\zugferd.xml" -w "C:\Daten\Vorlage.docx" ^
  -o "C:\Daten\zugferd.pdf" -l <clé-de-licence>

Important pour la deuxième étape : utilisez des chemins complets et ne faites pas pointer -d sur le dossier CSV – sinon l'appel est de nouveau traité comme un import CSV et le modèle est ignoré. Le fichier de sortie ne doit pas encore exister à cette étape. À la première étape, un avis concernant le PDF d'entrée manquant (code retour 57/58) peut apparaître ; le XML est tout de même écrit.

8. Signer un PDF existant par signature à distance

set ZUGCMD_REMOTE_PASSWORD=VOTRE-MOT-DE-PASSE
zugcmd.exe -remoteurl "https://VOTRE-SERVEUR-CODEB" -remoteuser "benutzer@firma.de" ^
  -level B-LTA -i "C:\Daten\rechnung_zugferd.pdf" -o "C:\Daten\rechnung_signiert.pdf" ^
  -reason "Validation de la facture" -l <clé-de-licence>

9. Créer un PDF ZUGFeRD et le signer en un seul appel

zugcmd.exe -x "C:\Daten\rechnung.xml" -i "C:\Daten\basis.pdf" -o "C:\Daten\rechnung_zugferd.pdf" ^
  -remoteurl "https://VOTRE-SERVEUR-CODEB" -remoteuser "benutzer@firma.de" -l <clé-de-licence>

Avec -cert "<empreinte>" à la place des paramètres -remote…, le PDF de sortie est signé avec votre certificat local.

Valeurs de retour (codes retour)

0 signifie succès, toute autre valeur une erreur. Les fichiers batch, VBA ou SQL Server peuvent donc évaluer directement le résultat.

Exemple de fichier batch :

zugcmd.exe -d "C:\Daten" -y ";" -silent -l <clé-de-licence>
if errorlevel 1 echo Echec de la creation ZUGFeRD, ExitCode %errorlevel%

Autres outils en ligne de commande

• Conversion directe de doc/docx en PDF/A (en allemand)
• Impression en ligne de commande de documents Office doc/docx (en allemand)
• Convertir un XML ZUGFeRD en Word (DOCX) (en allemand)
• Tous les articles sur les outils en ligne de commande (en allemand)

Vous préférez une interface graphique ? L'Aloaha ZUGFeRD GUI crée, modifie et signe des fichiers ZUGFeRD en quelques clics. Lancé sans arguments, zugcmd affiche un bref aperçu de tous les paramètres.