Finanzmanager/docs/import-export.md

Import und Export

Unter Verwaltung → Import/Export führen zwei Knöpfe hinein. Beide fragen zuerst nach dem Dateiformat (QIF oder CSV) und öffnen danach den passenden Dialog – der Import weiß dann, welche Dateien er annimmt, der Export, was er schreiben soll.

	QIF	CSV
Import	Klassen, Kategorien, Konten, Buchungen, Buchungsvorlagen	Buchungen samt Splitzeilen
Export	Stammdaten und Buchungen	Buchungen samt Splitzeilen

Die Formate stehen an einer Stelle: Dateiformat::ALLE. Kommt ein drittes hinzu, ist das die einzige Liste, die es zu ergänzen gilt – Dialoge, Auswahlkarten und die Prüfung des Dateinamens hängen daran.

QIF-Import

Der Lexware FinanzManager exportiert erweitertes Quicken-QIF. Die .QDF-Datei ist verschlüsselt und damit keine Migrationsquelle – der QIF-Export ist der einzige Weg.

Stand: Klassen, Kategorien, Konten (Phase 1) sowie Buchungen samt Splitzeilen und Umbuchungen (Phase 2) werden übernommen. Wertpapierbestände folgen in Phase 6, Buchungsvorlagen in Phase 7.

Aufbau der Datei

!Option:MDY          Datumsformat für die gesamte Datei
!Type:Class          Klassen
!Type:Cat            Kategorien
!Option:AutoSwitch   Beginn der Kontenliste
!Account             ein Konto je Eintrag
!Clear:AutoSwitch    Ende der Kontenliste
!Account / !Type:…   ab hier abwechselnd Konto und dessen Buchungen

Ein Eintrag endet mit ^. Jede Zeile beginnt mit einem Feldbuchstaben, der Rest ist der Wert. Felder dürfen mehrfach auftreten (Splitzeilen, Adresszeilen), deshalb hält QifParser jeden Eintrag als Liste von Paaren und bietet feld(), felder() und hatFeld().

Die Datei ist zustandsbehaftet. Der Kontobezug einer Buchung steckt allein darin, welcher !Account-Abschnitt zuletzt kam – nach Sektionstypen gruppiert gelesen wäre er verloren. Der Parser liefert daher eine flache Liste in Dateireihenfolge, jeder Eintrag mit Sektionstyp und aktuellem Konto.

Jeder Kontoeintrag setzt zugleich das aktuelle Konto. In der Kontenliste folgen mehrere aufeinander, ohne dass Buchungen dazwischenstehen; das schadet nicht und deckt zugleich die zweite Schreibweise ab, bei der ein einzelner !Account den Kontowechsel bedeutet.

Felder der Stammdaten

Sektion	Feld	Bedeutung
!Type:Class	N / D	Name, Beschreibung
!Type:Cat	N	vollständiger Pfad mit :
	D	Beschreibung
	I / E	Einnahme bzw. Ausgabe (Marker ohne Wert)
	T	steuerrelevant (Marker ohne Wert)
	R	Kennziffer des Steuerformulars
!Account	N / T	Name, Kontotyp (siehe docs/stammdaten.md)
	D	Beschreibung; Kontonr. 12345 wird als Kontonummer übernommen
	L	Kreditlimit im US-Format

Kontengruppen fehlen im Export. Ein !Account-Eintrag führt nur die vier Felder oben – kein Feld nennt die Gruppe, und auch die QSD-Datei enthält weder Gruppennamen noch Zuordnung. Der Import kann sie deshalb nicht anlegen: nach dem Einlesen stehen alle Konten unter „Nicht gruppiert“. Die Gruppen werden einmalig unter Verwaltung → Kontengruppen angelegt; dort lassen sich die Konten einer Gruppe in einem Zug ankreuzen.

Fallstricke

