Banking (FinAPI)

Bankkonten verbinden und Transaktionen in Tools nutzen.

TaskMonkey integriert FinAPI für PSD2-konformen Bankkonten-Zugriff. Damit liest du Kontostände und Transaktionen aus deinen Geschäftskonten direkt aus Tools — ideal für automatisierte Buchhaltung, Zahlungsabgleich, Reporting und Cashflow-Monitoring.

#Konto verbinden

1. Gehe zu /manage/bank-accounts
2. Neue Verbindung → du landest auf einem FinAPI-Web-Form
3. Bank suchen, Online-Banking-Zugangsdaten eingeben (PSD2-Flow direkt bei FinAPI, nicht bei TaskMonkey)
4. Konto(en) auswählen
5. Bestätigung → Konto erscheint in der Liste

Die Bank-Zugangsdaten werden nicht in TaskMonkey gespeichert. Lediglich FinAPI-interne Tokens und Konto-IDs liegen in der Datenbank.

#Was wird gespeichert

Pro Konto:

Die FinAPI-internen IDs (finapi_user_id, finapi_bank_connection_id, finapi_account_id) werden mitverwaltet, sind für dich aber transparent.

#Banking-Tools für deine Workspaces

Sobald ein Konto verbunden ist, stehen dir diese Shared Tools zur Verfügung:

Aktivieren wie bei jedem Tool: in der tools-Liste des Assistant oder Public Chats freigeben.

'assistants.buchhaltung' => [
    'name' => 'Buchhaltung',
    'tools' => [
        'listAccounts',
        'getBalance',
        'searchTransactions',
        'getRecentTransactions',
        'syncTransactions',
        'setSuggestions',
    ],
],

#Default-IBAN

Wenn dein Workspace überwiegend mit einem Konto arbeitet, hinterlege es als Default. Dann brauchen die Tools keinen iban-Parameter:

// apis.php
'apis' => [
    'banking' => [
        'defaultIban' => 'DE12345678901234567890',
    ],
],

Das Modell muss dann nicht jedes Mal nach der IBAN fragen. Bei mehreren Konten kann es sie als Argument übergeben — auch eine Teil-IBAN (z. B. nur die letzten 4–6 Stellen) wird auf das passende Konto gemappt.

#Refresh

Es gibt kein Auto-Refresh der Transaktionen. Du musst aktiv syncTransactions aufrufen — entweder im Chat (auf Nachfrage) oder als Scheduled Task:

// scheduled.php
'sync_banking' => [
    'enabled' => true,
    'tool' => 'syncTransactions',
    'interval' => '1h',
],

Vor jedem Sync wird automatisch die Bank-Connection bei FinAPI aktualisiert. Wenn die Bank Re-Authentifizierung erfordert (PSD2-Vorgabe alle 90 Tage), bekommst du eine Warnung im Log und musst die Verbindung in /manage/bank-accounts einmal manuell erneuern.

#Beispiel: Zahlungseingang prüfen

Ein typischer Use-Case — Modell beantwortet „Ist die Zahlung von Kunde X angekommen?":

Du bist der Buchhaltungs-Assistent. Bei Fragen zu Zahlungseingängen:
1. searchTransactions mit dem Kundennamen oder Rechnungsnummer als Filter
2. Zeige Treffer mit Datum, Betrag, Verwendungszweck
3. Wenn kein Treffer: prüfe, wann zuletzt syncTransactions lief —
   biete an, einen Sync auszulösen

#Beispiel: Wöchentlicher Cashflow-Report

// assistants/cashflow.php
'assistants.cashflow.prompt' => <<<PROMPT
Du erstellst Cashflow-Reports.

Beim Aufruf:
1. listAccounts → alle Konten mit Salden
2. searchTransactions für die letzte Woche, kategorisiert nach
   Eingang/Ausgang
3. Baue eine Markdown-Tabelle: Konto · Eingang · Ausgang · Saldo
4. Schreibe ein kurzes Resümee (Trends, Auffälligkeiten)
PROMPT,

Plus Scheduled Task, der diesen Assistant jeden Montag morgens triggert und per Mail verschickt.

#FinAPI-Version

TaskMonkey nutzt aktuell FinAPI V1. FinAPI hat angekündigt, V1 zum 30.06.2026 abzuschalten. Die Migration auf V2 läuft auf Plattform-Seite — für dich als Workspace-Entwickler ändert sich an den Tool-Signaturen nichts.

#Sicherheit

• Bank-Zugangsdaten werden nie in TaskMonkey gespeichert (PSD2-Flow direkt mit der Bank)
• Tokens liegen verschlüsselt in der DB
• Tools respektieren Workspace-Grenzen — ein Workspace sieht nie Konten eines anderen
• tm monitor und Audit-Logs zeigen alle Banking-Tool-Aufrufe — du siehst, wer wann was abgefragt hat

#Debug

tm test-tool listAccounts
tm test-tool getBalance iban=DE...
tm logs                     # bei API-Fehlern

Bei FinAPI-spezifischen Fehlern (Re-Authentifizierung nötig, Konto nicht mehr verfügbar) ist die Fehlermeldung typisch sprechend — falls nicht, frag den Betreiber.