Kapitel 5: Datensätze

Was ist ein Datensatz?

Ein Datensatz (Data Record, DR) ist die grundlegende Eingabeeinheit von BillingEngine. Er repräsentiert eine einzelne Nutzung Ihres Dienstes durch einen Kunden — das Senden einer SMS, eine Gesprächsminute, ein Megabyte übertragener Daten oder jede andere messbare Aktivität, für die Sie Ihren Kunden abrechnen möchten.

Datensätze sind die Eingabe für die Rating-Engine — den Prozess, der jedem Datensatz einen Preis basierend auf aktiven Preisregeln und den zum Zeitpunkt des Datensatzes gültigen Preislistenversionen zuweist.

Struktur eines Datensatzes

Jeder Datensatz hat folgende Felder:

code ist das zentrale Verbindungselement — die Engine verwendet es zum Nachschlagen der passenden Position in der aktiven Preislistenversion (price_list_item.code). Enthält die Preisliste diesen Code nicht, kann der Datensatz nicht bewertet werden.

Einreichen von Datensätzen

Datensätze werden als Array im Anfragekörper eingereicht, nicht als einzelne Objekte:

POST /api/v1/dr
Content-Type: application/json

{
  "records": [
    {
      "customer_external_id": "EXT-CU-0042",
      "code": "SMS",
      "quantity": 1500,
      "time_from": "2026-03-31T14:00:00Z",
      "external_id": "MY-SYSTEM-RECORD-99887"
    },
    {
      "customer_external_id": "EXT-CU-0042",
      "code": "VOICE_MIN",
      "quantity": 48,
      "time_from": "2026-03-31T14:05:00Z"
    }
  ]
}

Die maximale Batch-Größe beträgt 10.000 Datensätze (oder 5.000 bei ondemand: true).

Synchrone vs. asynchrone Verarbeitung

BillingEngine unterstützt zwei Verarbeitungsmodi:

Asynchron (Standard, ondemand: false): Datensätze werden in eine Warteschlange gestellt und im Hintergrund bewertet. Die Antwort kommt sofort mit queueId und Liste der ids:

{
  "message": "Successfully inserted 2 records",
  "queueId": "uuid-der-queue",
  "ids": ["uuid-datensatz-1", "uuid-datensatz-2"],
  "ondemand": false
}

Verarbeitungsstatus abrufen:

GET /api/v1/dr/status?month=202603&queue_id=uuid-der-queue

Antwort: { "total": 2, "by_status": { "rated": 1, "unrated": 0, "error": 1 } }

Synchron (ondemand: true): Datensätze werden sofort vor der Speicherung bewertet. Mit include_rated: true enthält die Antwort auch die Rating-Ergebnisse. Synchroner Modus eignet sich für Preisüberprüfungen, Debugging oder kleine Volumen.

Der Rating-Prozess

Jeder Datensatz durchläuft folgende Schritte:

1. Kundengruppen laden — die Engine identifiziert Gruppen für den über customer_external_id zugeordneten Kunden.

2. Anwendbare Regeln auswählen — alle aktiven Preisregeln des Partners werden geprüft. Regeln, die zum Kunden (oder seinen Gruppen) passen und deren valid_from/valid_to das time_from des Datensatzes abdeckt, werden ausgewählt.

3. Preislistenversion auswählen — für jede anwendbare Regel findet die Engine die zum time_from gültige Version.

4. Preislistenposition nachschlagen — sucht nach einer Position mit demselben code wie der Datensatz. Nicht gefunden → Regel wird übersprungen.

5. Preis berechnen — Tarifikation anwenden und Preis berechnen:

billed_qty = Tarifikation(quantity, item.tarification)
price = billed_qty × item.price × (1 - discount / 100)

6. Speichern — jede erfolgreiche Regel erzeugt einen separaten bewerteten Eintrag mit Preis, Währung, Rabatt und MwSt.-Satz.

Die Engine stoppt nicht nach der ersten übereinstimmenden Regel — sie erstellt bewertete Einträge für alle anwendbaren Regeln (typischerweise gleichzeitig cost und retail).

Tarifikation

Tarifikation ist ein Telekommunikationsmechanismus zur Rundung fakturierter Mengen. Eine Preislistenposition kann ein tarification-Feld im Format "first_block/subsequent_block" haben:

• "60/1" — erster Block 60 Sekunden, dann jede Sekunde einzeln
• "60/60" — rundet immer auf Vielfache von 60 auf

Beispiel: Tarifikation "60/60", quantity 75 → fakturierte Menge ist 120.

Datensatz-Status

Jeder eingereichte Datensatz durchläuft folgende Zustände:

Datensätze im Status error oder unrated können neu bewertet werden:

POST /api/v1/dr/re-rate
Content-Type: application/json

{ "month": "202603", "status": "error" }

Billing-Endpoint

Am Ende des Abrechnungszeitraums aggregiert der Billing-Endpoint die Preise:

POST /api/v1/dr/billing
Content-Type: application/json

{
  "time_from": "2026-03-01T00:00:00Z",
  "time_to": "2026-03-31T23:59:59Z",
  "billing_category": "retail",
  "group_by": "code"
}

Der Parameter group_by bestimmt die Aggregationsdimension: code, type, subtype oder analytic. Die Antwort enthält Summen mit MwSt.-Aufschlüsselung — ideal als Grundlage für die Rechnungserstellung.

Der Billing-Endpoint filtert nicht nach Kunde — er gibt eine Aggregation über alle Partner-Datensätze im angegebenen Zeitraum zurück.

Best Practices

Immer time_from setzen. Es ist ein Pflichtfeld. Übergeben Sie die tatsächliche Ereigniszeit, nicht die Zeit des API-Aufrufs.

external_id verwenden. Ihr eigener Datensatzbezeichner erleichtert die Suche und das Debugging.

Asynchronen Modus bevorzugen. Für Produktionsvolumen asynchron einreichen und Status über /dr/status überwachen.

error-Status überwachen. Datensätze ohne passende Regel oder Preislistenposition enden in error. Regelmäßige Prüfungen einrichten und Konfiguration entsprechend korrigieren.

Vernünftige Batch-Größen. Optimale Batch-Größe: Hunderte bis niedrige Tausende von Datensätzen.

Fazit

Datensätze sind das Herzstück von BillingEngine — alles andere existiert, um sie korrekt zu bewerten. Das Verständnis des Rating-Prozesses, der asynchronen Verarbeitung und des Billing-Endpoints gibt Ihnen ein vollständiges End-to-End-Bild des Systems. Kapitel 6 behandelt Trigger — den erweiterten Mechanismus für bedingtes Engine-Verhalten.