Finanzberichte: Konzepte

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, der Taktwerk GmbH, und passen zueinander.

Zugriff

Du authentifizierst jede Anfrage mit einem API-Token deiner Organisation, wie unter Authentifizierung 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.

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 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).

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.

curl https://coreapi.io/api/analytics/mrr-financials/settings \
  -H "Authorization: Bearer api_DEIN_TOKEN"

{
  "movementScope": "customer",
  "mrrRestatementAlertShare": "0.01"
}

Mit PATCH änderst du einen oder beide Werte. Felder, die du weglässt, behalten ihren Wert.

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"}'

{
  "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:

{
  "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:

{ "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:

{
  "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:

{ "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:

{
  "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. 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.

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).

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:

{
  "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.

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

Die Datensätze der vier Berichtsseiten und die MRR-Tabelle.

Drill-downs

Die Zeilen hinter jeder Zelle.

Snapshots

Monatsabschlüsse, Versionen und Nachträge.

Definitionen

Der versionierte Katalog aller Kennzahlen und das Glossar.

Einführung

Grundlagen

Pläne

Angebote

Finanzberichte

Provisionen

Zahlungspläne

Finanzberichte: Konzepte

Zugriff

Wie die Zahlen entstehen

Vier Zahlen, vier Quellen

Konten und Ebenen

Monate, Zeitraum und Zeitzone

Der laufende Monat

Beträge, Raten und Vorzeichen

Das `meta`-Objekt

Unvollständige Rechnungsprognose

Abgebrochene Berechnung

Snapshots und Nachträge

Hinweise

Weiter

Datensätze

Drill-downs

Snapshots

Definitionen

​Zugriff

​Wie die Zahlen entstehen

​Vier Zahlen, vier Quellen

​Konten und Ebenen

​Monate, Zeitraum und Zeitzone

​Der laufende Monat

​Beträge, Raten und Vorzeichen

​Das meta-Objekt

​Unvollständige Rechnungsprognose

​Abgebrochene Berechnung

​Snapshots und Nachträge

​Hinweise

​Weiter

Datensätze

Drill-downs

Snapshots

Definitionen

Zugriff

Wie die Zahlen entstehen

Vier Zahlen, vier Quellen

Konten und Ebenen

Monate, Zeitraum und Zeitzone

Der laufende Monat

Beträge, Raten und Vorzeichen

Das `meta`-Objekt

Unvollständige Rechnungsprognose

Abgebrochene Berechnung

Snapshots und Nachträge

Hinweise

Weiter