162 lines
7.8 KiB
Markdown
162 lines
7.8 KiB
Markdown
# 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)
|