KAI Backend API Referenz

Version: 34.0 (Production)
Datum: 20.11.2025
Basis-URL: /api
Authentifizierung: Header X-API-Key erforderlich.

Diese Dokumentation beschreibt alle verfügbaren Endpunkte des Systems, gruppiert nach funktionalen Modulen. Das System verwendet asynchrone Hintergrund-Jobs (Celery) für zeitaufwändige Aufgaben.

1. Modul: Lexoffice & Master-Workflows

Verwaltung der Buchhaltung, CSV-Exporte und Orchestrierung der Hauptprozesse.

POST /lexoffice/batch/run-full-workflow Async Job
Startet den kompletten Buchhaltungsprozess (Master-Workflow).
Sinn & Zweck:Orchestriert: 1. E-Mail-Abholung (KI), 2. Sortierung/Cleanup, 3. CSV-Export für Lexoffice. Nutzt State-Machine gegen Deadlocks.
Parameter:sources (Liste), start_date, end_date, model_label, profile_name
POST /lexoffice/batch/import-csv Async Job
Importiert eine CSV-Datei in Lexoffice und erstellt Belege.
Sinn & Zweck:Ermöglicht den Upload von extern erstellten Buchungsdaten (z.B. aus Shopware).
Parameter:file_path, account_name, tax_rate, category
GET /lexoffice/accounts
Listet konfigurierte Lexoffice-API-Konten.

2. Modul: KI-Rechnungsverarbeitung

KI-gestützte Extraktion von Daten aus Dokumenten.

POST /ai-invoices/batch/run-ai-workflow Async Job
Sammelt E-Mails aus Quellen, extrahiert Daten (OCR+KI) und erstellt PDFs.
Sinn & Zweck:Zentraler Einstiegspunkt für die Dokumentenerfassung aus IMAP, Gmail, Outlook. Erstellt standardisierte PDFs mit Metadaten.
Parameter:sources (Liste von Konten), query, model_label
POST /lexoffice-analyzer/batch/analyze-folder-for-lexoffice-csv Async Job
Analysiert einen lokalen Ordner und erstellt eine Lexoffice-Import-CSV.
Sinn & Zweck:Verarbeitet fertig sortierte Monatsordner und bereitet den Upload vor.
Parameter:folder_type, year, month, profile_name

3. Modul: Shopware SQL

Direkter Datenbankzugriff für E-Commerce Daten.

POST /shopware/batch/extract-and-export-csv Async Job
Exportiert Bestellungen aus der Shopware-DB als CSV.
Sinn & Zweck:Erzeugt Buchungsdaten für Online-Shop-Umsätze ohne manuelle Eingabe. Filtert nach Status (Bezahlt/Versendet).
Parameter:account_name, start_date, end_date, order_statuses (Filter)

4. Modul: E-Mail & Cloud Integrationen

Verbindung zu externen Providern.

POST /imap/batch/extract-invoices Async Job
Sucht und lädt Rechnungen aus einem IMAP-Konto.
Sinn & Zweck:Spezifischer Download-Task für Standard-IMAP-Konten. Nutzt UTF-8 Fix für Umlaute.
POST /google/batch/extract-invoices Async Job
Sucht und lädt Rechnungen via Gmail API.
Sinn & Zweck:Hochperformante Suche in Gmail (schneller als IMAP).
POST /microsoft/batch/extract-invoices Async Job
Sucht und lädt Rechnungen via Microsoft Graph (Outlook).
Sinn & Zweck:Nutzung der Graph API für Office 365 Konten. Inklusive Token-Refresh.
POST /imap/batch/find-and-move Async Job
Verschiebt E-Mails basierend auf Suchkriterien.
Sinn & Zweck:Organisiert Postfächer (z.B. "Erledigt" Ordner). Nutzt UTF-8 Fix.

5. Modul: WhatsApp

POST /whatsapp/webhook
Empfängt Nachrichten von Meta.
Sinn & Zweck:Reagiert auf eingehende Bilder/PDFs, lädt sie herunter und startet den OCR-Prozess.

6. Modul: Workspace (Dateisystem)

POST /workspace/run-cleanup-workflow Async Job
Räumt einen Ordner auf und sortiert Dateien.
Sinn & Zweck:Erkennt Duplikate (z.B. gleiche Rechnung aus E-Mail und Shopware), benennt Dateien um und sortiert sie in Jahr/Monats-Ordner.
Parameter:folder_type, profile_name
GET /workspace/list/{folder_type}
Listet Dateien in einem Verzeichnis (uploads, exports, etc.).

7. Modul: System & Jobs

GET /api/jobs/result/{job_id}
Fragt den Status eines Hintergrund-Jobs ab.
Sinn & Zweck:Polling für das Frontend. Gibt Fortschritt oder Endergebnis (JSON) zurück.
GET /api/system/stats
Liefert Systemstatus (Worker, Redis, Speicherplatz).
POST /api/debug/extract-raw-text Diagnose
Extrahiert reinen OCR-Text aus einer E-Mail.
Sinn & Zweck:Hilft Entwicklern, Regex-Muster in der config.json zu optimieren, indem man sieht, was die OCR "wirklich" sieht.

8. Modul: Parsing Profile

POST /parsing/analyze-sources Async Job
Analysiert E-Mail-Historie auf Kontakte.
Sinn & Zweck:Schlägt automatisch Regeln für Einnahmen/Ausgaben vor, basierend auf häufigen Absendern.
Parameter:sources, keywords
PUT /parsing/profiles/{profile_name}
Aktualisiert ein Parsing-Profil (Regelwerk).