Technische Dokumentation

KI-Finanzberichte: Systemdokumentation

Alles, was Sie benötigen, um die automatisierte Berichtserstellung von Nevald zu verstehen, einzurichten und produktiv zu nutzen — von der Datenanbindung bis zur fertigen Ausgabe.

Übersicht des KI-gestützten Finanzberichts-Dashboards von Nevald

8 Datenquellen nativ unterstützt

PDF, XLSX, JSON Ausgabeformate

Systemübersicht Datenintegration Konfiguration Ausgabeformate API-Referenz Sicherheit

Vollständige Systemdokumentation

Strukturierte Referenz für Entwickler, Administratoren und technische Anwender, die das Nevald-System in ihre Infrastruktur einbinden.

Systemübersicht

Das Nevald-System verarbeitet strukturierte und unstrukturierte Finanzdaten aus mehreren Quellen und erzeugt daraus vollständige, prüfbare Berichte — ohne manuelle Zwischenschritte. Die KI-Komponente übernimmt Klassifizierung, Aggregation und narrative Beschreibung der Kennzahlen.

Die Architektur ist modular aufgebaut. Datenanbindung, Verarbeitungs-Engine und Ausgabemodul laufen als eigenständige Dienste und können unabhängig voneinander skaliert werden.

Automatische Verarbeitung Berichte werden zeitgesteuert oder bei Datenänderung ausgelöst — keine manuelle Freigabe nötig.

KI-Analyse Abweichungen, Trends und Ausreißer werden automatisch erkannt und im Bericht kommentiert.

Mehrsprachige Ausgabe Berichte können in Deutsch, Englisch oder Französisch generiert werden — je nach Mandanteneinstellung.

Team bei der Arbeit mit dem Nevald Finanzberichts-System

Das System speichert keine Rohdaten dauerhaft. Alle Eingaben werden nach der Verarbeitung gelöscht, sofern keine explizite Archivierungsoption aktiviert ist.

Datenintegration

Nevald unterstützt acht native Konnektoren für gängige Buchhaltungs- und ERP-Systeme. Zusätzlich steht eine generische REST-Schnittstelle bereit, über die beliebige Datenquellen angebunden werden können.

Unterstützte Quellsysteme

System	Verbindungstyp	Synchronisationsintervall	Authentifizierung
DATEV	DATEV-API v2	stündlich	OAuth 2.0
SAP S/4HANA	OData v4	täglich	SAML / API-Key
Lexware	CSV-Export (SFTP)	täglich	SSH-Key
Xero	Xero API v2	stündlich	OAuth 2.0
QuickBooks	QBO REST API	stündlich	OAuth 2.0
Benutzerdefiniert	REST / Webhook	ereignisgesteuert	Bearer Token

Webhook-Einrichtung

Für ereignisgesteuerte Anbindungen sendet Ihr System eine POST-Anfrage an den Nevald-Endpunkt. Der Payload muss im JSON-Format vorliegen und ein gültiges source_id-Feld enthalten.

// Beispiel-Payload für Webhook-Integration
                  {
                  "source_id": "your-source-uuid",
                  "event": "data.updated",
                  "period": "2024-Q4",
                  "data": {
                  "revenue": 482900.00,
                  "expenses": 319400.00,
                  "currency": "EUR"
                  }
                  }

Fehlerbehandlung bei der Datenübertragung

Schlägt eine Übertragung fehl, wiederholt das System den Versuch nach 30 Sekunden, 2 Minuten und 15 Minuten. Nach drei erfolglosen Versuchen wird ein Fehler-Event in Ihrem Dashboard protokolliert und — sofern konfiguriert — eine E-Mail-Benachrichtigung versendet.

HTTP 4xx: Anfrage wird nicht wiederholt, Fehler sofort protokolliert
HTTP 5xx: Drei Wiederholungsversuche mit exponentiellem Backoff
Timeout nach 30 Sekunden: Wie HTTP 5xx behandelt

Alle fehlgeschlagenen Übertragungen sind im Bereich Protokoll → Integrationen mit vollständigem Request-Log einsehbar. Dort kann jede Anfrage manuell erneut ausgeführt werden.

Konfiguration

Jeder Mandant verfügt über eine eigene Konfigurationsdatei im YAML-Format. Diese Datei steuert, welche Kennzahlen in den Bericht einfließen, wie Abweichungen bewertet werden und welche Ausgabesprache verwendet wird.

# nevald-config.yaml — Beispielkonfiguration
                  tenant:
                  id: "tenant-001"
                  language: "de"
                  currency: "EUR"
                  report:
                  schedule: "0 6 1 * *" # Jeden 1. des Monats, 06:00 Uhr
                  period: "monthly"
                  format: ["pdf", "xlsx"]
                  thresholds:
                  deviation_warning: 0.08 # 8 % Abweichung = Hinweis
                  deviation_critical: 0.20 # 20 % Abweichung = Warnung
                  notifications:
                  email: "finanzen@ihr-unternehmen.de"
                  on_error: true
                  on_completion: true

Konfigurationsparameter im Überblick

