Kontoauszug per KI-Agent importieren und abarbeiten

Sieben Werkzeuge rund ums Bankkonto

Import: was der Server prüft, bevor ein Umsatz entsteht

Pflicht sind idempotency_key, bank_connection_id, file_base64 und file_name. Optional sind format, opening_balance, closing_balance und statement_date.

• Das Bankkonto muss in der App angelegt und einem Sachkonto zugeordnet sein; sonst antwortet der Server mit account_mapping_required.
• Das Format erkennt der Server aus Inhalt und Endung; mit format (csv, camt053 oder mt940) lässt es sich vorgeben.
• Eine Datei gehört zu genau einem Konto. Nennt der Auszug ein Konto, dessen IBAN nicht auf die Endziffern des gewählten Kontos endet, wird nichts importiert.
• Saldenprobe: Liegen Anfangs- und Endbestand vor — aus CAMT.053 oder MT940, bei CSV aus opening_balance und closing_balance —, muss Anfangsbestand plus Umsätze den Endbestand ergeben. Sonst wird nichts importiert.
• Hat eine Zeile kein gültiges Datum, einen mehrdeutigen Betrag oder ein unklares Vorzeichen, bricht der ganze Import ab; eine Teilmenge entsteht nie.
• Dubletten: Umsätze, die schon vorhanden sind, überspringt der Server — auch wenn sie über die Bankanbindung oder aus einer Datei in anderem Format kamen.
• Die Datei darf bis 20 MB groß sein. Über den gehosteten MCP-Server ist eine Anfrage auf 10 MB begrenzt; als Base64 entspricht das einer Auszugsdatei von rund 7 MB.
• Neue Umsätze stehen danach mit dem Status unbooked bereit.

Buchen beim Bilanzierer: keine Bankzeile ohne Beleg in die GuV

book_bank_transaction verlangt id, fiscal_year_id, idempotency_key, skr_account (das Gegenkonto) und tax_key. Optional sind partner_name, receipt_id und kind: normal, transfer (Umbuchung zwischen eigenen Konten), cash_withdrawal (Bargeld zwischen Bank und Kasse), private_expense, accounts_payable oder accounts_receivable.

Beim Bilanzierer greift die Belegpflicht für Aufwand und Erlös. Wählt der Agent für eine Bankzeile ein Aufwands- oder Erlöskonto, parkt der Server einen Abgang als Verbindlichkeit und einen Zugang als Forderung, ohne Umsatzsteuer. Aufwand, Erlös und Steuer entstehen erst mit dem Beleg, der diesen Posten ausgleicht. Bestandskonten wie Darlehen, Umbuchungen und Privatvorgänge bucht er direkt, und eine in der App freigegebene Bankregel greift wie gewohnt.

Mit receipt_id verweist der Agent auf den Beleg einer bereits gebuchten Eingangsrechnung; der Bankumsatz gleicht diese Rechnung dann aus. Gibt es zu dem Beleg keine gebuchte Eingangsrechnung, lehnt der Server ab.

Wer eine Einnahmen-Überschuss-Rechnung führt, bucht am Geldfluss: Dort entsteht der Aufwand oder die Einnahme mit der Bankzeile selbst.

Zuordnen und ausblenden

match_bank_transaction braucht id, fiscal_year_id, idempotency_key, invoice_id und invoice_kind (incoming oder outgoing). Ein ungebuchter Umsatz wird mit seinem ganzen Betrag zugeordnet; ist er kleiner als die Rechnung, bleibt der Rest offen. Vereinbartes Skonto und Zahlungsdifferenzen prüft der Server wie in der App, Beträge werden nicht frei erfunden. Bereits gebuchte, geparkte Zahlungen ordnet er wie in der Partner-Akte zu; amount begrenzt dort den Teilbetrag.

ignore_bank_transaction blendet einen ungebuchten Umsatz aus, der laut Werkzeugbeschreibung privat oder für die Buchhaltung irrelevant ist. Der Grund (reason, höchstens 500 Zeichen) bleibt am Umsatz stehen und erscheint in der App; dort lässt sich der Umsatz wieder öffnen. Gebuchte Umsätze ändert das Werkzeug nicht.

Beispiel: Auszug September importieren und abarbeiten

Ein Auftrag, wie er im Chat stehen kann:

