at_rechnungstellung – Anwender- und Administrator-Handbuch

Version 1.1.0 · Redmine 5.1 und 6 · GPLv2

Dieses Handbuch beschreibt Installation, Konfiguration und täglichen Einsatz des atori-Rechnungstellung-Plugins.

1. Überblick

Das Plugin ergänzt Redmine um Kundenstammdaten, einen Rechnungsworkflow von Entwurf bis bezahlt, ZUGFeRD 2.x-konforme PDF-Ausgabe und Zahlungsverfolgung. Rechnungen sind unabhängig von Redmines Projekt- und Ticket-Modell, einzelne Rechnungspositionen können aber freigegebene TimeEntry-Datensätze referenzieren, um abrechenbare Positionen direkt aus erfassten Stunden zu bilden.

Zentrale Begriffe:

Kunde – Stammdatensatz mit Anschrift und Bankverbindung, Steuernummer, USt-IdNr. und einer Zuordnung zu einem oder mehreren Redmine-Projekten.
Rechnung – gehört zu genau einem Kunden. Durchläuft fünf Zustände: Entwurf, ausgestellt, teilweise bezahlt, bezahlt, storniert. Nur Entwurf-Rechnungen sind editierbar. Rechnungsnummern werden beim Übergang zu ausgestellt automatisch vergeben.
Rechnungsposition – eine Zeile auf einer Rechnung. Menge, Einheit, Einzelpreis, USt.-Satz, optionaler Text. Kann für die Nachvollziehbarkeit auf TimeEntry-Datensätze verweisen.
Zahlung – ein eingegangener Betrag zu einer Rechnung. Löst automatische Statuswechsel aus: Teilzahlungen führen zu teilweise bezahlt, Volleingänge zu bezahlt.
E-Rechnungsausgabe – jeder Kunde wird mit einem von drei Formaten konfiguriert: ZUGFeRD (hybrides PDF/A-3 mit eingebettetem EN-16931-XML – der etablierte B2B-Standard), XRechnung (reines XML, Pflichtformat für deutsche Behörden, mit vorgeschriebener Leitweg-ID) oder none (reine PDF, kein eingebettetes oder beigelegtes XML). Die Auswahl liegt in den Kundenstammdaten, nicht an der einzelnen Rechnung.

2. Voraussetzungen

Redmine 5.1.0 oder neuer
Ruby 3.0 oder neuer
Gems prawn und prawn-table (werden über das Plugin-Gemfile installiert)
Schreibzugriff auf files/ für generierte PDFs

3. Installation

Aus einem Release-Archiv

cd /pfad/zu/redmine
unzip at_rechnungstellung-1.2.0.zip -d plugins/
bundle install
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# Redmine neu starten

bundle install ist hier erforderlich, weil das Plugin ein eigenes Gemfile mit prawn und prawn-table mitbringt.

Aus einem Git-Checkout

cd /pfad/zu/redmine
git clone <repo-url> plugins/at_rechnungstellung
bundle install
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# Redmine neu starten

Installation prüfen

Als Administrator einloggen und Administration → Plugins öffnen. Das Plugin Rechnungstellung sollte mit Version 1.1.0 erscheinen. In der oberen Navigation sollten für berechtigte Benutzer die Einträge Rechnungen und Kunden auftauchen.

Deinstallation

cd /pfad/zu/redmine
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung VERSION=0 RAILS_ENV=production
rm -rf plugins/at_rechnungstellung
# Redmine neu starten

Der Rake-Task rollt die Migrationen zurück und entfernt die plugin-eigenen Tabellen (Kunden, Kunde-Projekt-Zuordnung, Rechnungen, Rechnungspositionen, Zeit-Verweise, Zahlungen). Redmines Kern-Daten werden nicht angerührt.

4. Konfiguration

4.1 Plugin-Einstellungen

Unter Administration → Plugins → Rechnungstellung → Konfigurieren. Die Einstellungen gliedern sich in vier Bereiche:

Absenderdaten – Name, Anschrift, Land, Steuernummer, USt-IdNr., E-Mail, Telefon, Website, Bankverbindung. Diese Angaben füllen Kopf- und Fußzeile jeder generierten PDF.

Rechnungsnummern – Nummernformat (z.B. RG-{YYYY}-{NNNN}), Padding des Zählers, Standardwährung, Standard-USt.-Satz, Standard-Zahlungsziel (in Tagen).

PDF-Layout – Logo-Position (links oder rechts, konfigurierbare Ränder und Breite), Farben (primär, sekundär, Titel, Bruttosumme), Schrift, Tabellenoptik (Zebra-Streifen, Rahmenart, Innenabstand), DIN-5008-Anschriftenfeld, Seitenränder, freie Texte für Intro, Dankesformel und Rechtshinweis.

E-Mail-Versand – Standard-Betreff und -Nachrichtentext, optionale BCC-Adresse für das eigene Archiv.

