einvoice/README.md

einvoice – Rechnungen per Oberfläche oder Konsolenaufruf

Desktop-Oberfläche

Vorlage laden → Daten prüfen und ergänzen → E-Rechnung erstellen → fertige PDF im Fenster ansehen. Die lokale Anwendung verwendet dieselbe Berechnung, Nummernvergabe und technische Validierung wie die Konsole. Ein separates Repository ist deshalb nicht erforderlich.

# Auf diesem Rechner eingerichtet:
einvoice-ui
# Alternativ:
einvoice --gui

Im Anwendungsmenü steht JR eInvoice. Kunden lassen sich wiederverwenden oder neu erfassen. Mehrere Positionen mit mehrzeiliger Beschreibung, Mengen, deutschen Nettopreisen, Steuersätzen, Leistungszeitraum und Zahlungsziel sind bearbeitbar. Die Betragsübersicht rechnet sofort mit. „Entwurf ansehen“ zeigt eine PDF ohne Nummernreservierung; „E-Rechnung erstellen“ speichert und validiert die endgültige ZUGFeRD-PDF und zeigt sie direkt an. Ordner und Prüfbericht sind per Knopf erreichbar.

Eigene YAML-Vorlagen und frühere invoice.yaml-Dateien können geladen werden. Dabei werden Nummer und Datumsfelder für eine neue Rechnung zurückgesetzt. Leistungsbeschreibung, Referenzen, Mengen, Preise und Zeitraum vor Erstellung prüfen. Vorlagen ändern das Rechnungsdaten-Gerüst; das Layout kommt weiterhin aus der gemeinsamen HTML/Jinja2-Vorlage. Die PDF-Ansicht ist schreibgeschützt.

Erstinstallation / anderer Rechner:

# Bestehendes Checkout mit funktionierender Laufzeit:
einvoice --update --apply --with-gui
python3 scripts/install_commands.py --desktop

# Entwicklerumgebung (Java und Mustang wie unten einrichten):
pip install -e '.[pdf,gui]'
.venv/bin/einvoice-ui

Die GUI ist optional; reine Konsoleninstallationen benötigen Qt nicht. Nach einem Update mit --with-gui behalten weitere Updates die Oberfläche bei. Rechnungs- und Kundendaten bleiben lokal; die Anwendung versendet keine E-Mails. Bedienung, Installation und technische Details.

Kundenname, Leistung, Menge und Nettopreis eingeben: einvoice --create erledigt Rechnungsnummer, Berechnung, PDF/A-Erstellung, Einbettung des EN16931-XML und technische Validierung. Das fertige ZUGFeRD/Factur-X-PDF kannst du direkt an eine E-Mail anhängen. Alles läuft lokal.

Direkt loslegen

Auf diesem Rechner sind Python-Umgebung, Absenderdaten und Mustang eingerichtet.

cd /home/johannes/localdev/einvoice
python3 scripts/install_commands.py  # einmalig; auf diesem Rechner bereits eingerichtet

einvoice --create \
  --Customer "Meine Kundenfirma GmbH" \
  --Entry "Geleistete Stunden Oktober 2026" \
  --Volume 120 \
  --Price "85,00 €"

Bei einem neuen Kunden fragt die Konsole einmalig Straße/Hausnummer, Postleitzahl und Ort ab. Bei späteren Rechnungen genügt der gleiche Kundenname. Groß- und Kleinschreibung sind beim Kundennamen gleichgültig. einvoice --customers listet die gespeicherten Kunden samt Schlüssel auf. Es ist kein Standardkunde vorgewählt. IDV ist ausschließlich ein historisches Beispiel aus früheren Rechnungen.

Der Preis ist netto je Einheit. Standard: Stunden (HUR), 19 % USt, heute als Rechnungsdatum und 30 Tage Zahlungsziel. Im Beispiel entstehen 10.200,00 EUR netto, 1.938,00 EUR USt und 12.138,00 EUR brutto. „Oktober 2026“ in der Beschreibung wird als Leistungsmonat erkannt. Für Teilmonate/andere Leistungen --Month oder --ServiceDate ausdrücklich setzen und die tatsächlichen Leistungsdaten verwenden.

