Kapitel 1: Preislisten

Was ist eine Preisliste?

Preislisten bilden die Grundlage jeder Abrechnungsoperation in BillingEngine. Es sind strukturierte Preiskataloge, die genau definieren, was jede Art von Dienst kostet — auch rückwirkend über die Zeit. Ohne eine korrekt konfigurierte Preisliste kann die Engine keinen einzigen Datensatz bewerten.

Eine Preisliste ist ein benannter Container, der Versionen und deren Preispositionen gruppiert. Er enthält selbst keine konkreten Tarife — diese sind in den Versionen gespeichert. Diese Architektur erlaubt Preisänderungen, ohne die historische Konsistenz zu beeinträchtigen.

Die Hierarchie sieht so aus:

• Preisliste — übergeordnetes Objekt mit Name, Währung und Beschreibung
  • Version — Preissatz gültig ab einem bestimmten Datum (valid_from)
    • Positionen — konkrete Tarife per code

Dank dieser dreischichtigen Struktur merkt sich BillingEngine, welcher Tarif zum Zeitpunkt der Verarbeitung jedes Datensatzes galt. Historische Datensätze bleiben auch nach Preisänderungen konsistent.

Erstellen einer Preisliste

Erstellen Sie eine neue Preisliste über die REST-API:

POST /api/v1/price-lists
Content-Type: application/json

{
  "name": "Standard B2B Tarif",
  "currency": "EUR",
  "description": "Preisliste für Geschäftskunden"
}

Die Antwort enthält eine id, die Sie beim Erstellen von Versionen und beim Referenzieren in Preisregeln benötigen. Das Feld currency legt die Standardwährung der Preisliste fest (Standard: CZK). Wählen Sie einen aussagekräftigen Namen — "Standard B2B Tarif 2026" ist besser als "tariff_v3".

Preislistenversionen

Jede Preisliste kann mehrere Versionen haben. Die Engine wählt automatisch die Version aus, deren valid_from am spätesten ist und den Verarbeitungszeitpunkt des Datensatzes nicht überschreitet. Versionen benötigen kein Enddatum — die Engine wechselt automatisch zur neueren Version ab deren valid_from-Datum.

POST /api/v1/price-lists/{id}/versions
Content-Type: application/json

{
  "version": "Q1 2026",
  "valid_from": "2026-01-01",
  "description": "Tarife gültig ab 1. Januar 2026"
}

Das Feld version ist der Versionsbezeichner (z.B. "Q1 2026" oder "v2.0"). Wenn Sie eine Version mit späterem valid_from erstellen, wechselt die Engine automatisch ab diesem Datum auf sie.

Wichtig: Stellen Sie sicher, dass die Preisliste immer mindestens eine Version hat, deren valid_from den ältesten zu bewertenden Datensatz nicht überschreitet. Datensätze ohne passende Version werden als fehlerhaft markiert.

Preislistenpositionen

Positionen definieren die tatsächlichen Tarife. Jede Position ist an einen bestimmten Code (code) gebunden und definiert einen Preis (price):

POST /api/v1/price-lists/versions/{versionId}/items
Content-Type: application/json

{
  "code": "SMS",
  "price": 0.085,
  "unit": "Stk",
  "vat_rate": 19
}

Bei der Verarbeitung eines Datensatzes sucht die Engine nach einer Position mit dem entsprechenden code und berechnet den Preis als quantity × price × (1 - discount / 100). Wenn keine Position für diesen Code existiert, kann der Datensatz nicht bewertet werden und wird als fehlerhaft markiert.

Eine typische Preisliste für einen Telekommunikationsanbieter:

Die Währung wird auf Ebene der gesamten Preisliste festgelegt (Feld currency beim Erstellen).

Verbindung zu Kunden über Regeln

Eine Preisliste wird Kunden nicht direkt zugewiesen — das erfolgt über Preisregeln (pricing rules). Eine Regel besagt: “Für Kunden in Gruppe X verwende Preisliste Y.” Diese Trennung ermöglicht die gemeinsame Nutzung einer Preisliste zwischen mehreren Kundengruppen und die Aktualisierung von Preisen an einer Stelle.

Preisregeln werden ausführlich in Kapitel 2 behandelt.

Versionierung als Prüfungsgarantie

Finanzsysteme müssen prüfbar sein. BillingEngine löst dies, indem jeder bewertete Datensatz einen Verweis auf die genaue Preislistenversion enthält, die bei der Berechnung verwendet wurde. Dieser Verweis ist unveränderlich — der Datensatz trägt ihn ab dem Moment seiner Erstellung und kann nicht rückwirkend überschrieben werden.

Selbst wenn Sie den SMS-Preis durch Erstellen einer neuen Version mit späterem valid_from erhöhen, bleiben alle zuvor verarbeiteten Datensätze mit dem ursprünglichen Tarif bewertet. Ihre historischen Berichte sind immer korrekt, Rechnungen sind exakt und Streitigkeiten sind nachweisbar.

Verwaltung von Preislisten im Laufe der Zeit

Ein typischer Preislisten-Lebenszyklus in einer Produktionsumgebung:

1. Januar — Preisliste “Standardtarif 2026” mit Version valid_from: "2026-01-01" erstellen
2. Februar — Vertriebsteam genehmigt Preiserhöhung ab April
3. März — neue Version mit valid_from: "2026-04-01" und aktualisierten Tarifen erstellen
4. April — Engine wechselt automatisch zur neuen Version ohne manuellen Eingriff
5. Jeden Monat — Abrechnungs-Endpoint liefert korrekte Summen unabhängig von Preisänderungen

Best Practices

Versionen klar benennen. "Q2 2026 — SMS Preis +15%" ist besser als "version4". Namen sollten in drei Jahren noch Sinn ergeben.

Aktive Versionen nicht bearbeiten. Wenn Sie Preise ändern möchten, erstellen Sie eine neue Version mit späterem valid_from. Die Bearbeitung einer aktiven Version kann die Konsistenz historischer Berechnungen beeinträchtigen.

Im Sandbox testen. Überprüfen Sie vor der Bereitstellung einer neuen Version mit Testdatensätzen, dass die Engine korrekte Preise zurückgibt.

Grund für Änderungen dokumentieren. Das description-Feld einer Version dient genau diesem Zweck. Schreiben Sie, warum die Preisänderung erfolgte.

Datumsabdeckung prüfen. Stellen Sie sicher, dass die früheste Version ein valid_from hat, das die ältesten zu importierenden Datensätze nicht überschreitet. Datensätze ohne gültige Version enden im Fehlerstatus.

Fazit

Preislisten sind der grundlegende Baustein von BillingEngine. Das Verständnis ihrer dreischichtigen Struktur — Liste, Version, Positionen — und des Versionierungsprinzips ist der Schlüssel zur korrekten Einrichtung des gesamten Systems. Kapitel 2 behandelt Preisregeln, die Preislisten mit Kunden verbinden und definieren, wann welche Preisliste verwendet wird.