# einvoice – Rechnung mit einem Konsolenaufruf

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
export PATH="$PWD/bin:$PATH"

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.

**Für die verwaltete Laufzeit die Starter aus `bin/` verwenden:**

```bash
export PATH="/home/johannes/localdev/einvoice/bin:$PATH" # bei Bedarf in ~/.zshrc aufnehmen
# alternativ ohne PATH-Einrichtung:
./bin/einvoice --customers
./bin/einvoice --update --apply
```

Diese PATH-Zeile nach einer eventuellen venv-Aktivierung 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).

## 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)