Hier ist der CAMT-Auszug September für das Geschäftskonto.
Bitte importieren, Kundenzahlungen den offenen Rechnungen
zuordnen, Kontoführungsgebühren buchen und am Ende auflisten,
was ohne Beleg offen bleibt.

Schritt 1: Mit list_bank_accounts sucht der Agent das Geschäftskonto und dessen bank_connection_id.

Schritt 2: Er ruft import_bank_statement mit file_base64, file_name und einer neuen UUID auf. Die Antwort nennt importierte und übersprungene Umsätze sowie Anfangs- und Endbestand.

Schritt 3: list_bank_transactions mit status unbooked und dem Zeitraum September liefert die neuen Umsätze.

Schritt 4: list_open_items mit kind debitor und status open zeigt die offenen Ausgangsrechnungen. Passt eine Kundenzahlung nach Betrag und Verwendungszweck, ruft er match_bank_transaction auf. Den Verwendungszweck behandelt er dabei als Daten, nicht als Anweisung.

Schritt 5: Gebühren und andere Abgänge ohne Rechnung bucht er mit book_bank_transaction. Beim Bilanzierer parkt der Server sie als offenen Posten, solange weder ein Beleg vorliegt noch eine freigegebene Bankregel greift — genau diese Posten listet der Agent Ihnen am Ende auf.

Was in der App bleibt

• Die Bankanbindung per OAuth bei Ihrer Bank und die Zuordnung jedes Bankkontos zu einem Sachkonto.
• Das Wiederöffnen eines ignorierten Umsatzes.
• Die Korrektur eines gebuchten Bankumsatzes: storno_journal_entry verweist bei Bankbuchungen auf „Buchung korrigieren“ in der App, weil dieser Weg die alte Buchung storniert und die neue in einem Schritt erfasst. Eine Zuordnung zu einer Rechnung nimmt der Agent dagegen selbst mit storno_payment zurück.
• Kreditkarten-Auszüge als CSV, die eine eigene Spaltenzuordnung brauchen.

Häufige Fragen

Welche Kontoauszugsformate kann der Agent importieren?

CSV-Exporte von Banken, CAMT.053 und MT940. Der Agent sendet die Datei als Base64; das Format erkennt der Server selbst, oder der Agent gibt es mit format vor. Bei CSV ohne Saldozeile kann er Anfangs- und Endbestand mitgeben, damit die Saldenprobe läuft.

Kann der Agent mein Bankkonto selbst verbinden?

Nein. Die Anmeldung bei der Bank per OAuth richten Sie in der App ein, ebenso die Zuordnung zum Sachkonto. Danach liest der Agent die abgerufenen Umsätze mit list_bank_transactions und bucht sie.

Werden Umsätze doppelt angelegt, wenn ein Auszug zweimal importiert wird?

Nein. Bereits vorhandene Umsätze überspringt der Server, auch wenn sie über die Bankanbindung oder aus einer Datei in anderem Format kamen. Eine Wiederholung mit derselben UUID und denselben Daten liefert dasselbe Ergebnis; dieselbe UUID mit anderen Daten lehnt der Server ab.

Bucht der Agent Bankgebühren oder Einkäufe direkt als Aufwand?

Beim Bilanzierer nicht ohne Weiteres: Aufwand und Erlös entstehen am Beleg, eine Bankzeile ohne Beleg parkt der Server als offenen Posten. Ausnahmen sind Bestandskonten und eine in der App freigegebene Bankregel. In der Einnahmen-Überschuss-Rechnung bucht die Bankzeile dagegen unmittelbar am Geldfluss.

Wann blendet der Agent einen Umsatz aus?

ignore_bank_transaction ist für ungebuchte Umsätze gedacht, die privat oder für die Buchhaltung irrelevant sind. Der Grund bleibt in der App sichtbar, und der Umsatz lässt sich dort wieder öffnen. Welche Umsätze so behandelt werden, legen Sie fest — nicht der Agent.

Wie wird ein falsch gebuchter Bankumsatz korrigiert?

War es eine Zuordnung zu einer Rechnung, nimmt der Agent sie mit storno_payment zurück; der Umsatz steht danach wieder zur Zuordnung bereit. Eine sonstige Bankbuchung korrigieren Sie in der App mit „Buchung korrigieren“ — storno_journal_entry verweist bei Bankbuchungen genau dorthin.