Einstellungen liegen in einem dedizierten Partial und sind alle reine Formularfelder – keine YAML-Dateien oder Umgebungsvariablen.

4.2 Berechtigungen vergeben

Drei unabhängige globale Rechte stehen zur Verfügung:

Recht	Wirkung	Typische Rolle
Rechnungen ansehen	Rechnungen und Zahlungen lesen	Buchhaltung
Rechnungen verwalten	Anlegen, bearbeiten, ausstellen, stornieren, versenden	Projektleitung, Buchhaltung
Kunden verwalten	CRUD auf Kundenstammdaten	Projektleitung

Alle Rechte sind global (nicht projektbezogen), passend zum typisch organisationsübergreifend arbeitenden Rechnungswesen.

4.3 PDF-Layout mit Demo-Rechnung prüfen

Am Ende der Plugin-Einstellungsseite steht ein Abschnitt Demo-PDF mit einem Download-Link. Er rendert eine Beispiel-Rechnung mit den aktuellen Absenderdaten, Logo, Farben, Nummernformat und PDF-Layout- Einstellungen. Es wird kein echter Kunde und keine echte Rechnung angelegt – die Demo nutzt eine fiktive „Musterfirma GmbH" mit drei Positionen (zwei zum Standard-USt-Satz, eine zu 7%), um das typische Tabellen-Layout, Tausendertrennzeichen und Summen über mehrere Steuersätze durchzuspielen.

Ablauf:

Absenderdaten, Farben, Logo oder Layout-Optionen auf der Einstellungsseite ändern.
Speichern (wichtig — die Demo verwendet die gespeicherten Werte, nicht den aktuellen, ungespeicherten Stand im Formular).
Auf Demo-Rechnung als PDF herunterladen klicken; die PDF öffnet sich in einem neuen Tab.
Falls etwas nicht passt: betreffende Einstellung anpassen, speichern, erneut ziehen.

Die Demo-PDF wird durch denselben Builder erzeugt wie echte Rechnungen – was hier zu sehen ist, bekommt der Kunde später auch.

5. Bedienung

5.1 Kunde anlegen

Kunden → Neuer Kunde. Name, Anschrift, Ländercode (ISO 3166-1 alpha-2) ausfüllen, optional USt-IdNr., Steuernummer und Bankdaten. Ein oder mehrere Redmine-Projekte zuordnen, damit deren Zeiteinträge in Rechnungen für diesen Kunden eingezogen werden können.

Das E-Rechnungsformat des Kunden wählen: ZUGFeRD (Standard, B2B), XRechnung (für öffentliche Auftraggeber) oder none (nur reine PDF). Bei XRechnung-Kunden die Leitweg-ID eintragen – diese ist laut XRechnung-Spezifikation zwingend und wird beim Speichern validiert.

5.2 Entwurfsrechnung anlegen

Rechnungen → Neue Rechnung. Kunde auswählen; die Absenderdaten werden aus den Plugin-Einstellungen übernommen. Positionen manuell eingeben oder über Aus Zeiteinträgen freigegebene Stunden eines Zeitraums und Projekts einziehen. Positionen verschiedener Herkunft lassen sich beliebig mischen – erfasste Stunden neben pauschalen Posten.

Jede Position trägt eigene Einheit, Einzelpreis und USt.-Satz, sodass Rechnungen mit gemischten Sätzen (z.B. 19% + 7% in Deutschland) ohne manuelle Abstimmung korrekte Summen erzeugen.

5.3 PDF-Vorschau

Vorschau rendert die PDF aus dem aktuellen Entwurf, ohne den Stand zu persistieren. Praktisch für optische Kontrollen während der Bearbeitung. Die Vorschau ist nicht nummeriert – Nummernvergabe erfolgt erst bei Ausstellung (siehe nächster Abschnitt).

5.4 Rechnung ausstellen

Ausstellen vergibt die nächste Rechnungsnummer nach dem konfigurierten Format, setzt den Zustand auf ausgestellt und finalisiert das Dokument. Ausgestellte Rechnungen sind schreibgeschützt: PDF und Nummer werden zum kaufmännischen Beleg. Änderungen erfordern eine Stornierung (siehe §5.7) und einen neuen Entwurf.

Die E-Rechnungsausgabe richtet sich nach dem Kundenformat: ZUGFeRD-Kunden erhalten ein hybrides PDF plus eine herunterladbare {nummer}-factur-x.xml; XRechnung-Kunden erhalten eine reine PDF plus eine separate {nummer}-xrechnung.xml; none-Kunden erhalten eine reine PDF ohne XML.

5.5 Rechnung per E-Mail versenden

Per E-Mail senden öffnet einen Editor mit aus den Einstellungen vorbefülltem Betreff und Text. Die PDF wird automatisch angehängt. Eine optionale BCC an das eigene Archivpostfach wird berücksichtigt. Nach Versand wird der Zeitstempel sent_at eingetragen.

