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. Verwaltung → Verbindungen (/manage/connections), Karte „Bankkonten (finAPI)“
2. Bankkonto verbinden → du landest auf dem finAPI-Web-Form
3. Bank suchen, Online-Banking-Zugangsdaten eingeben (PSD2-Flow direkt bei finAPI, nicht bei TaskMonkey)
4. Konto(en) auswählen → Konto erscheint auf der Verbindungen-Seite

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

#Aktualisierung

TaskMonkey gleicht die Konten automatisch ab (Plattform-Cron, für alle Workspaces):

• Bankabruf höchstens 4× am Tag je Bankverbindung (PSD2 erlaubt ohne anwesenden Kunden nur wenige Abrufe; mehr sperrt die Bank).
• Abgleich mit finAPI (Umsätze, Saldo) höchstens alle 30 Minuten je Konto, sofort nach einem frischen Bankabruf.
• Verlangt die Bank eine neue Anmeldung (alle 90–180 Tage), ruft TaskMonkey sie nicht mehr ab, bis du auf der Verbindungen-Seite Neu verbinden klickst; die Admins bekommen einmal eine Mail.

Die Tools lesen immer den gespeicherten Stand. Ist er älter als 24 Stunden oder steht eine Neu-Anmeldung aus, liefern sie stale=true mit stale_hint (Stand-Datum).

#Banking-Tools (alle Workspaces)

Bewusst nur lesend: kein Abruf-Trigger, keine Überweisung, kein Trennen per Tool. IBANs (eigene und Gegenseite) sind maskiert, finAPI-IDs und Tokens kommen nie ins Ergebnis.

Wer darf: angemeldete Admins und Manager des Workspaces sowie eigene Scheduled Tasks. Im Website-Chat (anonym), in Inbox-Bots, die Kunden-Mails beantworten, und über Webhooks lehnen die Tools ab — auch wenn sie dort in der Tool-Liste stehen. Ein Workspace sieht nie Konten oder Umsätze eines anderen; eine fremde account_id/IBAN ergibt „nicht gefunden“.

Aktivieren wie bei jedem Tool: in der tools-Liste eines internen Assistenten (nie in public.tools). Am einfachsten sagst du dem Builder „Nimm die Bank-Auswertung in meinen Assistenten auf“.

'assistants.buchhaltung' => [
    'name' => 'Buchhaltung',
    'tools' => [
        'listBankAccounts',
        'getBankTransactions',
        'setSuggestions',
    ],
],

#Beispiel: Zahlungseingang prüfen

„Ist die Zahlung von Kunde X angekommen?“

Bei Fragen zu Zahlungseingängen:
1. getBankTransactions mit direction=in und counterpart=<Kunde>
   oder text=<Rechnungsnummer>, Zeitraum passend (days=60)
2. Treffer mit Datum, Betrag, Verwendungszweck zeigen
3. Kein Treffer: Stand nennen (stale_hint), nichts erfinden

#Beispiel: Wöchentlicher Cashflow-Report

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

Beim Aufruf:
1. listBankAccounts → Konten mit Salden
2. getBankTransactions mit days=7 je Konto (account_id)
3. Markdown-Tabelle: Konto · Eingang · Ausgang · Saldo
4. Kurzes Resümee (Trends, Auffälligkeiten), Stand-Datum nennen
PROMPT,

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

#FinAPI-Version

TaskMonkey nutzt aktuell finAPI Access V1. finAPI führt V1 als veraltet; die Umstellung auf V2 (mit Web Form 2.0) ist vorbereitet und wird auf Plattform-Seite eingeschaltet. 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)
• Tools respektieren Workspace-Grenzen — ein Workspace sieht nie Konten eines anderen
• Nur lesend, nur Admins/Manager und eigene Automationen, IBANs maskiert
• tm monitor zeigt alle Tool-Aufrufe — du siehst, wer wann was abgefragt hat

#Debug

tm test-tool listBankAccounts
tm test-tool getBankTransactions days=7 direction=in
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.