Saldenliste an den Jahresabschluss übergeben – mit Ihrem KI-Agenten

Was bei der Übergabe geschieht

publish_trial_balance fasst das Journal des Geschäftsjahres je Konto zusammen: Eröffnung, Soll- und Haben-Verkehrszahlen, Schlusssaldo. Konten, deren Bilanz- oder GuV-Posten der Kontenrahmen kennt, sind vorab zugeordnet; die übrigen ordnet die automatische Zuordnung des Jahresabschluss-Moduls zu. Was Sie dort früher von Hand zugeordnet haben, gilt weiter, damit eine neue Übergabe die Bilanz nicht still verschiebt.

Wird das Vorjahr in derselben Buchhaltung geführt und hat das Jahr keine eigene Eröffnung, trägt die Saldenliste den aus dem Vorjahr berechneten Vortrag in den Eröffnungsspalten – gebucht wird dafür nichts. Im Jahr der Übernahme, wenn das Vorjahr nur als freigegebene Saldenliste vorliegt, bucht die Übergabe die fehlenden Eröffnungswerte und meldet das in opening_entries_created.

Voraussetzungen vor dem Aufruf

• Ein Schlüssel mit dem Recht write.
• Die Gesellschaft bilanziert. Bei einer Einnahmen-Überschuss-Rechnung gibt es keinen Jahresabschluss; die Übergabe endet mit 409 und dem Code euer_betrieb.
• Ein Kontenrahmen SKR03 oder SKR04 ist eingestellt (sonst 409) und es gibt Buchungen im Jahr (sonst 422).
• Alle Buchungen des Jahres sind festgeschrieben; Eröffnungsbuchungen zählen nicht mit. Sonst antwortet die Schnittstelle mit 409 und nennt die Zahl der offenen Buchungen. Festschreiben kann der Agent mit finalize_bookkeeping_period – nur mit dem Recht finalize und nach Ihrer Bestätigung. In der App können Sie die Übergabe auch mit offenen Buchungen bewusst bestätigen; über die Schnittstelle gibt es diese Ausnahme nicht.
• Die Saldenliste geht auf. Sonst kommt 422, und übergeben wird nichts.
• Die Zahlen des Jahresabschlusses sind in der App nicht festgeschrieben. Sonst kommt 409; erst nach Aufheben der Festschreibung unter „Bilanz & GuV“ lässt sich neu übergeben.

Der Ablauf mit den echten Werkzeugen

• list_fiscal_years: die Kennung des Geschäftsjahres.
• list_bookkeeping_periods mit fiscal_year_id: welche Monate open, partially_finalized oder finalized sind.
• get_saldenliste mit fiscal_year_id: steht totals.balanced auf true, und sind die Salden plausibel?
• finalize_bookkeeping_period mit until (letzter Tag des Geschäftsjahres) und confirm=true – erst nach Ihrem ausdrücklichen Ja.
• publish_trial_balance mit fiscal_year_id und einer neuen UUID als idempotency_key.
• Antwort auswerten: requires_manual_mapping, warnings, eb_warning.
• get_annual_report_status: saldenliste_uebergeben steht jetzt auf true.

Aufruf und Antwort

Derselbe Vorgang als REST-Aufruf, darunter die Felder der Antwort:

curl -X POST \
  -H "Authorization: Bearer $JAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fiscal_year_id":"<uuid des Geschäftsjahres>","idempotency_key":"<neue uuid>"}' \
  "https://api.jahresabschluss.io/functions/v1/bookkeeping-api/v1/saldenliste/publish"

# Felder der Antwort (je nach Fall)
trial_balance_id         Kennung der übergebenen Saldenliste
mapped_count             Konten mit Bilanz- oder GuV-Posten
catalog_mapped_count     davon aus dem Kontenrahmen vorbelegt
unmapped_count           Konten noch ohne Posten
requires_manual_mapping  true: Zuordnung in der App ergänzen
balanced                 true: Soll gleich Haben
idempotent_replay        true: diese Saldenliste lag bereits so vor
warnings / warning       Hinweise im Klartext
opening_entries_created  gebuchte Eröffnungswerte im Übernahmejahr
eb_warning, eb_deviations  Eröffnung weicht vom Vorjahresschluss ab

Die Antwort richtig lesen

