Abrechnungsintervall und Kalkulation

Mit dieser Schnittstelle hinterlegen Ihre eigenen Werkzeuge je Anlage, wie oft Sie den Kunden abrechnen – monatlich, quartalsweise oder jährlich –, und lassen sich Einkaufs- und Verkaufspreise für genau diesen Zeitraum berechnen. Konsole, Skript und KI-Assistent erhalten dieselben Zahlen, weil der Controller den Zeitraum selbst rechnet. Diese Seite ist die Referenz für Integratoren und für alle, die einen KI-Assistenten an den Controller anbinden.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Erweiterungen erfolgen additiv: neue Felder und neue Werte kommen hinzu, bestehende bleiben.

Grundlagen

Basis-URL: https://cmp.sf-app.de/api/v1. Betreiben Sie den Controller selbst, setzen Sie Ihren eigenen Host ein.
Authentifizierung: ein Konto des Controllers, für Skripte per HTTP Basic mit E-Mail-Adresse und Passwort eines lokalen Kontos – wie unter Aufmerksamkeit beschrieben.
Rollen: Kundenabrechnung steht Partnerzugängen zur Verfügung, die als STARFACE-Partner eingetragen sind. Lesen und Schreiben dürfen Inhaber und Administratoren; alle anderen Rollen erhalten 403.
Je Partnerzugang: Das Abrechnungsintervall gilt für Ihren Partnerzugang, wie Ihre Preislisten. Betreuen zwei Partner dieselbe Anlage, hinterlegt jeder sein eigenes Intervall und sieht das des anderen nicht.
Format: JSON, UTF-8. Kalendertage als JJJJ-MM-TT, Monate als JJJJ-MM, Beträge in Euro netto.

Werte für den Zeitraum

Wert	Zeitraum	In der Konsole
`MONTH`	1 Monat	monatlich
`QUARTER`	3 Monate	quartalsweise
`YEAR`	12 Monate	jährlich

Groß- und Kleinschreibung spielt keine Rolle; monthly, quarterly und yearly werden ebenfalls angenommen.

Abrechnungsintervall

Lesen

Das Intervall steht an zwei Stellen:

in der Anlagenliste GET /api/v1/sites im Feld billingInterval jeder Anlage (MONTH, QUARTER, YEAR oder null),
in den Preislisten-Zuordnungen:

GET /api/v1/billing/assignments?siteIds={siteId},{siteId}

Antwort 200
[
  {
    "siteId": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
    "priceListId": "9a1c2f60-0d1e-4c1b-9a51-6f2f0e7a1b11",
    "priceListName": "Partnerpreise 2026",
    "sbcService": false,
    "fluxpunktPriceListId": null,
    "fluxpunktPriceListName": null,
    "billingInterval": "QUARTER"
  }
]

Eine Anlage ohne Preisliste und ohne Intervall fehlt in der Antwort.

Setzen oder entfernen

PUT /api/v1/billing/intervals
Content-Type: application/json

Feld	Pflicht	Beschreibung
`siteIds`	ja	Kennungen der Anlagen (`id` aus der Anlagenliste).
`interval`	nein	`MONTH`, `QUARTER` oder `YEAR`. `null` oder leer entfernt das Intervall.

Drei Anlagen auf quartalsweise stellen
curl -s -u "buchhaltung@partner.de:••••••" -X PUT -H "Content-Type: application/json" \
  -d '{"siteIds": ["1458d78f-6e4c-4cf2-b524-888b0c3caddf", "5b0c…", "77e1…"], "interval": "QUARTER"}' \
  https://cmp.sf-app.de/api/v1/billing/intervals

Die Antwort ist die Liste der Zuordnungen wie beim Lesen. Der Controller prüft nicht, ob die Anlage eine Cloud-Anlage ist oder einen laufenden Updatevertrag hat; die Konsole bietet das Feld nur dort an. Ein gespeicherter Wert bleibt erhalten, wenn ein Vertrag endet.

Anwendungsbeispiel

Ihre Warenwirtschaft kennt den Zahlungsrhythmus jedes Vertrags. Ein nächtlicher Abgleich überträgt ihn als Abrechnungsintervall in den Controller. Öffnet ein Kollege danach die Kalkulation einer Anlage, steht dort sofort der Zeitraum, in dem der Kunde bezahlt.

