einvoice/Documentation.md

Documentation

Resilienz & Logs

• YAML wird strikt validiert (Pydantic) -> frühzeitige, klare Fehler.
• Pro Run: out/logs/run.log (DEBUG-level File Log, inkl. Stacktraces).
• Mustang stdout/stderr wird ebenfalls geloggt.

PDF Rendering

Priorität:

1. WeasyPrint (wenn installiert)
2. wkhtmltopdf (wenn vorhanden)

Wenn beides fehlt -> klarer Fehler.

Combine + Validate (Mustang) – standardmäßig aktiv

Combine: java -jar Mustang-CLI.jar --action combine --source invoice.pdf --source-xml factur-x.xml --out invoice.facturx.pdf --profile E

Validate: java -jar Mustang-CLI.jar --no-notices --action validate --source invoice.facturx.pdf

YAML Schema

Siehe examples/invoice.sample.yaml

Hinweis zum XML

Aktuell erzeugt facturx.py ein minimal stabiles EN16931 XML (Nummer/Datum/Währung/Gesamt). Für maximale Empfänger-Kompatibilität erweitere facturx.py um Seller/Buyer/Lines/Tax breakdown etc.

Init Command

jr-einvoice init <invoice_dir> erstellt:

• invoice.yaml (Vorlage)
• optional assets/ Ordner (für Logos etc.)
• .gitkeep Dateien damit Git die Ordner behält

Damit kannst du pro Rechnung einen neuen Ordner anlegen und direkt editieren.

Presets

• presets/seller.default.yaml: deine Standard-Seller- und Payment-Daten
• presets/customers.yaml: Kunden-Vorlagen (case-insensitive Keys)

Init merge order:

1. examples/invoice.init.yaml (Basis)
2. presets/seller.default.yaml
3. presets/customers.yaml (wenn --customer gesetzt)
4. Smart defaults (heutiges Datum, due_days, reference)

Assets / Logo

jr-einvoice init kopiert standardmäßig assets/logo.svg nach <invoice_dir>/assets/logo.svg. Das Template referenziert assets/logo.svg relativ – WeasyPrint bekommt dafür base_url=<invoice_dir>.

Setup Mustang

jr-einvoice setup-mustang lädt das Jar von Maven Central (repo1.maven.org) und prüft optional die .sha1 Datei.

Auto-Rechnungsnummer

Wenn du bei init keine --invoice-number angibst, aber --invoices-root setzt, dann wird die nächste Nummer vorgeschlagen.

Standard-Pattern: YYYY-NNNN (z.B. 2026-0007). Gesucht wird in Ordnernamen unter --invoices-root.

Implementierung: jr_einvoice/invoice_number.py.

Customer Presets (Datei pro Kunde)

Bevorzugt: presets/customers/<customer>.yaml

Fallback: presets/customers.yaml (Map customers:)

Mustang Update Check

jr-einvoice mustang-update liest Maven metadata und vergleicht mit tools/mustang/VERSION.txt. Mit --apply wird die neueste Version geladen und installiert (inkl. optional SHA1-Check).

Auto Folder Name

Mit jr-einvoice init invoices --auto-folder --customer unicredit wird ein Unterordner erzeugt:

Rechnung_<invoice_number>_<customer>

Sanitizing/slugging in jr_einvoice/folder_naming.py.

Open Editor

Mit --open wird invoice.yaml nach dem Init in $EDITOR geöffnet. Fallback-Reihenfolge: code, codium, nano, vim, vi.

Script output

• --print-path prints the created folder path after the panel
• --print-path-only prints only the path (no rich output)

Auto open

• --open opens unconditionally (needs an editor available)
• --open-auto opens only when a GUI session is detected (DISPLAY/WAYLAND_DISPLAY) and stdout is a TTY

Generate artifact output

Options:

• --print-artifacts: prints paths after the rich OK output

• --print-artifacts-only: prints only the paths (one per line) in this order:

  1. invoice.pdf
  2. factur-x.xml
  3. invoice.facturx.pdf
  4. validation/validate_report.xml
  5. out/logs/run.log

• --json: prints a JSON object with keys:

  • invoice_dir, out_dir, invoice_pdf, facturx_xml, facturx_pdf, validate_report, log