236 lines
11 KiB
Markdown
236 lines
11 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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](docs/desktop-ui.md).
|
||
|
||
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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```text
|
||
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](docs/e-rechnung-2027.md).
|
||
|
||
Ein vollständiger Ablauf mit Projektbeschreibung, PDF-Anhang, Mailbetreff,
|
||
Textvorlage und Versand steht im [fiktiven Halian-Beispiel](docs/beispiel-workflow-halian.md).
|
||
|
||
## Optionen für Alltag und Skripte
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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:**
|
||
|
||
```bash
|
||
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](Documentation.md#updates-und-rollback).
|
||
|
||
## 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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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](Documentation.md) ·
|
||
[Rechtsstand und Abgleich mit der INTEGRA-Mail](docs/e-rechnung-2027.md)
|