1. Zeichensatz ISO-8859-1, Zeilenenden CRLF. QifParser::nachUtf8() prüft erst, ob schon UTF-8 vorliegt – eine zweite Konvertierung zerstörte die Umlaute.
2. Beträge im US-Format: -1,241.04. Das Komma ist Tausendertrenner.
3. Datum laut Kopfzeile, meist MDY mit zweistelligem Jahr: D3.18.26 ist der 18.03.2026. Jahreszahlen ab 70 gelten als 19xx.
4. Kategorie und Klasse in einer Zeile: L400 - Leben:B-Essen alleine/Privat.
5. Unterkategorien ohne genannte Elternkategorie. Der Import legt fehlende Zwischenstufen selbst an (Kategorie::findenOderAnlegenNachPfad()).
6. Konten stehen zweimal in der Datei – einmal in der Kontenliste, einmal als Kopf ihrer Buchungen. Der zweite Treffer ist keine Dublette.
7. Umbuchungen stehen nur einmal in der Datei – in dem Konto, in dem sie erfasst wurden. Die Gegenseite ist allein durch L[Zielkonto] benannt und wird beim Import erzeugt; ohne sie fehlte dem Gegenkonto der Betrag. Auch Splitzeilen können ein Umbuchungsziel tragen (S[Konto]). Eine Buchung, die auf ihr eigenes Konto verweist, ist die Eröffnungsbuchung und bekommt keine Gegenseite.
8. C ist der Abgleichstatus (X = abgeglichen), kein Kennzeichen für vorausberechnete Buchungen – Wertpapierbuchungen führen es nie. Geplante Buchungen sortiert man über das Datum aus.
9. Anfangssalden stehen nicht als eigenes Feld im Export. Sie ergeben sich aus den Buchungen vor dem Stichtag, Gegenbuchungen eingerechnet.

Arbeitsweise der Importeure

Beide sind idempotent: Was es schon gibt, wird gezählt und übersprungen, nie doppelt angelegt. Ein zweiter Lauf derselben Datei ändert nichts. Der echte Lauf liegt jeweils in einer Transaktion – ein Abbruch mitten in der Kategorieliste hinterließe sonst einen halben Baum.

QifStammdatenImport (Klassen, Kategorien, Konten): Der Trockenlauf schreibt gar nicht, sondern zählt mit einer Menge bereits bekannter Pfade mit; auch die Zwischenstufen, die der Import selbst anlegen würde, erscheinen in der Vorschau.

QifBuchungsImport arbeitet mit einem Stichtag:

• Buchungen vor dem Stichtag werden nicht gespeichert, sondern je Konto zum Anfangssaldo aufsummiert – einschließlich der Gegenbuchungen aus Umbuchungen. Die Salden stimmen dadurch exakt, ohne die ganze Historie mitzuschleppen.
• Buchungen im Zeitraum kommen einzeln in die Datenbank, mit Splitzeilen, Klasse, Abgleichstatus und Adresszeilen.
• Buchungen nach dem Enddatum (Vorgabe: heute) sind Vorausberechnungen des FinanzManagers und bleiben draußen.
• Wertpapiergeschäfte schlagen vorerst nur mit ihrem Geldfluss auf dem Verrechnungskonto zu Buche (L|[Konto] und $). Ein Betrag auf dem Depot ohne Gegenwert würde die Summe der Kontostände verfälschen; Bestände folgen in Phase 6.

Nur einzelne Konten übernehmen

Der Import lässt sich auf einzelne Konten begrenzen (Option konten, im Dialog eine Ankreuzliste, auf der Kommandozeile --konto=NAME). Drei Dinge sind dabei entschieden:

1. Maßgeblich ist jedes berührte Konto, nicht nur der !Account-Abschnitt. Eine Umbuchung steht nur einmal in der Datei, beim erfassenden Konto. Zählte allein dieser Abschnitt, fehlte dem gewählten Konto die Gegenseite. Deshalb kommt ein Eintrag mit, sobald sein Konto, ein Umbuchungsziel aus L oder S oder – beim Wertpapiergeschäft – das Verrechnungskonto in der Auswahl steht. Umgekehrt heißt das: Wer nur das Zielkonto wählt, bekommt die Buchung auch auf dem erfassenden Konto zu sehen; sie gehört dort hin und lässt sich nicht halbieren.
2. Anfangssalden werden weiterhin über die ganze Datei gerechnet, aber nur für die gewählten Konten geschrieben. Der Saldo eines Kontos steckt auch in Buchungen, die anderswo erfasst wurden – ohne den vollen Durchlauf wäre er falsch. Und ein Teilimport darf die Salden der übrigen Konten nicht überschreiben.
3. Die Fingerabdrücke entstehen vorab in einem eigenen Durchgang. Der laufende Zähler für gleiche Fingerabdrücke (siehe unten) hinge sonst an der Auswahl: Dieselbe Buchung bekäme im Teilimport einen anderen Hash als im Vollimport und käme ein zweites Mal in die Datenbank. So lassen sich die Konten nacheinander einlesen, ohne dass die Umbuchungen zwischen ihnen doppelt entstehen.

Die auswählbaren Konten liefert QifBuchungsImport::kontenDerDatei() – erst nach dem Lesen steht fest, was die Datei führt. Enthalten sind auch Konten, die selbst keine Buchung tragen und nur Umbuchungsziel sind; sonst ließe sich genau deren Gegenseite nicht übernehmen.

Die Dublettenerkennung nutzt einen Fingerabdruck aus Konto, Datum, Betrag, Nummer und Text. Weil es echte Doppelbuchungen am selben Tag gibt (zweimal dasselbe im selben Laden), zählt ein laufender Index gleiche Fingerabdrücke durch – stabil über Läufe hinweg, weil die Datei immer dieselbe Reihenfolge hat.

Bedienung

Im Dialog unter Verwaltung → Import/Export → Import → QIF: Datei hochladen, Trockenlauf, dann übernehmen. Hochgeladene Dateien bleiben im Importverzeichnis (data/import), damit derselbe Export erst geprüft und dann übernommen werden kann; das Housekeeping räumt sie später weg.

Nach dem Trockenlauf steht unter Konten die Ankreuzliste der Konten, die in der Datei vorkommen – vorher gibt es nichts zu wählen, weil die Datei noch nicht gelesen wurde. Von dort führen zwei Wege weiter: ein erneuter Trockenlauf mit der Auswahl oder das Übernehmen. Ohne Häkchen zählt die ganze Datei.

Auf der Kommandozeile:

docker compose exec -u www-data php php scripts/qif-import.php data/import/Export.QIF
docker compose exec -u www-data php php scripts/qif-import.php --uebernehmen data/import/Export.QIF

Ohne --uebernehmen läuft nur der Trockenlauf. --benutzer=NAME wählt den Mandanten, sonst gilt der erste aktive Benutzer.

--stichtag= und --bis= überschreiben die Vorgaben; ohne Angabe gilt der Stichtag aus den Einstellungen (Reiter Import/Export) und als Enddatum der heutige Tag. --nur-stammdaten lässt die Buchungen aus.

docker compose exec -u www-data php php scripts/qif-import.php --konten data/import/Export.QIF
docker compose exec -u www-data php php scripts/qif-import.php \
    --konto="DKB Girokonto" --konto="Tagesgeld" --uebernehmen data/import/Export.QIF

--konten nennt die Konten der Datei und beendet sich, ohne etwas anzufassen. --konto= grenzt den Import ein und ist mehrfach angebbar; ein Name, den die Datei nicht führt, bricht ab – sonst liefe der Import durch und legte nichts an.

Prüfung gegen den echten Export

Der Vollexport (8780 Buchungen, 2017–2026) ergibt mit Stichtag 01.01.2026:

Klassen            17 angelegt
Kategorien        105 angelegt
Konten             37 angelegt, 36 vorhanden (die Zweitnennung je Konto)
Buchungen         833 angelegt

vor dem Stichtag verrechnet:   7946 Buchungen auf 35 Konten
nach dem Enddatum verworfen:      1 vorausberechnete Buchung
darunter Wertpapiergeschäfte:    16 (nur Geldfluss)

