Berichte

Die Berichts-Tools lesen und bearbeiten Berichte in Fyvel. Du kannst Berichte auflisten, Definitionen laden, berechnete Werte abrufen, Drilldowns ausführen und Berichtszeilen strukturiert ändern.

Verfügbare Tools

list_reports
create_report
delete_report
toggle_report_star
get_report
resolve_report
resolve_report_row_drilldown
apply_report_rows
reorder_report_rows
delete_report_row

Scope

Berichte sind organisationsweit. Du brauchst dafür keine companyUuid.

Empfohlener Ablauf

Struktur laden

list_reports
passendes reportUuid auswählen
get_report - liefert Zeilen, Zeilen-UUIDs (reportRowUuid), Reihenfolge und Konfiguration

Zahlen prüfen

list_layers — Buchungsebenen für die Gesellschaft laden (layer_uuid, is_default, is_forecast)
resolve_report — berechnete Werte pro Zeile und Periode (siehe Resolve-Modi und Analytics-Cache unten)
bei Bedarf resolve_report_row_drilldown — gleicher Modus und dieselbe Ebenen-Konfiguration wie beim zugehörigen resolve_report

Analytics-Cache und Retry

Buchungsbasierte Berichtswerte stammen aus einem Analytics-Cache, den Fyvel nach Änderungen an Buchungen oder Zuordnungen im Hintergrund neu aufbaut (FastAPI-Microservice). Wenn resolve_report auf allen Daten- und berechneten Zeilen nur leere Werte findet (null oder 0), antwortet das Tool mit einem Fehler statt einer Erfolgsantwort:

Report data is still being refreshed. Wait a few seconds and call this tool again.

Der Server markiert den Cache der betroffenen Gesellschaft dabei als veraltet; beim Retry wird er in der Regel neu aufgebaut und liefert danach echte Zahlen. Wichtig für Agenten:

Diesen Fehler nicht als leeren Bericht interpretieren — kurz warten und denselben Aufruf wiederholen.
Besonders nach set_booking_category, accept_ai_mapping_suggestions, append_manual_transactions o. Ä.: erst analysieren, wenn resolve_report erfolgreich Zahlen liefert.
Header- und Abstandszeilen (header, spacer) zählen nicht — nur data- und calculated-Zeilen fließen in die Prüfung ein.
resolve_report_row_drilldown nutzt keine Refresh-Pending-Prüfung: rows: [] bedeutet, dass zur Zeile keine Kategorien oder Konten mit Buchungsdaten passen — kein Retry nötig.

Resolve-Modi

resolve_report und resolve_report_row_drilldown kennen drei sich gegenseitig ausschließende Modi — dieselbe Logik wie in der Web-App unter Einstellungen in der Berichtsansicht.

Modus	Parameter	Ebenen
Standard (Default)	`selectedLayerUuids` und/oder `selectedLayerGroupUuids`	eine flache Auswahl für den gesamten Zeitraum
Rolling Forecast	`periodSlices`	pro Segment (`actual` / `forecast`) eigene Ebenen
Vergleich	`compareSides`	`sideA` und `sideB` getrennt; Ergebnis ist sideA − sideB

periodSlices und compareSides dürfen nicht gleichzeitig gesetzt werden. Im Standard-Modus ohne Ebenen liefert der Resolver nur Nullen.

Standard

Typische Ist-Ebenen: is_default: true, kein Snapshot (layer_type ungleich snapshot). Gruppen über list_layer_groups → selectedLayerGroupUuids.

{
  "reportUuid": "<report-uuid>",
  "companyUuid": "<company-uuid>",
  "periodFrom": "2025-01",
  "periodTo": "2025-12",
  "aggregationMode": "monthly",
  "selectedLayerUuids": ["<default-actual-layer-uuid>"]
}

Rolling Forecast

Über periodSlices kombinierst du Ist- und Forecast-Segmente. Üblich: zwei Segmente — Ist bis einschließlich Stichtag, Forecast ab dem Folgemonat. Slice-Perioden als monatliche Keys (YYYY-MM), auch wenn aggregationMode quarterly oder yearly ist.

{
  "reportUuid": "<report-uuid>",
  "companyUuid": "<company-uuid>",
  "periodFrom": "2025-01",
  "periodTo": "2025-12",
  "aggregationMode": "monthly",
  "periodSlices": [
    {
      "periodFrom": "2025-01",
      "periodTo": "2025-06",
      "segmentKind": "actual",
      "selectedLayerUuids": ["<ist-layer-uuid>"]
    },
    {
      "periodFrom": "2025-07",
      "periodTo": "2025-12",
      "segmentKind": "forecast",
      "selectedLayerUuids": ["<forecast-layer-uuid>"]
    }
  ]
}