Fehler

Fehlerantworten tragen error (Code) und message (deutscher Text).

Status	`error`	Bedeutung
`400`	`no_sites`	`siteIds` fehlt oder ist leer.
`400`	`interval_invalid`	`interval` ist kein gültiger Wert.
`401`	–	Nicht angemeldet oder falsches Passwort.
`403`	`forbidden`	Rolle unter Administrator, oder der Partnerzugang ist kein STARFACE-Partner.
`404`	`not_found`	Mindestens eine Anlage ist für Ihren Partnerzugang nicht sichtbar. Nichts wurde geändert.

Kalkulation einer Anlage

GET /api/v1/billing/sites/{siteId}/calculation?scope={scope}&period={period}

Parameter	Ort	Pflicht	Beschreibung
`siteId`	Pfad	ja	Kennung der Anlage.
`scope`	Query	nein	`monthly` (Standard): laufende Gebühren – Cloud-Abo, MS Teams, SBC, Miete. `update`: Updategebühren für Appliance und VM.
`period`	Query	nein	`month`, `quarter` oder `year`. Ohne Angabe: ein Monat bei `monthly`, ein Jahr bei `update`.
`month`	Query	nein	Erster Monat des Zeitraums, `JJJJ-MM`. Nur bei `monthly`; bei `update` nur der Januar des Folgejahres.

Welcher Zeitraum berechnet wird:

`scope`	`period`	Zeitraum
`monthly`	`month`	der laufende Monat (oder `month`)
`monthly`	`quarter`	das laufende Kalenderquartal (oder drei Monate ab `month`)
`monthly`	`year`	zwölf Monate ab dem laufenden Monat (oder ab `month`)
`update`	`year`	Januar bis Dezember des Folgejahres
`update`	`month`, `quarter`	bei laufendem Updatevertrag der laufende Monat bzw. das laufende Quartal, sonst ab Januar des Folgejahres

Ohne laufenden Updatevertrag enthält update zusätzlich die einmaligen Positionen für den Abschluss: die vollen Monate seit Aktivierung bzw. seit Ablauf des früheren Vertrags mit Faktor 1,2 und den Rest des laufenden Jahres (group = ONCE). Über mehrere Monate zählt bei Cloud-Anlagen der Höchstwert der angelegten Benutzer im ganzen Zeitraum für jeden Monat. Reicht der Zeitraum über den laufenden Monat hinaus, steht dazu eine Warnung in warnings.

Quartal einer Cloud-Anlage
curl -s -u "buchhaltung@partner.de:••••••" \
  "https://cmp.sf-app.de/api/v1/billing/sites/1458d78f-6e4c-4cf2-b524-888b0c3caddf/calculation?scope=monthly&period=quarter"

Antwort 200 (gekürzt)
{
  "ref": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
  "error": null,
  "calculation": {
    "siteId": "1458d78f-6e4c-4cf2-b524-888b0c3caddf",
    "siteName": "Muster GmbH – Zentrale",
    "platform": "CLOUD",
    "priceListName": "Partnerpreise 2026",
    "period": "QUARTER",
    "billingInterval": "QUARTER",
    "result": {
      "scope": "MONTHLY",
      "from": "2026-10-01",
      "to": "2026-12-31",
      "positions": [
        {
          "articleNo": "2300001001",
          "label": "STARFACE CLOUD Userlizenz",
          "basis": "Höchstwert im Zeitraum, angelegte User 35, abzüglich 3 inklusive, Zeitraum 10/2026–12/2026",
          "quantity": 32,
          "months": 3,
          "factor": 1,
          "ekUnit": 5.52,
          "vkUnit": 6.90,
          "ek": 529.92,
          "vk": 662.40,
          "group": "RECURRING"
        }
      ],
      "excluded": [],
      "unmatched": [],
      "warnings": [],
      "totals": {"ek": 529.92, "vk": 662.40, "margin": 132.48},
      "subtotals": [{"group": "RECURRING", "from": "2026-10-01", "to": "2026-12-31", "ek": 529.92, "vk": 662.40, "margin": 132.48}],
      "agreement": null
    }
  }
}

