Diese Anleitung führt Sie durch das minimale Setup — von der Anmeldung bis zum ersten DR mit zugewiesenem Preis. Das schaffen Sie in 10 Minuten.

Jeden Schritt können Sie über das Dashboard oder direkt über die API ausführen — ganz wie Sie möchten.

Übersicht

1. Anmeldung
2. Preisliste + Version + Positionen erstellen
3. Pricing Rule erstellen
4. DR senden
5. Abrechnungsübersicht abrufen

Schritt 1 — Anmeldung

Dashboard: Melden Sie sich unter /dashboard mit Ihren Zugangsdaten an.

API:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "ihr_login",
  "password": "ihr_passwort"
}

Die Antwort enthält einen token. Fügen Sie ihn jedem weiteren Request hinzu:

Authorization: Bearer <token>

Schritt 2 — Preisliste, Version und Positionen

Eine Preisliste teilt dem System mit, wie viel ein bestimmter Datensatztyp kostet. Die Struktur hat drei Ebenen: Preisliste → Version → Positionen.

2a — Preisliste erstellen

Dashboard: Bereich Preislisten → Preisliste hinzufügen.

API:

POST /api/v1/price-lists
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Standard-Preisliste",
  "currency": "EUR"
}

Antwort: { "id": "<preislisten_id>" } — speichern Sie diese.

2b — Preislistenversion erstellen

Eine Version legt fest, ab wann Preise gelten. Sie muss is_active: true haben, damit sie verwendet wird.

Dashboard: Preisliste öffnen → Reiter Versionen → Version hinzufügen.

API:

POST /api/v1/price-lists/<preislisten_id>/versions
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "v1",
  "valid_from": "2024-01-01T00:00:00Z",
  "is_active": true
}

Antwort: { "id": "<versions_id>" } — speichern Sie diese.

2c — Preislistenposition hinzufügen

Eine Position sagt: „Für Code VOICE_CZ berechne 0,06 € pro Einheit."

Dashboard: Version öffnen → Position hinzufügen.

API:

POST /api/v1/price-lists/versions/<versions_id>/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "VOICE_CZ",
  "name": "Sprachanruf CZ",
  "price": 0.06,
  "currency": "EUR",
  "unit": "Minute"
}

Der Wert code muss exakt mit dem Feld code im DR übereinstimmen, den Sie in Schritt 4 senden.

Schritt 3 — Pricing Rule

Eine Pricing Rule verknüpft die Preisliste mit Ihren Kunden. Ohne Rule weiß das System nicht, welche Preisliste es verwenden soll.

Das folgende Setup wendet die Preisliste auf alle Ihre Kunden an.

Dashboard: Bereich Pricing Rules → Regel hinzufügen, Preisliste auswählen.

API:

POST /api/v1/pricing-rules
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Standardregel",
  "code": "RULE_DEFAULT",
  "price_list_id": "<preislisten_id>",
  "priority": 10,
  "is_active": true
}

Eine Rule ohne customer_id oder group_id gilt für alle Kunden. Um eine bestimmte Gruppe anzusprechen, fügen Sie "group_id": "<group_id>" hinzu.

Schritt 4 — DR senden

Jetzt senden Sie den ersten Datensatz. Verwenden Sie "ondemand": true für sofortige Bewertung.

Kunden müssen nicht im Voraus angelegt werden. Geben Sie einfach eine beliebige Kennung in customer_external_id an — der Kunde wird beim ersten Datensatz automatisch erstellt.

POST /api/v1/dr
Authorization: Bearer <token>
Content-Type: application/json

{
  "ondemand": true,
  "records": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "time_from": "2024-06-15T10:00:00Z",
      "customer_external_id": "CUST-001"
    }
  ]
}

Antwort: { "inserted": 1, "ids": ["<dr_id>"] }

Was im Hintergrund passiert ist:

• Kunde CUST-001 wurde automatisch erstellt (keine persönlichen Daten erforderlich)
• Das System fand die Pricing Rule → Preislistenversion → Position VOICE_CZ
• Berechneter Preis: 10 × 0,06 = 0,60 €
• DR gespeichert mit Status rated

