Version 1.7.0 · Redmine 5.1 und 6 · GPLv2
Dieses Handbuch beschreibt Installation, Konfiguration und täglichen Einsatz des atori-Rechnungstellung-Plugins.
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:
TimeEntry-Datensätze verweisen.prawn und prawn-table (werden über das Plugin-Gemfile installiert)files/ für generierte PDFscd /pfad/zu/redmine
unzip at_rechnungstellung-1.7.0.zip -d plugins/
bundle install
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# Redmine neu startenbundle install ist hier erforderlich, weil das Plugin ein eigenes Gemfile mit prawn und prawn-table mitbringt.
Als Administrator einloggen und Administration → Plugins öffnen. Das Plugin Rechnungstellung sollte mit Version 1.7.0 erscheinen. In der oberen Navigation sollten für berechtigte Benutzer die Einträge Rechnungen und Kunden auftauchen.
Ein Redmine-Update ist für das Plugin nur dann unkritisch, wenn die Reihenfolge stimmt. Redmine lädt jedes Plugin beim Start; passt ein Plugin nicht zur neuen Version, startet die ganze Instanz nicht, bis der Plugin-Ordner entfernt ist. Die Daten in den Plugin-Tabellen sind davon nie betroffen.
Regel: Jede Plugin-Version unterstützt die aktuelle und die vorherige Redmine-Linie (derzeit 5.1 und 6). Welche Plugin-Version mit welcher Redmine-Version getestet ist, steht in der Freigabe-Übersicht auf redmine-plugins.atori.de.
Reihenfolge beim Update:
redmine:plugins:migrate, Neustart) und auf der alten Redmine-Version kurz prüfen. Diese Brückenversion läuft auf beiden Redmine-Versionen.bundle exec rake redmine:plugins:migrate RAILS_ENV=production und Neustart.Fallweg, wenn keine Brückenversion existiert (etwa weil die neue Redmine-Version ein neueres Ruby verlangt):
cd /pfad/zu/redmine
mv plugins/at_rechnungstellung ../at_rechnungstellung.alt # Ordner beiseitelegen, NICHT migrieren
# Redmine aktualisieren
# neue Plugin-Version nach plugins/at_rechnungstellung entpacken
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# Redmine neu startenDie Plugin-Tabellen bleiben dabei unverändert in der Datenbank; die neue Plugin-Version hebt das Schema mit ihren eigenen Migrationen an.
> Nie VERSION=0 als Teil eines Updates. Die Rückwärtsmigration auf > Version 0 löscht die Plugin-Tabellen und damit alle Daten des Plugins. > Sie gehört ausschließlich zur endgültigen Deinstallation (siehe unten).
> Vorher Rechnungen sichern. Das Plugin legt keine PDF- oder XML-Dateien > ab; beide werden bei jedem Aufruf aus der Datenbank erzeugt. Die Migration > zurück auf Version 0 löscht die Plugin-Tabellen und damit alle Kunden, > Rechnungen, Positionen und Zahlungen endgültig. Rechnungen unterliegen in > Deutschland einer Aufbewahrungspflicht von acht Jahren. Laden Sie deshalb > vor der Deinstallation jede ausgestellte Rechnung als PDF (und ggf. XML) > herunter und legen Sie sie außerhalb von Redmine ab. Ab Version 1.7.0 > erledigt das der Sammelexport in der Rechnungsliste in einem Schritt. > > Wer nur den Plugin-Ordner löscht, ohne die Migration zurückzurollen, > behält die Tabellen in der Datenbank: Redmine zeigt dann nichts mehr an, > eine spätere Neuinstallation findet die Daten aber wieder vor.
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 startenDer 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.
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 als freier Text mit Platzhaltern: {{year}} (Jahr), {{year2}}, {{month}}, {{day}}, {{seq}} (laufende Nummer, Länge über Länge der Sequenz) sowie die Kundenplatzhalter {{customer_prefix}} (Kürzel), {{customer_number}} und {{customer}}; die alte Schreibweise RG-{YYYY}-{NNNN} funktioniert weiterhin. Die laufende Nummer zählt je vollständig aufgelöstem Präfix. Ein Format wie {{customer_prefix}}-{{year}}-{{seq}} ergibt damit einen eigenen Nummernkreis pro Kunde und Jahr. Dazu 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.
Stundensätze – hier wird festgelegt, aus welchem benutzerdefinierten Zahlenfeld (Format Ganzzahl oder Gleitkommazahl) ein abweichender Stundensatz am Ticket bzw. am Projekt gelesen wird. Die Felder legen Sie vorher unter Administration → Benutzerdefinierte Felder an (Typ Tickets bzw. Projekte); für Tickets muss das Feld für die betroffenen Tracker und Projekte aktiviert sein. (nicht verwendet) schaltet die jeweilige Stufe ab. Der Knopf Felder jetzt anlegen erledigt die Einrichtung in einem Schritt: Er legt je ein Gleitkommafeld Stundensatz für Tickets (alle Tracker, alle Projekte) und für Projekte an, macht sie nur für Rollen mit Rechnungsrechten sichtbar und trägt beide ein. Ist das gewählte Ticketfeld für einen Tracker oder ein Kundenprojekt nicht aktiv, zeigt der Block eine Warnung mit Link zur Feldverwaltung, denn Buchungen dort würden still zum Projekt- oder Kundensatz laufen. Details in Abschnitt 5.1.
Einstellungen liegen in einem dedizierten Partial und sind alle reine Formularfelder – keine YAML-Dateien oder Umgebungsvariablen.
Fünf Rechte stehen unter Administration → Rollen und Rechte → Rechnungstellung zur Verfügung:
| Recht | Geltungsbereich | Wirkung | Typische Rolle |
|---|---|---|---|
| Rechnungen ansehen | projektbezogen | Rechnungen, PDF/XML, Zahlungen und Sammelexport für die Kunden der eigenen Projekte | Projektleitung |
| Rechnungen verwalten | projektbezogen | Anlegen, bearbeiten, ausstellen, stornieren, versenden, archivieren für die Kunden der eigenen Projekte | Projektleitung |
| Alle Rechnungen ansehen | global | Alle Rechnungen aller Kunden lesen | Buchhaltung |
| Alle Rechnungen verwalten | global | Alle Rechnungen aller Kunden bearbeiten | Buchhaltung |
| Kunden verwalten | global | Kundenstammdaten anlegen und ändern | Projektleitung, Buchhaltung |
Die Rechte wirken pro Kunde, nicht pro Projekt. Ein Kunde hat in den Stammdaten ein oder mehrere Projekte. Wer in einem dieser Projekte eine Rolle mit Rechnungen ansehen hat, sieht alle Rechnungen dieses Kunden – auch solche, deren Positionen aus einem anderen Projekt desselben Kunden stammen, und auch solche ohne Projektbezug (manuelle Positionen). Eine Rechnung ist ein Dokument des Kunden; sie lässt sich nicht zur Hälfte zeigen.
Beispiel: Kunde Müller GmbH hat die Projekte „Website“ (Projektleitung Anna) und „App“ (Projektleitung Ben). Anna und Ben sehen beide alle Rechnungen der Müller GmbH, auch die des jeweils anderen Projekts. Sollen die Rechnungen getrennt bleiben, legen Sie die Müller GmbH als zwei Kunden an („Müller GmbH – Website“, „Müller GmbH – App“), jeweils mit dem eigenen Projekt.
Die Buchhaltung bekommt die beiden globalen Alle …-Rechte; sie sieht dann unabhängig von Projektmitgliedschaften alles. Kunden verwalten bleibt global, weil Kunden projektübergreifend sind.
> Upgrade-Hinweis (1.6 → 1.7): Rechnungen ansehen und Rechnungen > verwalten waren bis 1.6 global. Die Migration gibt jeder Rolle, die > eines der beiden Rechte hatte, automatisch das passende Alle …-Recht; > für bestehende Installationen ändert sich nichts. Wer die Einschränkung > auf Kunden nutzen will, nimmt den Projektleitungs-Rollen danach das > Alle …-Recht wieder weg.
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:
Die Demo-PDF wird durch denselben Builder erzeugt wie echte Rechnungen – was hier zu sehen ist, bekommt der Kunde später auch.
Kunden → Neuer Kunde. Name, Anschrift, Ländercode (ISO 3166-1 alpha-2) ausfüllen, optional USt-IdNr., Steuernummer und Bankdaten. Der Ansprechpartner wird getrennt nach Anrede, Vorname und Nachname erfasst. Ein oder mehrere Redmine-Projekte zuordnen, damit deren Zeiteinträge in Rechnungen für diesen Kunden eingezogen werden können. Projekte und ihre Zuordnung lassen sich bereits beim Neuanlegen in einem Schritt setzen.
Nummernkreis je Kunde. Das Feld Rechnungsnummern-Präfix ist das Kürzel, das der Platzhalter {{customer_prefix}} im Nummernformat einsetzt (z.B. ACME). Die Start-Rechnungsnummer legt fest, ab welcher laufenden Nummer die nächste Rechnung dieses Kunden gezählt wird; sie wirkt als Untergrenze, bis die laufende Nummer sie überholt hat.
Freigabe je Projekt. In der Projektliste des Kunden trägt jedes Projekt zusätzlich die Option Ohne Freigabe abrechnen. Standardmäßig ist sie aus, d.h. Stunden dieses Projekts müssen über at_zeiterfassung freigegeben sein, bevor sie in Rechnung gestellt werden können. Wird die Option gesetzt, können die Stunden dieses Projekts ohne explizite Freigabe abgerechnet werden.
Mindestgranularität. Das Feld Mindestgranularität (Min.) legt fest, auf welche Einheit at_zeiterfassung beim Stoppen eines Timers die gebuchte Zeit aufrundet (z.B. 15 Minuten). Leer = keine Aufrundung.
Abweichende Stundensätze je Projekt oder Ticket. Der Stundensatz am Kunden ist der Normalfall. Soll ein Projekt oder ein einzelnes Ticket zu einem anderen Satz abgerechnet werden (z.B. Remote-Arbeit günstiger als Einsätze vor Ort), tragen Sie den Satz in das benutzerdefinierte Feld ein, das in den Plugin-Einstellungen unter Stundensätze gewählt ist. Für jede Zeitbuchung gilt dann: Satz des Tickets, sonst Satz des Projekts, sonst Satz des Kunden. Leer oder 0 bedeutet „nicht gesetzt“, die Buchung fällt zur nächsten Stufe durch. Unteraufgaben erben den Satz des nächsthöheren Tickets, das einen hat. Wer das Feld sehen und ändern darf, steuern Sie wie bei jedem benutzerdefinierten Feld über die Rollen; die über Felder jetzt anlegen erzeugten Felder sehen nur Rollen mit Rechnungsrechten, so bleiben Sätze vor übrigen Projektmitgliedern verborgen. Beim Aufbau einer Rechnung aus Zeiten zeigt die Stundenauswahl je Buchung den tatsächlich gezogenen Satz, und Stunden mit unterschiedlichen Sätzen werden zu getrennten Rechnungspositionen. Die Währung ist immer die des Kunden.
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.
Rechnungen → Neue Rechnung. Kunde auswählen; die Absenderdaten werden aus den Plugin-Einstellungen übernommen. Positionen manuell eingeben oder über Aus Zeiteinträgen Stunden eines Zeitraums einziehen. Positionen verschiedener Herkunft lassen sich beliebig mischen – erfasste Stunden neben pauschalen Posten.
In der Zeitauswahl sind die Einträge nach Projekt gruppiert. Jede Projektgruppe hat im Kopf ein Auswahlkästchen, mit dem sich alle Einträge dieses Projekts auf einmal markieren oder abwählen lassen. Welche Einträge angeboten werden, hängt von der Freigabe-Einstellung des Projekts beim Kunden ab: Für Projekte mit Freigabepflicht erscheinen nur freigegebene Stunden; für Projekte mit Ohne Freigabe abrechnen erscheinen alle Stunden des Zeitraums.
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.
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).
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.
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.
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.
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.
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.
Archivieren. Ausgestellte, bezahlte und stornierte Rechnungen lassen sich archivieren: Sie verschwinden aus der Standardansicht der Liste und aus den Kennzahlen im Listenkopf (offen, überfällig, bezahlt), bleiben aber vollständig erhalten – Nummer, PDF, XML, Zahlungen und die Verknüpfung zur Stornorechnung. Der Filter Archiv schaltet zwischen Archivierte ausblenden (Standard), Nur archivierte und Alle anzeigen um. Archivieren geht einzeln auf der Rechnungsseite oder für mehrere Rechnungen über die Auswahlkästchen der Liste; beides braucht das Recht Rechnungen verwalten. Entwürfe werden nicht archiviert, sondern gelöscht. Wird eine archivierte Rechnung storniert, kommt sie automatisch aus dem Archiv zurück, weil der Vorgang wieder offen ist. Archivieren ist kein Löschen: Für die Aufbewahrung gelten die archivierten Rechnungen wie alle anderen.
Sammelexport. Rechnungen → Sammelexport liefert alle ausgestellten Rechnungen eines Zeitraums (Ausstellungsdatum) als ZIP-Datei: je Rechnung die PDF und, falls der Kunde ein E-Rechnungsformat hat, die XML-Datei (NUMMER-factur-x.xml bzw. NUMMER-xrechnung.xml), in Ordnern pro Jahr, dazu rechnungen.csv mit Nummer, Kunde, Datum, Fälligkeit, Netto, Brutto, Zustand, offenem Betrag, Archivdatum und Stornoverweis. Entwürfe sind nicht enthalten; Stornorechnungen und archivierte Rechnungen schon, denn der Export dient der Aufbewahrung. Optional nach Kunde und Zustand einschränken. Das Recht Rechnungen ansehen genügt. Der Export wird beim Aufruf erzeugt; ab der in den Plugin-Einstellungen hinterlegten Obergrenze (Standard 200 Rechnungen) verlangt er einen kürzeren Zeitraum. Vor einer Deinstallation ist das der Weg, die Belege zu sichern (siehe Abschnitt 3).
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 für dieses Projekt Freigabe vorgeschrieben ist. Ist beim Kunden für das Projekt Ohne Freigabe abrechnen gesetzt, erscheinen alle Stunden des Zeitraums; andernfalls werden nicht freigegebene Einträge 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.
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:
log/production.log, sofern verfügbar