Der Härtetest sind die Salden: Acht Konten, deren Werte aus der Kontenübersicht des FinanzManagers vorliegen, stimmen danach auf den Cent – von „Whg Besigheim“ (210.601,99 €) bis „Auslagen Eltern Wohnungskauf“ (−22.410,94 €).

CSV-Import

Das Gegenstück zum CSV-Export: Buchungen samt Splitzeilen, sonst nichts. Konten, Kontengruppen und Buchungsvorlagen bleiben dem QIF vorbehalten.

Die Kopfzeile bestimmt die Spalten, nicht ihre Reihenfolge. Eine Datei aus einem anderen Programm darf sie umsortieren oder eigene ergänzen; verglichen wird kleingeschrieben und ohne Umlaute (CsvTabelle::schluessel()), „Empfänger“ und „empfaenger“ meinen dasselbe. Unverzichtbar sind Datum, Konto und Betrag – fehlt eine davon, bricht der Lauf ab, statt eine halbe Datei einzulesen.

Spalte	Inhalt
Art	Buchung oder Splitzeile
Datum / Valuta	TT.MM.JJJJ oder JJJJ-MM-TT
Konto	Name eines vorhandenen Kontos
Nummer, Empfänger, Buchungstext	wie im Kontoblatt; bei Splitzeilen ist Buchungstext die Notiz
Kategorie	vollständiger Pfad mit :
Klasse	Name
Gegenkonto	statt einer Kategorie: macht die Zeile zur Umbuchung
Betrag	deutsch (-84,00) oder englisch (-84.00)
Abgeglichen	ja/nein

Entschieden ist dabei:

1. Splitzeilen folgen unmittelbar auf ihre Buchung und tragen in Art das Wort Splitzeile. Alles bis zur nächsten Buchungszeile gehört dazu. Eine Splitzeile ohne Buchung davor ist ein Fehler und wird gemeldet – stillschweigend fallen zu lassen wäre ein unbemerkter Verlust. Die Beträge der Zeilen müssen den Buchungsbetrag ergeben; das prüft Buchung::anlegen().
2. Kategorien und Klassen legt der Import bei Bedarf an, Konten nicht. Eine Kategorie ist ein Pfad und mehr nicht; ein Konto trägt Kontoart, Bankverbindung und Anfangssaldo, und nichts davon steht in der Zeile. Ein unbekanntes Konto ist deshalb ein Fehler.
3. Dieselbe Dublettenerkennung wie beim QIF: Fingerabdruck aus Konto, Datum, Betrag, Nummer und Text, mit laufendem Index für echte Doppelbuchungen am selben Tag. Ein zweiter Lauf derselben Datei ändert nichts.
4. Zahlen und Trenner werden erkannt, nicht vorausgesetzt. CsvTabelle sieht auf der Kopfzeile nach, ob Semikolon oder Komma trennt, und liest Beträge in beiden Schreibweisen: Maßgeblich ist, welches Zeichen zuletzt steht – es trennt die Nachkommastellen, das andere ist Tausendertrenner. Gelesen wird über einen Speicherstrom und fgetcsv(), damit ein maskiertes Feld auch einen Zeilenumbruch enthalten darf.

Export

Verwaltung → Import/Export → Export, dann das Format, dann der Filter: Zeitraum, Konto, Kategorie und Klasse. Ohne Häkchen zählt jeweils alles. Über dem Formular steht, wie viele Buchungen der Filter trifft – sonst lädt man eine leere Datei herunter und merkt es erst in der Tabellenkalkulation.

Zwei Eigenheiten des Datenmodells schlagen auf den Filter durch:

• Der Kontofilter greift auf beide Seiten. Eine Umbuchung ist EINE Buchung mit gegenkonto_id und steht nur beim erfassenden Konto. Zählte allein dieses, fehlte dem Auszug des Gegenkontos seine einzige Bewegung.
• Kategorie und Klasse zählen auch in den Splitzeilen. Sonst fiele jede Splitbuchung aus dem Filter, obwohl sie die gesuchte Kategorie führt.
• Unter den Kategorien stehen die aktiven Umbuchungskonten (#124, gegenkonten[]). Ein gewähltes Konto nimmt jede Buchung oder Splitzeile mit diesem Gegenkonto mit; Kategorien und Umbuchungskonten verbinden sich als „oder“, wie in einer Auswahlliste.

Die Kontenliste der Datei enthält zusätzlich jedes Konto, das nur Umbuchungsziel ist. Ohne seinen Eintrag bezöge sich die Datei auf ein Konto, das der Import nicht kennt, und die Umbuchung ginge verloren.

Die Datei wird nicht vorgehalten. Sie entsteht im Speicher und geht mit Content-Disposition: attachment unmittelbar an den Browser; ein Exportverzeichnis gibt es bewusst nicht. Ein Auszug der eigenen Finanzen, der irgendwo im Dateisystem liegen bleibt, ist eine Altlast, die niemand aufräumt.

Das Filterformular sendet als POST. Bei vielen angehakten Kategorien wächst eine GET-Adresse über das, was nginx annimmt – die Antwort wäre dann „414 Request-URI Too Large“ statt der Datei. Die GET-Route bleibt für kurze Adressen bestehen, die man sich merken mag.

QIF-Export

Derselbe Dialekt, den der Import liest: erst !Type:Class, dann !Type:Cat, dann die Kontenliste zwischen !Option:AutoSwitch und !Clear:AutoSwitch, danach je Konto ein !Account-Kopf und dessen Buchungen. Datumsformat ist DMY mit vierstelligem Jahr (!Option:DMY), Beträge stehen im US-Format.

Klassen und Kategorien kommen vollständig mit, auch wenn der Filter enger ist: Ohne sie ließe sich die Datei auf einer leeren Installation nicht einspielen. Die Konten dagegen nur, soweit der Filter sie zulässt – sonst wäre es kein Auszug mehr.

Wertpapiergeschäfte (!Type:Invst) stehen nicht darin; sie hängen am Depot und werden über die Wertpapierverwaltung gepflegt.

CSV-Export

Deutsches Tabellenkalkulations-CSV: Semikolon als Trenner, Komma als Dezimalzeichen, kein Tausenderpunkt (der macht aus der Zahl einen Text), CRLF am Zeilenende und ein BOM vorweg – sonst zeigen Excel und LibreOffice beim Doppelklick „Ãœbrige“ statt „Übrige“. Die Spalten sind die des CSV-Imports; dieselbe Datei liest er wieder ein.

CsvTabelle hält das Format an einer Stelle; BerichtExport (Auswertungen) nutzt dieselben Zeilen- und Zahlenregeln.

Housekeeping

Exportdateien entstehen im Speicher und hinterlassen nichts. Die hochgeladenen Importdateien bleiben dagegen absichtlich liegen – erst Trockenlauf, dann Übernahme, ohne zweiten Upload. Genau dadurch sammeln sich im Importverzeichnis mit der Zeit Kontoauszüge an, die niemand mehr braucht.

Housekeeping löscht deshalb, was älter ist als die eingestellte Frist (Einstellungen → Import/Export, Vorgabe 14 Tage; 0 schaltet es ab). Überwacht werden das Importverzeichnis und data/tmp, der Platz für Arbeitsdateien; gelöscht werden nur gewöhnliche Dateien unmittelbar darin – ein Symlink zeigte womöglich aus dem überwachten Bereich heraus.

Angestoßen wird der Lauf beiläufig beim Öffnen von Import und Export, höchstens einmal am Tag (housekeeping_letzter_lauf). Ein Fehler dabei reißt die Seite nicht mit: Wer den Import öffnet, will importieren, nicht eine Fehlermeldung übers Aufräumen lesen. Für Installationen, die wochenlang nicht geöffnet werden, gibt es denselben Lauf als Skript:

docker compose exec -u www-data php php scripts/housekeeping.php --probe
docker compose exec -u www-data php php scripts/housekeeping.php --still

--probe zählt nur auf, was wegfiele.