• unmapped_count größer null oder requires_manual_mapping true: Der Agent sagt Ihnen, dass auf der Zuordnungsseite des Jahresabschlusses noch Konten offen sind. Er ordnet sie nicht selbst über einen Umweg zu.
• warnings: Der Agent gibt die Hinweise wörtlich weiter, etwa zu Eröffnungswerten, die von festgestellten Vorjahreszahlen abweichen.
• eb_warning und eb_deviations: je Konto der Eröffnungswert, der erwartete Vorjahresschluss und die Differenz. Eine gute nächste Frage ist get_opening_balances für dasselbe Jahr.
• opening_entries_created: Im Übernahmejahr wurden Eröffnungsbuchungen angelegt; der Agent nennt ihre Zahl.
• Nach erfolgreicher Übergabe zeigt get_annual_report_status saldenliste_uebergeben true. Der Abschluss selbst entsteht danach in der App.

Wiederholen ohne Doppelung

Bricht die Verbindung ab, wiederholt der Agent mit derselben UUID und denselben Daten. Die Schnittstelle speichert zu jedem Schlüssel die Antwort und gibt sie bei der Wiederholung zurück – eine zweite Übergabe entsteht nicht. Läuft die erste noch, kommt 409 mit dem Hinweis, den Stand in der App zu prüfen.

Gespeichert wird auch eine Ablehnung. Hat der Agent zum Beispiel eine 409 wegen offener Buchungen erhalten und danach festgeschrieben, braucht der nächste Versuch eine neue UUID; mit der alten käme dieselbe Ablehnung zurück. Dieselbe UUID für ein anderes Geschäftsjahr lehnt die Schnittstelle ab.

Rolle von get_saldenliste mit as_of

get_saldenliste liest nur und ist die Kontrolle vor der Übergabe. Mit as_of rechnet sie zu einem Stichtag im Geschäftsjahr: Verkehrszahlen bis einschließlich as_of, die Eröffnung bleibt die des ganzen Jahres. Liegt as_of außerhalb des Geschäftsjahres, kommt 400. So lassen sich Zwischenstände prüfen, etwa zum Quartalsende oder vor einem Gespräch mit Ihrer Kanzlei.

Die Übergabe nimmt dagegen immer das ganze Geschäftsjahr. Einen Zwischenstand übergibt publish_trial_balance nicht. Öffnen Sie den Jahresabschluss in der App, gleicht die App eine veraltete Saldenliste aus der Buchhaltung übrigens selbst ab – sofern diese Buchhaltung die führende Quelle des Jahres ist und die Abschlusszahlen nicht festgeschrieben sind.

Was in der App bleibt

• Die Zuordnung offener Konten zu Bilanz- und GuV-Posten.
• Die Übergabe trotz noch nicht festgeschriebener Buchungen, mit ausdrücklicher Bestätigung.
• Das Hochladen einer Saldenliste aus einer anderen Buchhaltung.
• Bilanz, GuV, Anhang und Lagebericht erstellen und ausstellen sowie die Festschreibung der Abschlusszahlen.
• Konzernabschlüsse: Sie sind in der Software ein eigenes Modul; publish_trial_balance bedient den Einzelabschluss.

Häufige Fragen

Muss vor der Übergabe festgeschrieben sein?

Bei der Übergabe über die Schnittstelle ja. publish_trial_balance lehnt mit 409 ab, solange Buchungen des Jahres nicht festgeschrieben sind, und nennt ihre Zahl. Eröffnungsbuchungen zählen nicht mit.

Was bedeutet unmapped_count?

Die Zahl der Konten, die noch keinem Bilanz- oder GuV-Posten zugeordnet sind. Ist sie größer als null, ergänzen Sie die Zuordnung in der App.

Was passiert, wenn der Agent die Übergabe wiederholt?

Mit derselben UUID kommt die gespeicherte Antwort zurück, eine zweite Übergabe entsteht nicht. Nach einer Ablehnung, deren Ursache behoben ist, braucht der neue Versuch eine neue UUID.

Kann ich eine Saldenliste aus einer anderen Software übergeben?

Nicht mit publish_trial_balance; das Werkzeug nimmt die Saldenliste aus dieser Buchhaltung. Eine fremde Saldenliste laden Sie in der App hoch.

Welche Rechte braucht der Schlüssel?

write für publish_trial_balance, finalize für finalize_bookkeeping_period. get_saldenliste und get_annual_report_status kommen mit read aus.

Funktioniert das bei einer Einnahmen-Überschuss-Rechnung?

Nein. Wer per EÜR ermittelt, stellt keinen Jahresabschluss auf. Die Übergabe endet mit 409 euer_betrieb; die Zahlen gehen in die Anlage EÜR.