Schritt 5 — Abrechnungsübersicht

Rechnungsunterlagen für einen beliebigen Zeitraum erhalten Sie mit einem einzigen Aufruf.

Dashboard: Bereich Billing → Zeitraum festlegen → Übersicht anzeigen.

API:

POST /api/v1/dr/billing
Authorization: Bearer <token>
Content-Type: application/json

{
  "time_from": "2024-06-01T00:00:00Z",
  "time_to":   "2024-06-30T23:59:59Z",
  "group_by":  "code"
}

Antwort:

{
  "items": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "amount_without_vat": 0.60,
      "vat_amount": 0.00,
      "amount": 0.60,
      "currency": "EUR"
    }
  ],
  "summary": {
    "amount_without_vat": 0.60,
    "vat_amount": 0.00,
    "amount": 0.60,
    "currency": "EUR"
  }
}

Nächste Schritte

• Mehr Codes — weitere Positionen zur Preislistenversion hinzufügen (SMS_CZ, DATA_EU, …)
• Mehr Kunden — verschiedene customer_external_id-Werte verwenden; Kunden werden automatisch erstellt
• Kundensegmentierung — Kundengruppen und Rules mit group_id erstellen
• Neue Preisversion — Version mit neuem valid_from hinzufügen; historische Daten bleiben unverändert
• Trigger — automatische Gebühren bei Überschreitung von Nutzungslimits

Eine Preisliste in Billing Engine ist eine hierarchische Struktur aus Versionen und Positionen.

Struktur der Preisliste

Jede Preisliste kann mehrere Versionen haben — typischerweise ist eine aktiv, die anderen archiviert. Jede Version enthält Preispositionen, die durch einen Code identifiziert werden (z. B. VOICE_CZ, SMS_CZ).

Preisberechnung

Wenn ein Datensatz (DR) eingeht, führt das System folgende Schritte aus:

1. Über Pricing Rules wird die gültige Preislistenversion für den Kunden gefunden
2. Die Preisposition mit dem passenden Code aus dem DR wird gesucht
3. Der Preis wird berechnet: Preis = Menge × Einzelpreis

Zuweisung an Kunden

Preislisten werden Kunden nicht direkt zugewiesen. Die Verknüpfung erfolgt über:

• Groups — ein Kunde gehört zu einer Gruppe
• Pricing Rules — eine Rule legt fest: für diese Gruppe verwende diese Preisliste

Dieses Modell ermöglicht es, eine einzige Preisliste für viele Kunden zu verwenden und bei Versionswechseln nicht jeden Kunden einzeln anpassen zu müssen.

Pricing Rules bestimmen, welche Preisliste und Version für einen Datensatz angewendet werden.

Funktionsweise einer Rule

Jede Rule definiert:

• Bedingungen (conditions) — Übereinstimmungskriterien, z. B. code = "VOICE_CZ" oder quantity > 10
• Priorität — eine Zahl; höhere Priorität = Rule wird zuerst ausgewertet
• Ziel-Preisliste — welche Preisliste (und Version) bei Übereinstimmung verwendet wird

Das System durchläuft die Rules von der höchsten Priorität und wendet die erste passende an.

Bedingungsoperatoren

Bedingungen unterstützen die Operatoren: eq, ne, gt, gte, lt, lte, like, in.

{ "code": { "op": "eq", "value": "VOICE_CZ" },
  "quantity": { "op": "gt", "value": 0 } }

Trigger — ein spezieller Regeltyp

Trigger erweitern Rules um automatisierte Aktionen. Sie werden ausgelöst, wenn:

• Ein einzelner DR einen Grenzwert überschreitet (conditions)
• Eine Aggregationsbedingung über einen Zeitraum erfüllt ist — z. B. SUM(quantity) > 100 (aggregate_conditions)

Ein Trigger kann eine Benachrichtigung senden oder eine Gebühr zur Abrechnung hinzufügen.