> ## Documentation Index > Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt > Use this file to discover all available pages before exploring further. # Finanzberichte: Konzepte > Wie Fynn die Finanzkennzahlen berechnet, warum MRR, Accounted MRR, Zahlungseingang und Umsatz voneinander abweichen und wie Monate, Ebenen, Abschlüsse und Hinweise funktionieren. Die Finanzberichte-API liefert dieselben Zahlen, die du in der App unter Berichte siehst: MRR und seine Bewegungen, Accounted MRR, Zahlungen, Forderungen, Umsatz, die Kundenbasis und Monatsabschlüsse. Diese Seite erklärt die Begriffe, die in allen Antworten vorkommen. Die Beispiele auf allen Seiten dieser Gruppe stammen aus derselben Beispielorganisation wie die [Benutzerhandbücher der Berichte](https://docs.fynn.eu/guide/analytics/reports/overview.md), der Taktwerk GmbH, und passen zueinander. ## Zugriff Du authentifizierst jede Anfrage mit einem API-Token deiner Organisation, wie unter [Authentifizierung](https://docs.fynn.eu/v2-offers-api/authentication.md) beschrieben. | Voraussetzung | Wofür | | - | - | | Berechtigung `analytics:read` | Alle lesenden Endpunkte: Datensätze, Drill-downs, Hinweise, Definitionen, Snapshots, Excel | | Berechtigung `analytics:write` | Einen Monat erneut abschließen, Einstellungen ändern | | Freischaltung der Finanzberichte | Alle Endpunkte dieser API | Die Finanzberichte schaltet Fynn für deine Organisation frei. Bis dahin antwortet jeder Endpunkt dieser API mit `403` und dem Typ `feature-not-available`, siehe [Fehler](https://docs.fynn.eu/v2-finance-api/errors.md). ## Wie die Zahlen entstehen Fynn berechnet die Kennzahlen einer Organisation stündlich im Hintergrund. Die Berechnung liest die Verträge (Abonnements, Positionen, Zeitpläne, Preisverläufe, Rabatte, Pausen und Kündigungen), die abgeschlossenen Belege, die Zahlungen und die Abrechnungsprognose. Daraus entsteht für jeden Monat und jede Position ein Monatsbeitrag, und aus den Beiträgen entstehen Bestände, Bewegungen und alle weiteren Kennzahlen. Jede Antwort nennt in `meta.asOf` den Zeitpunkt der Berechnung, aus der ihre Zahlen stammen. Die Berechnung repariert keine Daten. Wenn sie eine Annahme treffen muss, zum Beispiel weil der Preisverlauf einer Position fehlt, rechnet sie mit einer festen Regel weiter und hält das als Hinweis fest. So bleibt jede Zahl nachvollziehbar: Über die [Drill-downs](https://docs.fynn.eu/v2-finance-api/drill-downs.md) erreichst du die Zeilen hinter jeder Zelle, und ihre Summe ergibt genau den Wert der Zelle. Am 1. jedes Monats um 05:00 Uhr in der Zeitzone deiner Organisation hält Fynn die MRR-Zahlen und die Geldwerte des Vormonats als Snapshot fest. Spätere Korrekturen an einem abgeschlossenen Monat ändern die laufende Berechnung, aber nie den Snapshot. Die Differenz heißt Nachtrag und ist mit Ursache abrufbar. ## Vier Zahlen, vier Quellen Vier Kennzahlen beschreiben Umsatz aus unterschiedlichen Quellen. Sie weichen deshalb voneinander ab, und das ist gewollt. | Kennzahl | Quelle | Zeitpunkt | Taktwerk GmbH, September 2026 | | - | - | - | - | | MRR | Verträge | letzte Sekunde des Monats | 53.414,80 € | | Accounted MRR | wiederkehrende Positionen abgeschlossener Rechnungen | anteilig nach Leistungszeitraum (30/360) | 53.414,80 € | | Zahlungseingang | Zahlungen | Zahldatum | 59.869,28 € | | Umsatz | alle Positionen abgeschlossener Belege | Monat der Ausstellung | 56.713,90 € (53.866,90 € wiederkehrend, 1.470,00 € einmalig, 1.377,00 € variabel) | Ein Jahresvertrag über 1.200,00 € netto zeigt den Unterschied. Die Rechnung wird im Januar abgeschlossen und im Februar bezahlt, der Leistungszeitraum ist das Kalenderjahr. * **MRR**: 100,00 € in jedem Monat des Vertrags, weil der Vertrag auf den Monat umgerechnet wird. * **Accounted MRR**: 100,00 € in jedem Monat, weil die Rechnung nach 30/360 auf ihren Leistungszeitraum verteilt wird (30 von 360 Tagen je Monat). * **Zahlungseingang**: 1.428,00 € brutto im Februar, dem Monat der Zahlung. * **Umsatz**: 1.200,00 € im Januar, dem Monat, in dem die Rechnung abgeschlossen wurde. MRR und Accounted MRR liegen nahe beieinander, solange die Rechnungen den Verträgen folgen. Im September 2026 sind sie bei der Taktwerk GmbH gleich. Die Differenz steht als eigene Zeile `billing_gap` (Differenz Vertrag zu Rechnung) in der MRR-Tabelle, gerechnet als Vertrag minus Rechnung und nach Ursachen aufgeteilt. Ein positiver Wert heißt: Es wurde weniger abgerechnet, als der Vertrag vorsieht. Im August 2026 sind das +79,00 €, weil eine Rechnung über 79,00 € noch aussteht (`not_yet_billed`). Im Juli 2026 sind es −149,00 €, weil eine Rechnung 149,00 € über dem Vertrag liegt (`price_mismatch`). > [!NOTE] > > Accounted MRR folgt den Rechnungen, nicht den Erlösbuchungen. Die Buchhaltung kann eine Gutschrift in einem anderen Monat erfassen als die Berechnung. Für den Jahresabschluss gilt immer die Buchhaltung. ## Konten und Ebenen Bewegungen (Neu, Expansion, Kontraktion, Verloren, Reaktiviert) entstehen je Konto. Welche Einheit ein Konto ist, bestimmt die Ebene im Parameter `scope`: | `scope` | Ein Konto ist | | - | - | | `subscription` | ein Abonnement | | `invoice_address` | eine Rechnungsadresse (Voreinstellung einer neuen Organisation) | | `customer` | ein Kunde | | `organisation` | der oberste Kunde eines Kundenverbunds mit allen zugehörigen Kunden | Die Ebene ändert keine Summen. MRR am Monatsende ist auf jeder Ebene gleich. Sie ändert, wie sich Änderungen auf Bewegungen und Kontenzahlen verteilen. Ein Beispiel: Ein Kunde hat zwei Abonnements. Beim ersten steigt die Menge um 100,00 €, das zweite über 60,00 € endet. Mit `scope=subscription` siehst du eine Expansion über 100,00 € und einen Verlust über 60,00 €. Mit `scope=customer` bleibt ein Konto mit einer Expansion über 40,00 €, deren Ursachen die beiden Änderungen sind. Fynn berechnet immer alle vier Ebenen. Welche gilt, wenn eine Anfrage keinen `scope` mitschickt, legst du in den Einstellungen fest. Die Taktwerk GmbH zählt je Kunde. Dort steht auch der Schwellenwert für Nachträge. ```bash theme={null} curl https://coreapi.io/api/analytics/mrr-financials/settings \ -H "Authorization: Bearer api_DEIN_TOKEN" ``` ```json theme={null} { "movementScope": "customer", "mrrRestatementAlertShare": "0.01" } ``` Mit `PATCH` änderst du einen oder beide Werte. Felder, die du weglässt, behalten ihren Wert. ```bash theme={null} curl -X PATCH https://coreapi.io/api/analytics/mrr-financials/settings \ -H "Authorization: Bearer api_DEIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"movementScope": "invoice_address"}' ``` ```json theme={null} { "movementScope": "invoice_address", "mrrRestatementAlertShare": "0.01" } ``` ## Monate, Zeitraum und Zeitzone Monate schreibst du als `YYYY-MM` zwischen 1900 und 2099. Ein Monat beginnt und endet in der Zeitzone deiner Organisation. MRR ist der Bestand in der letzten Sekunde des Monats. | Parameter | Bedeutung | Voreinstellung | | - | - | - | | `from` | erster Monat | `to` minus 11 Monate | | `to` | letzter Monat | der laufende Monat | | `currency` | ISO-4217-Code einer Währung deiner Organisation | die Standardwährung | Ein Zeitraum umfasst höchstens 36 Monate, und `from` darf nicht nach `to` liegen. Beträge werden nie zwischen Währungen umgerechnet: Jede Antwort enthält genau eine Währung. Verträge mit anderen Intervallen werden auf einen Monat mit 30 Tagen umgerechnet. Ein Wochenpreis von 70,00 € ergibt 300,00 € MRR, weil eine Woche 7/30 eines Monats ist. Für Monate nach dem laufenden gibt es noch keine Zahlungen. Solche Werte sind `null`. Bestände wie offene Forderungen schreibt die Berechnung dort als Prognose mit den heute offenen Rechnungen fort. Ab welchem Monat das gilt, steht in `meta.projectedFrom`. ## Der laufende Monat Jede Kennzahl-Kachel sagt, für welchen Monat ihr Wert gilt: `asOfMonth` nennt den Monat, `monthComplete` ist `false`, solange er läuft. Die Kacheln des Wiederkehrenden Umsatzes zeigen immer den letzten abgeschlossenen Monat, wie der MRR-Waterfall. Reicht der Zeitraum bis in den laufenden Monat, steht dessen bisheriger Wert daneben in `current`. Am 01.10.2026 mit `to=2026-10` sieht die MRR-Kachel so aus: ```json theme={null} { "kpis": [ { "id": "mrr", "title": "MRR", "valueKind": "money", "value": "53414.80", "delta": "1568.80", "better": "up", "sparkline": [ "32074.00", "33728.00", "35406.00", "39440.90", "44674.40", "45797.40", "46869.70", "47533.40", "49076.90", "51831.50", "51846.00", "53414.80" ], "caption": null, "asOfMonth": "2026-09", "monthComplete": true, "current": { "asOfMonth": "2026-10", "value": "53530.80", "delta": "116.00", "monthComplete": false } } ] } ``` Der September ist abgeschlossen und zeigt 53.414,80 €. Der Oktober läuft und steht bisher bei 53.530,80 €, weil ein Rabatt über 116,00 € endet. Endet der Zeitraum vor dem laufenden Monat, ist `current` `null`. Kacheln mit dem Bezug „heute", etwa die offenen Forderungen, tragen den laufenden Monat mit `monthComplete: false`. ## Beträge, Raten und Vorzeichen Beträge sind exakte Dezimalzahlen als Text mit zwei Nachkommastellen, nie Gleitkommazahlen. Meist stehen sie in einem Objekt mit Währung: ```json theme={null} { "amount": "53414.80", "currency": "EUR" } ``` Raten und Anteile haben sechs Nachkommastellen: `"0.032575"` sind 3,2575 %. Die Umsatz-Churn-Rate im September ist (350,90 + 1.338,00) / 51.846,00 = `"0.032575"`. Die API formatiert nie Prozente. | Wo | Kontraktion und Verloren | | - | - | | MRR-Tabelle (`rows.contraction`, `rows.lost`) | positiv, weil die Zeilen Beträge zeigen, die den MRR senken | | Ursachen (`reasons`) | mit Vorzeichen, Rückgänge negativ | | MRR-Waterfall (`steps[].value`) und Finanzübersicht | negativ | | Drill-down-Zeilen (`amount`) | negativ; die Summe ist der negative Wert der Zelle | Die Differenz Vertrag zu Rechnung rechnet überall gleich: Vertrag minus Rechnung, in der MRR-Tabelle, im Abgleich der Liquiditätsseite, in den Drill-downs und in Excel. ## Das `meta`-Objekt Jeder Datensatz enthält ein `meta`-Objekt mit dem Kontext der Antwort: ```json theme={null} { "asOf": "2026-10-01T04:00:00+00:00", "buildId": "0199c0de-0000-7000-8000-00000000b001", "scope": "customer", "currency": "EUR", "from": "2026-07", "to": "2026-09", "findings": { "error": 0, "warning": 6, "info": 9 }, "filtersNotApplied": [], "notSnapshotted": [ "one_off", "variable", "accounted_mrr", "billing_gap", "cash_collected", "cash_collected_this_month", "cash_collected_other_months", "cash_collected_unassigned", "cash_refunded", "cash_net", "cash_forecast", "receivables_eop" ], "projectedFrom": null, "forecast": { "incomplete": false, "failedSubscriptions": 0 }, "build": { "status": "succeeded", "builtAt": "2026-10-01T04:00:00+00:00", "buildId": "0199c0de-0000-7000-8000-00000000b001", "failed": null }, "dataBuildId": "0199c0de-0000-7000-8000-00000000b001" } ``` | Feld | Bedeutung | | - | - | | `asOf` | Zeitpunkt der Berechnung, aus der die Zahlen stammen; `null`, solange noch keine Berechnung existiert | | `buildId` | Kennung dieser Berechnung | | `scope`, `currency`, `from`, `to` | die tatsächlich verwendeten Werte, auch wenn du sie nicht mitgeschickt hast | | `findings` | Anzahl der Hinweise je Stufe | | `filtersNotApplied` | Datensätze, die einen Kunden-, Produkt- oder Segmentfilter nicht anwenden können, weil ihre Daten diese Dimension nicht haben (Zahlungen haben kein Produkt) | | `notSnapshotted` | Zeilen der MRR-Tabelle, die ein Snapshot nicht enthält; sie zeigen immer aktuelle Werte | | `projectedFrom` | erster Monat, ab dem Bestände als Prognose fortgeschrieben sind | | `forecast` | ob die Rechnungsprognose vollständig ist, siehe unten | | `build` | der letzte Berechnungsversuch: `status` (`succeeded` oder `failed`), `builtAt`, `buildId` und bei einem Abbruch `failed`, siehe unten | | `dataBuildId` | Kennung der Berechnung, aus der die Zahlen stammen, also der letzten erfolgreichen. Nach einem Abbruch weicht sie von `build.buildId` ab. `buildId` enthält denselben Wert und bleibt aus Kompatibilitätsgründen. | ### Unvollständige Rechnungsprognose Scheitert die Abrechnungsprognose für ein Abonnement, fehlt es in jedem Prognosemonat, und es entsteht der Hinweis `FORECAST_FAILED`. Enthält der Zeitraum den laufenden oder spätere Monate, meldet `meta.forecast` das: ```json theme={null} { "incomplete": true, "failedSubscriptions": 2 } ``` Ein Prognosewert ist dann eine Untergrenze, keine Aussage „keine Rechnungen". Zeige ihn als unvollständig an, nie als 0,00 €. Die Excel-Bücher schreiben die Zeile als „Rechnungsprognose (brutto), unvollständig (2 Abos ohne Prognose)". ### Abgebrochene Berechnung Jede Berechnung prüft ihre Zahlen, bevor sie sie speichert, zum Beispiel dass der Zahlungseingang einer Rechnung ihren Bruttobetrag nicht übersteigt. Schlägt eine Prüfung fehl, wird die Berechnung abgebrochen und nichts davon gespeichert. Die Antworten zeigen weiter die Zahlen der letzten erfolgreichen Berechnung (`dataBuildId`, `asOf`), und `meta.build` beschreibt den Abbruch: ```json theme={null} { "status": "failed", "builtAt": "2026-09-28T12:00:00+00:00", "buildId": "0199c0de-0000-7000-8000-00000000b002", "failed": { "invariants": ["CASH_WITHIN_DOCUMENT"], "rowCount": 2, "invoiceRowCount": 2 } } ``` | Feld | Bedeutung | | - | - | | `failed.invariants` | die Codes der fehlgeschlagenen Prüfungen, sortiert; `IDENTITY` steht für die MRR-Identität Beginn + Bewegungen = Ende | | `failed.rowCount` | Anzahl der Abweichungen insgesamt | | `failed.invoiceRowCount` | wie viele der aufgelisteten Abweichungen eine Rechnung nennen; gleich `rowCount`, wenn jede Abweichung eine Rechnung betrifft | Die einzelnen Abweichungen liest du über die Detail-Kennzahl [`build_failure`](https://docs.fynn.eu/v2-finance-api/drill-downs#abgebrochene-berechnung). Die nächste erfolgreiche Berechnung setzt `status` wieder auf `succeeded`. Die App zeigt einen Abbruch als Hinweis „Berechnung abgebrochen" über den Finanzseiten. ## Snapshots und Nachträge Ein Snapshot hält die Zahlen eines abgeschlossenen Monats fest: MRR zu Beginn und Ende, die fünf Bewegungen und ihre Ursachen, Kohorten, Kundenkonzentration, gebundenen MRR und seit dem 28.09.2026 auch Zahlungseingang, Zahlungsausgang, offene Forderungen und DSO. Version 1 entsteht automatisch am 1. des Folgemonats. Weitere Versionen legst du bewusst an, mit einem Grund. Ändert sich ein festgehaltener Wert später, zeigt die laufende Berechnung den neuen Wert und der Snapshot den alten. Bei der Taktwerk GmbH hielt der Abschluss für August 2026 einen MRR von 51.646,00 € fest. Am 04.09. wurde ein Abo mit Start im August angelegt, seitdem hat der August 51.846,00 €. Der Nachtrag beträgt +200,00 €. Details stehen unter [Snapshots](https://docs.fynn.eu/v2-finance-api/snapshots.md). ## Hinweise Hinweise (Findings) melden, wo die Berechnung eine Annahme getroffen hat oder Daten auffällig sind. Jeder Hinweis hat einen Code, eine Stufe und eine Erklärung. | Stufe | Bedeutung | | - | - | | `error` | Eine Zahl ist voraussichtlich falsch. | | `warning` | Die Daten sollten geprüft werden, die Zahl folgt einer festen Regel. | | `info` | Zur Kenntnis, die Zahl ist korrekt. | Die Liste lässt sich nach `severity`, `code`, `customerId` und `month` filtern und ist seitenweise abrufbar (25 je Seite, höchstens 200). ```bash theme={null} curl "https://coreapi.io/api/analytics/mrr-financials/findings?code=BILLED_VS_CONTRACT_DIFF&month=2026-07" \ -H "Authorization: Bearer api_DEIN_TOKEN" ``` Im Beispiel ist `catalog` auf drei der Codes gekürzt: ```json theme={null} { "data": [ { "id": "3f0b6d2e-8a41-5c77-9e20-1d4c7a9b5e33", "code": "BILLED_VS_CONTRACT_DIFF", "codeLabel": "Abrechnung weicht vom Vertrag ab", "severity": "warning", "message": "The recurring amount billed differs from the contract contribution in the listed months.", "entityType": "subscription_item", "entityId": "0199c0de-0000-7000-8000-d00000033002", "monthStart": "2026-07-01T00:00:00+00:00", "customer": { "id": "0199c0de-0000-7000-8000-c00000000033", "number": "K-10033", "name": "Eichenhof Senioren GmbH" }, "subscriptionId": "0199c0de-0000-7000-8000-b00000000033", "details": { "currency": "EUR", "months": [ "2026-07" ], "billed": "298.00", "expected": "149.00", "difference": "149.00", "invoiceLines": 1, "causes": { "2026-07": "price_mismatch" }, "byMonth": { "2026-07": { "expected": "149.00", "billed": "298.00", "difference": "149.00" } } } } ], "meta": { "page": 1, "pageSize": 25, "total": 1, "sum": null, "asOf": "2026-10-01T04:00:00+00:00" }, "counts": { "error": 0, "warning": 6, "info": 9 }, "catalog": [ { "code": "BILLED_VS_CONTRACT_DIFF", "label": "Abrechnung weicht vom Vertrag ab", "explanation": "Der MRR folgt dem Vertrag. Abweichende Rechnungsbeträge ändern ihn nicht." }, { "code": "NOT_BILLED", "label": "Nicht abgerechnet", "explanation": "Für vergangene Vertragsmonate gibt es weder eine Rechnung noch eine offene Abrechnungsposition, deshalb rechnet auch der nächste Lauf sie nicht ab. Du kannst die Monate abrechnen oder gutschreiben." }, { "code": "FORECAST_DUPLICATE", "label": "Doppelte Prognose-Rechnung", "explanation": "Die Abrechnungsprognose enthält dieselbe Rechnung zweimal, mit gleichem Zeitraum und Betrag. Die Rechnungsprognose zählt sie einmal." } ] } ``` `codeLabel` ist der deutsche Name des Codes. `counts` zählt alle Hinweise ohne Filter. `catalog` enthält jeden Code mit deutschem Namen und der Annahme, die die Berechnung für ihn trifft. Diesen Katalog drucken auch die Excel-Bücher. `GET /api/analytics/mrr-financials/findings/{id}` liefert einen Hinweis mit seiner vollständigen Erklärung: die betroffenen Datensätze, die Fakten, und bei `BILLED_VS_CONTRACT_DIFF` jeden geprüften Monat mit Vertrag, Abrechnung, Toleranz und den Rechnungspositionen. Drei Codes betreffen die Abrechnung, nicht den Vertrag: | Code | Name | Bedeutung | | - | - | - | | `NOT_BILLED` | Nicht abgerechnet | Für vergangene Vertragsmonate gibt es weder eine Rechnung noch eine offene Abrechnungsposition. Auch der nächste Lauf rechnet sie nicht ab. | | `NOT_BILLED_NO_SCHEDULE` | Wird nicht abgerechnet | Das Abo hat keinen Zeitplan, die Organisation rechnet aber über Zeitpläne ab. | | `FORECAST_DUPLICATE` | Doppelte Prognose-Rechnung | Die Abrechnungsprognose enthält dieselbe Rechnung zweimal. Die Rechnungsprognose zählt sie einmal. | Vier Codes betreffen offene Posten und Guthaben eines Kunden: | Code | Name | Bedeutung | | - | - | - | | `OPEN_ITEMS_CANCEL_OUT` | Offene Posten gleichen sich aus | Offene Rechnungen und offene Gutschriften des Kunden gleichen sich aus. Das Kundenkonto steht auf 0,00. | | `EXCESS_CUSTOMER_BALANCE` | Guthaben höher als offene Belege | Das Kundenguthaben ist höher als die offenen Rechnungen des Kunden. | | `INVOICE_DOUBLE_COVERED` | Rechnung doppelt gedeckt | Zahlungen und Gutschriften der Rechnung sind zusammen höher als ihr Bruttobetrag. Der Mehrbetrag zählt als Guthaben an Kunden. | | `CANCELLATION_WITH_PAYMENT` | Storno mit Zahlung | Die Rechnung ist storniert und hat trotzdem eine Zahlung. Der Betrag zählt als Guthaben an Kunden. | > [!NOTE] > > Die App nutzt einen weiteren Endpunkt, der nicht Teil der öffentlichen API ist: das Anstoßen einer Neuberechnung (`/api/analytics/mrr-financials/rebuild`). Er kann sich ohne Ankündigung ändern. Die Zahlen werden ohnehin stündlich neu berechnet. ## Weiter > **[Datensätze](https://docs.fynn.eu/v2-finance-api/datasets.md)** > > Die Datensätze der vier Berichtsseiten und die MRR-Tabelle. > **[Drill-downs](https://docs.fynn.eu/v2-finance-api/drill-downs.md)** > > Die Zeilen hinter jeder Zelle. > **[Snapshots](https://docs.fynn.eu/v2-finance-api/snapshots.md)** > > Monatsabschlüsse, Versionen und Nachträge. > **[Definitionen](https://docs.fynn.eu/v2-finance-api/definitions.md)** > > Der versionierte Katalog aller Kennzahlen und das Glossar.