Rechnungsdaten vollständig: JR-2026-0001 · Meine Kundenfirma GmbH
PDF/A und strukturierte Rechnungsdaten werden erzeugt …
Rechnung validiert: PDF/A und EN16931-XML technisch gültig.
Rechnung erzeugt · Netto: 10.200,00 EUR · USt: 1.938,00 EUR · Brutto: 12.138,00 EUR
Leistung: 2026-10-01 bis 2026-10-31
PDF zum Anhängen an deine E-Mail:
…/Rechnung_JR-2026-0001_…/Rechnung_JR-2026-0001.pdf
Prüfbericht: …/out/validation/validate_report.xml
Vor Versand Leistungsdaten, Betrag und Empfänger prüfen.

Die ausgegebene Rechnung_<Nummer>.pdf ist die vollständige E-Rechnung, inklusive XML. Direkt anhängen; nicht über einen PDF-Drucker neu drucken, weil dabei das XML verloren gehen kann. Die Ausgabe bestätigt die erfolgreiche technische Prüfung. Sie garantiert nicht pauschal die sachliche oder steuerliche Richtigkeit deiner Eingaben. Details: Rechtsstand und Grenzen.

Ein vollständiger Ablauf mit Projektbeschreibung, PDF-Anhang, Mailbetreff, Textvorlage und Versand steht im fiktiven Halian-Beispiel.

Optionen für Alltag und Skripte

# Neue Kundenanschrift ohne Rückfragen übergeben:
einvoice --create --Customer "Neue Firma GmbH" \
  --Street "Kundenstraße 12" --PostalCode 10115 --City Berlin \
  --Email rechnung@empfaenger.example \
  --Entry "IT-Beratung" --Volume "7,5" --Price "120,00 EUR" \
  --ServiceDate 2026-10-15 --non-interactive

# Bekannter Kunde, expliziter Monat und Bestellbezug:
einvoice --create --Customer "Meine Kundenfirma GmbH" \
  --Entry "Softwareentwicklung" --Volume 120 --Price "85,00 €" \
  --Month 2026-10 --OrderReference "PO-12345" --DueDays 14

# Beispiel für eine Stückposition:
einvoice --create --Customer "Meine Kundenfirma GmbH" \
  --Entry "Dokumentationspaket" --Volume 1 --Unit C62 --Price "500,00 €"

Weitere Optionen: --Number, --Date, --Tax, --BuyerReference, --Country, --VatId, --root, --json. Alle Fachoptionen haben auch kleingeschriebene Varianten (--customer, --entry, …); einvoice --help zeigt sie an. --json liefert Artefaktpfade und den technischen Prüfstatus ohne Fragen.

Die Nummer lautet automatisch JR-JJJJ-NNNN und wird im Rechnungsstamm unter Dateisperre vergeben. --Number setzt eine ausdrücklich gewählte freie Nummer. Vorhandene PDF-Rechnungen außerhalb dieses Stamms werden nicht automatisch eingelesen. Das Präfix JR trennt die neue Serie von früheren JJJJ-MM-Nummern. Bei einem technischen Fehler bleibt der reservierte Entwurf samt Log zur Diagnose erhalten; zum Wiederholen jr-einvoice generate <Rechnungsordner> verwenden.

Abhängigkeiten sicher aktualisieren

cd /home/johannes/localdev/einvoice
python3 scripts/update.py           # neueste kompatible Pakete + Mustang aufbauen und testen
python3 scripts/update.py --apply   # testen, aktivieren, nochmals prüfen
python3 scripts/update.py --status  # aktiven Stand anzeigen (offline)
python3 scripts/update.py --rollback # vorherigen Stand prüfen und wieder aktivieren (offline)

Der Ablauf prüft Python-Paketabhängigkeiten, WeasyPrint/PDF-Erzeugung, beide CLIs und die vollständige Testsuite einschließlich echter Mustang-Validierung und ungültiger Gegenbeispiele. Schlägt ein Test vor Aktivierung fehl, bleibt die bisherige Laufzeit aktiv. Schlägt die Prüfung danach fehl, wird automatisch zurückgeschaltet. Die Konsole zeigt Schritte, Versionsänderungen und Fehler; vollständige Logs liegen in .runtime/logs/. Netzwerk ist nur für neue Kandidaten nötig. Ohne --apply werden Downloads, Installation und Tests ausgeführt, aber keine Umschaltung.

Konsolenbefehle einmalig im Benutzer-Suchpfad einrichten:

python3 scripts/install_commands.py
# Danach aus jedem Verzeichnis, ohne venv-Aktivierung:
einvoice --customers
einvoice --update --apply
einvoice --update --rollback
jr-einvoice --help