Feld	Beschreibung
`error`	Grund, warum die Anlage nicht berechnet wurde (z. B. keine Preisliste zugewiesen); dann ist `calculation` `null`.
`calculation.period`	Der berechnete Zeitraum.
`calculation.billingInterval`	Das hinterlegte Abrechnungsintervall, sonst `null`.
`result.positions[]`	Je Artikel Menge, Monate, Faktor, Einzel- und Gesamtpreise; `basis` erklärt die Menge. Jede Position wird auf den Cent gerundet, die Summen über die gerundeten Positionen gebildet.
`result.excluded[]`	Lizenzen, die nicht berechnet werden, mit Grund.
`result.unmatched[]`	Lizenzen ohne Zuordnung zu einem Artikel – bitte prüfen.
`result.subtotals[]`	Summen je `group` (`ONCE`, `RECURRING`) mit Zeitraum.
`result.agreement`	Bei `update`: Stand des Updatevertrags (`ACTIVE`, `CANCELLED`, `ENDED`, `NONE`) mit `endsAt`.

Anwendungsbeispiel

Zum Quartalsbeginn erzeugt Ihr Fakturierungsskript die Rechnungen für alle Kunden mit quartalsweiser Abrechnung: Es liest die Anlagenliste, wählt die Anlagen mit billingInterval = "QUARTER" und übernimmt für jede die Positionen aus der Kalkulation mit period=quarter als Rechnungszeilen.

Fehler

Status	`error`	Bedeutung
`400`	`scope_invalid`	`scope` ist nicht `monthly` oder `update`.
`400`	`period_invalid`	`period` ist kein gültiger Wert.
`400`	`month_invalid`	`month` hat nicht die Form `JJJJ-MM`.
`400`	`month_not_applicable`	Bei `scope=update` ist nur der Januar des Folgejahres zulässig.
`401`	–	Nicht angemeldet oder falsches Passwort.
`403`	`forbidden`	Rolle unter Administrator, oder der Partnerzugang ist kein STARFACE-Partner.
`404`	`not_found`	Die Anlage ist für Ihren Partnerzugang nicht sichtbar.
`409`	`billing_unavailable`	Es ist kein STARFACE-Katalog aktiv.

Für KI-Assistenten (MCP)

Werkzeug	Neu in diesem Zusammenhang	Benötigte Stufe
`billing_calculation`	Argument `period` (`month`, `quarter`, `year`). Ohne `period` gilt je Anlage das hinterlegte Abrechnungsintervall, ohne Intervall ein Monat. Jede Anlage im Ergebnis nennt `period` und `billingInterval`. Das ältere `yearly=true` entspricht `period=year`.	Lesen
`billing_site_price_list`	`get` liefert je Anlage `billingInterval` (`month`, `quarter`, `year` oder `null`). `set` nimmt `billingInterval` an (`none` entfernt es), auch ohne Preisliste.	`get`: Lesen; `set` mit `mode=apply`: Lesen + Schreiben
`fleet_list_sites`	Je Anlage `billingInterval`.	Lesen

Im MCP schreibt der Controller die Werte klein (quarter), in der REST-Schnittstelle groß (QUARTER). Schreibende Aufrufe laufen zuerst als Probelauf; erst mode=apply speichert.

billing_site_price_list: Intervall setzen
{
  "operation": "set",
  "sites": ["K8P3F-8GQBF-AT7FT-XK6ZV"],
  "billingInterval": "quarter",
  "mode": "apply"
}

Anwendungsbeispiel

Sie fragen Ihren Assistenten: „Was rechne ich bei Muster für das vierte Quartal ab?“ Der Assistent ruft billing_calculation ohne period auf. Weil für Muster quartalsweise hinterlegt ist, erhält er Oktober bis Dezember und nennt Ihnen EK, VK und Marge.

Grenzen

Grenze	Wert
Anlagen je MCP-Aufruf	100 (auch per Serverlizenzschlüssel)
Anlagen je `PUT /billing/intervals`	ohne feste Grenze; alle oder keine werden geändert

Grundlagen​

Werte für den Zeitraum​

Abrechnungsintervall​

Lesen​

Setzen oder entfernen​

Fehler​

Kalkulation einer Anlage​

Fehler​

Für KI-Assistenten (MCP)​

Grenzen​

Grundlagen

Werte für den Zeitraum

Abrechnungsintervall

Lesen

Setzen oder entfernen

Fehler

Kalkulation einer Anlage

Fehler

Für KI-Assistenten (MCP)

Grenzen