Die Antwort enthält period_forecast mit Flags pro Spalte (has_forecast, has_historical, is_mixed).

Vergleich

Zwei Ebenen-Konfigurationen gegenüberstellen — z. B. Ist vs. Plan oder aktueller Stand vs. Snapshot.

{
  "reportUuid": "<report-uuid>",
  "companyUuid": "<company-uuid>",
  "periodFrom": "2025-01",
  "periodTo": "2025-12",
  "compareSides": {
    "sideA": { "label": "Ist", "selectedLayerUuids": ["<actual-layer-uuid>"] },
    "sideB": { "label": "Plan", "selectedLayerUuids": ["<plan-layer-uuid>"] }
  }
}

Jede Seite kann selectedLayerUuids und/oder selectedLayerGroupUuids nutzen. Im Vergleichsmodus sind die period_forecast-Flags in der Antwort zurückgesetzt. Zeilen ändern

Neue oder geänderte Zeilen über apply_report_rows senden
Nur die Reihenfolge ändern: reorder_report_rows mit allen Zeilen-UUIDs in der gewünschten Reihenfolge
Eine einzelne Zeile löschen: delete_report_row

Batch-Zeilen (`apply_report_rows`)

Mit apply_report_rows kannst du mehrere Zeilen in einem Aufruf anlegen oder aktualisieren.

Zeilentypen: unter anderem data_pl, data_bs, data_cashflow, data_cashflow_capex, data_cashflow_equity_change, calculated, header, spacer
Neue Zeilen: reportRowUuid weglassen
Bestehende Zeilen: vorhandene reportRowUuid mitgeben
Limit: maximal 60 Zeilen pro Request
Referenzen auf neue Zeilen: mit clientKey und refClientKey arbeiten, wenn berechnete Zeilen im selben Request auf neu angelegte Zeilen verweisen

Für Vorzeichen gilt: data_pl, data_cashflow, data_cashflow_capex und data_cashflow_equity_change nutzen optional changeSign relativ zum Standard. data_cashflow_capex erwartet fixedAssetChangeSources (Bilanz-Delta) und depreciationSources (GuV-Periodenwert). data_cashflow_equity_change erwartet nur shareholderEquityChangeSources (Bilanz-Delta); kumuliertes GuV-Ergebnis (YTD) und Nettoergebnis (Periode) werden automatisch über die gesamte GuV berechnet. data_bs und calculated nutzen signConvention. Das Ergebnis kannst du mit resolve_report prüfen.

Typische Anwendungsfälle

Berichte auflisten und favorisieren (toggle_report_star)
Berichte anlegen oder löschen
Berichtsstruktur und Zeilen-UUIDs laden (get_report)
Zahlen und Forecast-Flags aus dem Resolver holen (resolve_report) — Standard, Rolling Forecast oder Vergleich
Ist vs. Plan oder Snapshot vergleichen (compareSides)
Ist- und Forecast-Perioden über einen Stichtag kombinieren (periodSlices)
Datenzeilen in der Tiefe aufdröseln (resolve_report_row_drilldown)
Mehrere Zeilen auf einmal erstellen oder anpassen (apply_report_rows)
Gesamtreihenfolge setzen (reorder_report_rows)
Einzelne Zeile entfernen (delete_report_row)

Einstieg

Organisation & Stammdaten

Unternehmensdaten

Berichte

Berichte

Berichte

Verfügbare Tools

Scope

Empfohlener Ablauf

Analytics-Cache und Retry

Resolve-Modi

Standard

Rolling Forecast

Vergleich

Batch-Zeilen (`apply_report_rows`)

Typische Anwendungsfälle

​Berichte

​Verfügbare Tools

​Scope

​Empfohlener Ablauf

​Analytics-Cache und Retry

​Resolve-Modi

​Standard

​Rolling Forecast

​Vergleich

​Batch-Zeilen (apply_report_rows)

​Typische Anwendungsfälle

Berichte

Verfügbare Tools

Scope

Empfohlener Ablauf

Analytics-Cache und Retry

Resolve-Modi

Standard

Rolling Forecast

Vergleich

Batch-Zeilen (`apply_report_rows`)

Typische Anwendungsfälle