LedgerLou Bank

Das Bank-Modul verbindet rohe Kontobewegungen mit dem Hauptbuch. Kontoauszüge werden importiert, mit Vorschlägen abgeglichen und über REST oder Agenten systematisch abgestimmt.

API Reference

CSV / CAMT ImportMulti-Format-Parser für alle gängigen Kontoauszugsformate

Matching-VorschlägeVorschläge auf Basis von Betrag, Datum und Verwendungszweck

Manuelle AbstimmungTransaktionen einzeln zuordnen oder neue Buchung erzeugen

Batch- und Sammelabgleich1:1-, 1:n- und n

mit expliziten Ausgleichszeilen für Restdifferenzen

GoBD-konformUnmatch als Gegenbuchung, kein stilles Überschreiben

API & MCPREST vollständig, MCP für den Kernflow verfügbar und weiter im Ausbau

Workflow

Kontoauszug importierenCSV, CAMT.053 oder XML per Dashboard-Upload oder

POST /v1/bank-accounts/
/upload

. Duplikate werden anhand eines Content-Hashs automatisch übersprungen.

Offene Transaktionen sichtenAlle unabgestimmten Transaktionen sind per API oder Agent sofort sichtbar. Status unmatched zeigt, wo noch Handlungsbedarf besteht.

Matching-Vorschläge übernehmenGET /v1/bank-transactions/suggestions liefert priorisierte Vorschläge auf Basis von Betrag, Datum und Verwendungszweck. Bestätigung erfolgt per REST oder via Agent mit Schreibfreigabe.

Restfälle manuell zuordnenTransaktionen ohne Vorschlag werden per REST einer bestehenden Buchung zugeordnet, über Allocations plus Ausgleichszeilen gegen offene Posten abgestimmt oder mit ergänzender Buchung verarbeitet.

Abstimmungsstand kontrollieren

GET /v1/bank-accounts/
/reconciliation

zeigt offene vs. abgestimmte Transaktionen und den aktuellen Buchungsstand des Kontos.

Zugangswege

Dashboard (UI)Im MVP für Bankkonto-Setup, Kontoauszug-Import und Abstimmungsarbeit.

REST APIKontoauszüge automatisiert importieren und die vollständige Abstimmung per Skript oder Backend-Workflow steuern.

MCPMCP Agents können bereits den Kernflow lesen, importieren und abstimmen. Erweiterte Parität zur REST-API wird aktuell ausgebaut.

Fremdwährungs-Abgleich

LedgerLou führt das Hauptbuch weiterhin in EUR. Für offene Posten in Fremdwährung speichert das System deshalb immer zwei Ebenen:

Belegwährung: z. B. 41.63 USD
EUR-Buchungswert bei Erstverbuchung: z. B. 38.27 EUR

Beim Bankabgleich gilt:

Matching-Vorschläge für Fremdwährungsrechnungen vergleichen den Bankumsatz mit dem EUR-Buchungswert, nicht mit der rohen Fremdwährungszahl.
Der offene Posten wird bei der Abstimmung in Belegwährung reduziert oder geschlossen.
Die Differenz zwischen tatsächlichem Bankabfluss/-zufluss und ausgebuchtem EUR-Buchungswert wird als realisierter FX-Gewinn/-Verlust gebucht.
Über die REST-API gibt es dafür einen expliziten FX-Ausgleich mit Belegbetrag, EUR-Ausbuchung und FX-Effekt.

Sammelabstimmung und Restdifferenzen

Zusätzlich zur bestehenden 1:1-Zuordnung unterstützt LedgerLou jetzt einen rohen Match-Group-Flow für offene Posten: eine oder mehrere Banktransaktionen gegen einen oder mehrere OPOs, optional ergänzt um explizite Ausgleichszeilen.

Endpoint: POST /v1/bank-match-groups
Ziel: offene Posten in einem Settlement-Intent zusammenfassen, inklusive 1:1-Fällen im Dashboard
Alle ausgewählten Banktransaktionen müssen vom selben Bankkonto stammen und dieselbe Richtung haben.
Die Gruppe darf über drei Bausteine ausgeglichen werden: Allocations auf OPOs, automatische FX-Gewinn/-Verlust-Buchung und manuelle Ausgleichszeilen.
Das Ergebnis ist eine einzige Settlement-Buchung im Hauptbuch; alle zugehörigen Banktransaktionen werden auf denselben intent_id gesetzt.
POST /v1/bank-match-groups/:id/unmatch storniert diese Sammelbuchung vollständig und öffnet alle verknüpften Banktransaktionen erneut.

Für Fremdwährungs-Offenposten wird pro Allocation weiterhin gegen den EUR-Buchungswert abgestimmt. Die Differenz zwischen Bankbetrag und EUR-Ausbuchung läuft automatisch über 4840/6880. Andere Restdifferenzen wie Bankgebühren, Skonto, Write-offs oder manuelle Gegenbuchungen werden als explizite Ausgleichszeilen mit frei gewähltem Konto und Soll/Haben-Seite erfasst.

Duplikat-Erkennung

Beim Import eines Kontoauszugs prüft LedgerLou jede Transaktion in drei Stufen, bevor sie in die Datenbank geschrieben wird.

Stufe 1 — Bank-Referenz (höchste Priorität)

Wenn die Transaktion eine bank_reference enthält (z. B. eine Auftrags- oder Transaktions-ID der Bank), wird zunächst nach einer Zeile mit identischer normalisierter Bank-Referenz und gleichem Betrag gesucht. Treffer → Duplikat, Zeile wird übersprungen.

Stufe 2 — Content-Fingerprint

Kandidaten mit gleichem Betrag und passendem Datum (Buchungs- oder Wertstellungsdatum ±0) werden geprüft:

IBAN des Gegenkontos + Verwendungszweck stimmen überein → Duplikat
Name des Gegenkontos + Verwendungszweck stimmen überein → Duplikat

Alle Felder werden vor dem Vergleich normalisiert: Unicode-Komposition aufgelöst, Umlaute vereinfacht (ü → u), Sonderzeichen zu Leerzeichen, Kleinschreibung. Dadurch werden z. B. "Müller & Söhne" und "Muller und Sohne" als identisch erkannt.

Stufe 3 — Content-Hash (Datenbank-Constraint)

Parallel dazu berechnet der Parser einen SHA-256-Hash aus den Feldern:

tenant_id | bank_account_id | tx_date | amount | counterparty_name | reference

Der Hash ist per UNIQUE(tenant_id, content_hash) abgesichert. Fehlt ein Treffer in Stufe 1 und 2, verhindert dieser Constraint eine doppelte Einfügung auf Datenbankebene (ON CONFLICT DO NOTHING).

API-Response beim Upload

POST /v1/bank-accounts/:id/upload gibt immer HTTP 201 zurück — unabhängig davon, ob Duplikate dabei waren. Das Response-Body enthält eine genaue Aufschlüsselung:

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_rows": 50,
  "imported": 47,
  "skipped_duplicates": 3,
  "errors": []
}

Feld	Bedeutung
`batch_id`	UUID dieses Import-Vorgangs
`total_rows`	Anzahl verarbeiteter Zeilen
`imported`	Tatsächlich neu gespeicherte Transaktionen
`skipped_duplicates`	Erkannte und still übersprungene Duplikate
`errors`	Parse- oder Validierungsfehler pro Zeile

Duplikate werden nie als Fehler behandelt — sie erhöhen nur skipped_duplicates. Ein erneuter Upload desselben Kontoauszugs ist daher jederzeit sicher.

Scopes

bank:readbank:write