5.6 Zahlung erfassen

Neue Zahlung auf der Rechnungsseite: Datum, Betrag und optionaler Verwendungszweck (Banktransaktions-ID, Schecknummer). Teilzahlungen setzen die Rechnung auf teilweise bezahlt und reduzieren den offenen Betrag in der Anzeige. Eine Zahlung, die den vollen Betrag abdeckt, bringt die Rechnung in den Zustand bezahlt.

Zahlungen lassen sich löschen, um Fehler zu korrigieren; der Zustand der Rechnung wird aus den verbleibenden Zahlungen neu berechnet.

5.7 Rechnung stornieren

Eine ausgestellte Rechnung, die sich als fehlerhaft erweist, wird storniert, nicht gelöscht. Stornieren erzeugt eine Stornorechnung mit eigener Nummer und verknüpft sie mit dem Original. Beide bleiben für den Audit-Trail erhalten, und die Zahlungsverfolgung spiegelt nach Stornierung die Nullbilanz wider.

5.8 Offene Posten und Reporting

Die Rechnungen-Liste hat Filter für offen, überfällig, bezahlt, storniert und Datumsbereiche. Überfällig wird aus dem Fälligkeitsdatum relativ zu heute berechnet. CSV-Export über den Standard-Listen-Export von Redmine.

6. Troubleshooting

PDF-Rendering schlägt mit „prawn not found" o.ä. fehl. Das Plugin-Gemfile deklariert prawn und prawn-table. Nach Installation bundle install im Redmine-Verzeichnis ausführen und den Redmine-Prozess neu starten.

Zeiteinträge erscheinen nicht beim Einziehen aus Zeit. Prüfen, dass (1) dem ausgewählten Kunden das Quellprojekt in den Stammdaten zugeordnet ist, (2) der Datumsbereich die Einträge abdeckt und (3) die Einträge im at_zeiterfassung-Plugin als freigegeben markiert sind, sofern Freigaben vorgeschrieben sind. Nicht freigegebene Einträge werden bewusst ausgefiltert.

Rechnungsnummer wird nicht vergeben. Rechnungsnummern werden beim Übergang zu ausgestellt vergeben, nicht beim Speichern des Entwurfs. Den Zustand der Rechnung prüfen – ein Entwurf zeigt „noch keine Nummer" und bleibt vollständig editierbar.

Empfänger akzeptiert das E-Rechnungs-XML nicht. Zuerst das Kundenformat prüfen. Öffentliche Auftraggeber in Deutschland verlangen üblicherweise XRechnung (reines XML, Leitweg-ID validiert) – nicht ZUGFeRD. Private Empfänger akzeptieren in der Regel ZUGFeRD (hybrides PDF/A-3 mit eingebettetem EN-16931-XML). Format des Kunden auf die Anforderung des Empfängers setzen und neu ausstellen. Wird eine bestimmte Profilvariante verlangt (Factur-X Basic, EN 16931 Comfort, XRechnung-CII) und die Ausgabe abgelehnt, mit der exakten Anforderung des Empfängers melden – wir prüfen die Profil-Konformität.

XRechnung-Kunde lässt sich nicht speichern: „Leitweg-ID darf nicht leer sein". Die Leitweg-ID ist Pflicht für Kunden mit E-Rechnungsformat XRechnung. Die vom öffentlichen Empfänger mitgeteilte Leitweg-ID eintragen oder das Format auf ZUGFeRD oder none ändern, falls XRechnung nicht tatsächlich erforderlich ist.

Logo-Platzierung oder Farben greifen nicht. Plugin-Einstellungen sind gecached. Nach Änderungen am PDF-Layout den Redmine-Prozess neu starten oder den Rails-Cache leeren. Logo-Pfade werden relativ zum Redmine-Root aufgelöst; das Bild vor dem Verweis in eine stabile Ablage kopieren oder verlinken.

E-Mail-Versand schlägt fehl. Genutzt werden die Standard-Mailer-Einstellungen von Redmine (config/configuration.yml → email_delivery). Wenn Ticket-E-Mails funktionieren, Rechnungs-E-Mails aber nicht, die Anhang-Größenlimits des ausgehenden SMTP-Servers prüfen – Rechnungs-PDFs mit reichhaltigem Layout können einige hundert KB erreichen.

7. Support

Support ist für zwölf Monate ab Kaufdatum enthalten.

E-Mail: support@atori.de Erstreaktion: werktags innerhalb von 48 Stunden.

Bitte in Supportanfragen angeben:

Redmine-Version (z.B. 5.1.5 oder 6.1.2)
Plugin-Version (sichtbar unter Administration → Plugins)
Browser und Browserversion
Schritte zur Reproduktion und das beobachtete Verhalten
Relevante Zeilen aus log/production.log, sofern verfügbar
Wo sinnvoll, eine anonymisierte Kopie der erzeugten PDF (Kundendaten bei Bedarf schwärzen)