schedule — Cron-Ausdruck für die automatische Berichtsauslösung. Zeitzone ist immer UTC.
period — Berichtszeitraum: monthly, quarterly oder annual.
deviation_warning / deviation_critical — Schwellenwerte für die KI-Bewertung von Abweichungen gegenüber dem Vorjahreszeitraum.
format — Mindestens ein Ausgabeformat muss angegeben sein. Mehrere Formate werden parallel erzeugt.

Änderungen an der Konfigurationsdatei werden erst beim nächsten geplanten Berichtslauf wirksam. Für sofortige Anwendung verwenden Sie den Endpunkt POST /api/v1/config/reload.

Ausgabeformate

Fertige Berichte stehen in drei Formaten zur Verfügung. Jedes Format enthält identische Kerndaten — lediglich Struktur und Darstellung unterscheiden sich je nach Verwendungszweck.

PDF Druckoptimiertes Layout mit Unternehmenslogo, Seitennummerierung und eingebetteten Diagrammen. Geeignet für Vorstands- und Aufsichtsratsberichte.

XLSX Strukturierte Tabellen mit Formeln und Pivot-Vorbereitung. Alle Kennzahlen als bearbeitbare Zellen, keine fest codierten Werte.

JSON Maschinenlesbare Ausgabe für Weiterverarbeitung in eigenen Systemen, Dashboards oder BI-Werkzeugen.

JSON-Ausgabestruktur

{
                  "report_id": "rpt-20241201-001",
                  "period": "2024-11",
                  "generated_at": "2024-12-01T06:03:14Z",
                  "summary": {
                  "revenue": 482900.00,
                  "expenses": 319400.00,
                  "net": 163500.00,
                  "deviation_yoy": 0.113
                  },
                  "flags": [
                  {
                  "type": "warning",
                  "metric": "expenses",
                  "message": "Ausgaben 11,3 % über Vorjahreszeitraum"
                  }
                  ]
                  }

API-Referenz

Die REST-API von Nevald folgt dem OpenAPI 3.1-Standard. Alle Endpunkte erfordern einen gültigen Bearer Token, der über das Mandantenportal generiert wird. Tokens haben eine Gültigkeitsdauer von 90 Tagen.

Methode	Endpunkt	Beschreibung
GET	/api/v1/reports	Liste aller generierten Berichte
GET	/api/v1/reports/{id}	Einzelnen Bericht abrufen
POST	/api/v1/reports/trigger	Berichtserstellung manuell auslösen
GET	/api/v1/reports/{id}/download	Bericht als Datei herunterladen
POST	/api/v1/config/reload	Konfiguration neu laden
GET	/api/v1/status	Systemstatus und letzte Aktivität

Authentifizierungsbeispiel

# Bericht manuell auslösen
                  curl -X POST https://api.nevaldai.services/api/v1/reports/trigger \
                  -H "Authorization: Bearer <IHR_TOKEN>" \
                  -H "Content-Type: application/json" \
                  -d '{"period": "2024-11", "format": ["pdf"]}'

Ratenlimits und Fehlercodes

Die API erlaubt 120 Anfragen pro Minute je Token. Wird das Limit überschritten, antwortet der Server mit HTTP 429 und dem Header Retry-After, der angibt, wie viele Sekunden bis zur nächsten erlaubten Anfrage gewartet werden muss.

Code	Bedeutung
400	Ungültiger Payload oder fehlende Pflichtfelder
401	Token fehlt oder ist abgelaufen
403	Keine Berechtigung für diesen Endpunkt
404	Bericht oder Ressource nicht gefunden
429	Ratenlimit überschritten
500	Interner Serverfehler — Support kontaktieren

Sicherheit & Datenschutz

Alle Verbindungen zum Nevald-System laufen ausschließlich über TLS 1.3. Daten werden während der Übertragung und im Ruhezustand mit AES-256 verschlüsselt. Der Verarbeitungsstandort liegt innerhalb der EU.

Zugriffskontrolle

Jeder Mandant ist vollständig isoliert — kein gemeinsamer Speicher, keine gemeinsamen Prozesse.
API-Tokens können auf einzelne Endpunkte beschränkt werden (Scope-basierte Berechtigungen).
Alle API-Zugriffe werden mit Zeitstempel, IP-Adresse und verwendetem Endpunkt protokolliert.
Protokolle werden 90 Tage aufbewahrt und stehen im Mandantenportal zum Download bereit.

Einrichtung in Ihrer Umgebung

Mandantenkonto im Nevald-Portal anlegen und Zwei-Faktor-Authentifizierung aktivieren.
API-Token mit den benötigten Scopes generieren und sicher in Ihrem Secret-Manager ablegen.
Datenquelle über den passenden Konnektor oder den generischen Webhook anbinden.
Konfigurationsdatei hochladen und mit einem Testlauf die Integration prüfen.
Automatischen Zeitplan aktivieren und E-Mail-Benachrichtigungen einrichten.

Bei Fragen zur Datenschutz-Grundverordnung oder zu individuellen Sicherheitsanforderungen wenden Sie sich direkt an admin@nevaldai.services. Für Enterprise-Mandanten ist ein dedizierter Ansprechpartner verfügbar.