Der Installer verlinkt die Konsolen- und GUI-Starter nach ~/.local/bin und prüft die Konsole. Dort vorhandene andere Befehle werden vor dem Ersetzen gesichert. Wiederholtes Ausführen ist möglich. Auf diesem Rechner ist das Verzeichnis bereits im PATH. Bei einem gespeicherten alten Shell-Pfad einmal rehash (zsh) bzw. hash -r (bash) ausführen. Eine aktivierte .venv kann die Befehle überdecken: dann deactivate ausführen. Direkte Aufrufe von .venv/bin/einvoice verwenden weiterhin die ursprüngliche Entwicklerumgebung. Java und native Bibliotheken werden mitgetestet, aber über den Systempaketmanager aktualisiert; dessen Änderungen kann dieser Updater nicht zurückrollen. Details und Grenzen: Update-Betrieb.

Ohne Microsoft Office / Microsoft 365

Die Rechnungslösung benötigt weder Word, Excel, Outlook noch Microsoft 365. Es gibt keine DOC/DOCX-, XLS/XLSX- oder PPT/PPTX-Vorlagen und keine Office-Automation. Auch LibreOffice muss zur Rechnungserstellung nicht installiert sein.

Zweck	Verwendetes Format
Rechnungsdaten und Stammdaten	YAML (.yaml)
Layout	HTML/Jinja2 (.html.j2), Logo als SVG
Fertige E-Rechnung	PDF/A-3 mit eingebettetem EN16931-XML
Optionaler Mailentwurf	EML (.eml), ohne Outlook-Anbindung
Dokumentation	Markdown (.md)

Ein Wechsel auf LibreOffice erfordert für dieses Projekt keine Dateikonvertierung. ODT-/ODS-Dateien werden aktuell weder eingelesen noch erzeugt. Layoutänderungen finden in der HTML-Vorlage statt. Das fertige E-Rechnungs-PDF direkt versenden; nicht zum Bearbeiten konvertieren oder neu als PDF exportieren, da eingebettete Rechnungsdaten oder die geprüfte PDF/A-Struktur verloren gehen können. Die tatsächliche E-Mail-Zustellung erfolgt weiterhin über dein separat eingerichtetes Mailprogramm bzw. Konto; sie wird von diesem Tool nicht bereitgestellt.

Daten und Einrichtung

• Absender: johannes@jr-it-services.de, lokale Vorlage private/presets/seller.default.yaml.
• Kunden: private/presets/customers/; neue Kunden werden dort mit geschützter Dateiberechtigung gespeichert.
• Rechnungen: private/invoices/, jeweils in einem eigenen geschützten Ordner.
• Eigenes Logo optional: private/presets/logo.svg, sonst mitgeliefertes JR-Logo.
• Persönliche Daten, Rechnungen und Ausgabeordner werden nicht mit Git veröffentlicht.

Andere Datenablage: JR_EINVOICE_HOME=/absoluter/pfad; nur die Vorlagen umleiten: JR_EINVOICE_PRESETS=/absoluter/pfad. Nach Wheel-Installation ist der Standard ~/.local/share/jr-einvoice/. Bei einem frischen Checkout zuerst die vollständigen eigenen Absender-/Zahlungsdaten lokal konfigurieren; create verwendet keine versionierten Musteradressen als echte Geschäftsdaten.

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[pdf]'
jr-einvoice setup-mustang --version 2.26.0

Java und die WeasyPrint-Systembibliotheken müssen installiert sein; für Arch siehe scripts/arch_install.sh. Die bisherigen jr-einvoice-Befehle bleiben verfügbar: YAML-Entwürfe, mehrere Positionen, Neuerzeugung, Eingangskontrolle und optionaler EML-Mailentwurf mit Absender aus den eigenen Stammdaten.

jr-einvoice email /pfad/zum/rechnungsordner --to rechnung@empfaenger.example
jr-einvoice validate /pfad/eingangsrechnung.xml --report private/eingang-pruefung.xml
python -m unittest discover -s tests -v
JR_EINVOICE_INTEGRATION=1 python -m unittest discover -s tests -v

Unterstützt werden normale positive EUR-Rechnungen mit positiver Umsatzsteuer. Steuerbefreiungen/Kleinunternehmer, Reverse Charge, Gutschriften/Storno und XRechnung-Ausgabe sind noch nicht implementiert. Archivierung, DATEV-/Peppol- Anbindung und Versandnachweis bleiben im betrieblichen Ablauf. Nach dem Versand PDF, strukturierte Daten, Prüfbericht und Versandnachweis gesichert aufbewahren.

Ausführliche Dokumentation · Rechtsstand und Abgleich mit der INTEGRA-Mail