Kernkonzepte

LedgerLou ordnet das Hauptbuch in drei Ebenen:

Journal -> Intents -> Buchungszeilen

Das Journal ist die Gesamtsicht. Darin liegen viele Intents. Jeder Intent gruppiert eine oder mehrere Buchungszeilen, die gemeinsam einen Buchungsvorgang bilden.

Konzept	Was es ist	Persistenz
Journal	Append-only Gesamtschau aller Intents eines Mandanten	ledger_events (GoBD-konform, hash-gekettet)
Intent	Fachliche Klammer für genau einen Buchungsvorgang innerhalb des Journals	Kein eigener Datensatz — als intent_id in ledger_events, documents, bank_transactions u. a.
Buchungszeile	Einzelne Soll/Haben-Zeile innerhalb eines Intents	ledger_events (1+ Zeilen pro Intent)

Praktisch bedeutet das:

• Das Journal listet alle Intents chronologisch.
• Ein Intent gruppiert die Zeilen, die gemeinsam zu einem Vorgang gehören.
• Eine Buchung kann aus einer oder mehreren Buchungszeilen bestehen, je nach Split und Steuerlogik.

Intent-Lebenszyklus

Ein Intent ist unveränderlich. Sobald seine Zeilen im Journal stehen, werden sie nie mehr modifiziert oder gelöscht — auch nicht, wenn nachgelagerte Module wie der Bank-Abgleich ihre Zuordnung später wieder auflösen. Korrekturen entstehen ausschließlich durch neue Intents, die über reverses_intent_id auf den Ursprung verweisen.

Drei typische Szenarien zeigen, wie sich das im Zusammenspiel mit dem Bank-Abgleich konkret verhält:

Reversal-Logik

Ein Storno ist in LedgerLou immer ein neuer Buchungs-Intent. Die Originalzeilen bleiben unverändert stehen, die Stornozeilen spiegeln Soll und Haben, übernehmen Audit-relevante Felder wie FX-Block, external_reference, custom_metadata und tax_code, und tragen reverses_intent_id auf den stornierten Intent.

Für das Buchungsdatum gibt es zwei Modi:

Modus	REST posting_mode	MCP posting_mode	Wirkung
Aktuelle Periode	current_period oder weglassen	current_period oder weglassen	Storno wird mit heutigem Datum in der aktuellen offenen Periode gebucht. Das ist der Default für API und MCP, damit bestehende Integrationen stabil bleiben.
Ursprungsperiode	original_period	original_period	Storno wird auf das Buchungsdatum der Originalbuchung gesetzt. Das ist für Jahresabschluss- oder Periodenkorrekturen sinnvoll, solange die Ursprungsperiode noch offen ist.

original_period ist ein expliziter Korrekturmodus. LedgerLou prüft vor dem Schreiben, ob die Zielperiode offen ist. Ist sie soft-locked oder hard-locked, wird die Stornierung mit PERIOD_LOCKED abgelehnt. Dann muss die Periode bewusst wieder geöffnet werden oder die Korrektur bleibt in der aktuellen Periode.

Bei bereits abgeglichenen Intents kehrt LedgerLou zuerst abhängige Settlement-Intents um und löst die Bankverknüpfung. Gruppierte Bankabgleiche bleiben geschützt: Wenn ein Settlement noch andere aktive Intents ausgleicht, muss zuerst die Gruppenzuordnung aufgehoben werden.

curl -X POST https://api.ledgerlou.de/v1/journal/reverse \
  -H "Authorization: Bearer $LEDGERLOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "Falsche Kontierung",
    "posting_mode": "original_period"
  }'

Für MCP gilt dasselbe.

{
  "intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Falsche Kontierung",
  "posting_mode": "original_period"
}

Metadaten & Externe Referenzen

Jede Buchung kann optional zwei Intent-Level-Felder mitgeben, die den Vorgang mit externen Systemen verknüpfen oder zusätzlichen Kontext liefern:

Eigenschaft	external_reference	custom_metadata
Typ	string (max. 500 Zeichen)	Flaches JSON-Objekt (string | number | boolean | null als Werte)
Pflicht	Nein	Nein
Unveränderlich	Ja (GoBD)	Ja (GoBD)
Im Audit-Hash	Ja	Ja (deterministische Sortierung)
Filterbar	GET /v1/journal?externalReference=...	—
Storno-Verhalten	Wird identisch vom Original übernommen	Wird identisch vom Original übernommen

Typische Anwendungsfälle:

• Rechnungsnummer als Referenz — external_reference: "RE-2025-0042" verknüpft die Buchung mit der Rechnung im ERP. Per ?externalReference=RE-2025-0042 ist der zugehörige Journal-Eintrag sofort auffindbar.
• Kostenstelle und Projekt — custom_metadata: { "cost_center": "CC-100", "project": "alpha" } ordnet die Buchung organisatorisch zu, ohne das Kontenrahmenmodell anpassen zu müssen.
• Herkunfts-Tags für Automatisierungen — custom_metadata: { "source_system": "shopify", "order_id": "ORD-9981" } gibt MCP-Agents und ETL-Pipelines einen strukturierten Rückkanal.

Fremdwährungsbuchungen

LedgerLou führt die Bücher in EUR. Buchungen in Fremdwährung (z. B. USD, GBP, CHF) werden nativ im EUR-Betrag gebucht und tragen zusätzlich einen FX-Block mit den Originaldaten:

Feld	Bedeutung
currency	ISO 4217 Währungscode (z. B. USD)
foreign_amount	Brutto-Betrag in Fremdwährung
rate	Umrechnungskurs Fremdwährung → EUR (ECB-Konvention)
rate_date	Stichtag des Kurses
rate_source	Quelle (z. B. ECB, manual, bank)

Wichtige Regeln:

• Der Aufrufer gibt den Kurs explizit an — LedgerLou ruft keine externen Kursquellen ab.
• Der EUR-Betrag in lines muss zum FX-Block passen: foreign_amount × rate ≈ Summe der Soll-Beträge (Toleranz: max. 1 Cent oder 0,01 %).
• Bei Split-Buchungen wird der Fremdwährungsbetrag proportional auf die Zeilen verteilt (Largest-Remainder-Verfahren, 4 Dezimalstellen).
• Stornobuchungen übernehmen den FX-Block identisch aus dem Original — es wird kein neuer Kurs berechnet.
• EUR-Buchungen setzen keinen FX-Block (fx: null oder Feld weglassen).
• Eröffnungsbilanzwerte (POST /v1/bookings/opening-balances) unterstützen kein FX.

Workflow

Zugangswege

Scopes