Kapitel 4: Kunden

Kunden in BillingEngine

Ein Kunde ist die zentrale Entität, um die sich die gesamte Abrechnung in BillingEngine dreht. Jeder Datensatz (DR) muss einem bestimmten Kunden zugeordnet sein — erst dann weiß die Engine, welche Regeln und Preislisten anzuwenden sind.

Ein Kunde in BillingEngine repräsentiert Ihre Endkunden — Unternehmen, die Ihre Dienste beziehen. Verwechseln Sie diese Entität nicht mit Systembenutzern (users), die für die Anmeldung in der Administration verwendet werden.

Kundenstruktur

Ein Kunde trägt folgende Attribute:

Kunden erstellen

Erstellen Sie einen neuen Kunden über die REST-API:

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

{
  "name": "Endkunde GmbH",
  "external_id": "EXT-CU-0042",
  "tax_id": "DE123456789",
  "vat_id": "DE123456789",
  "address_street": "Musterstraße 1",
  "address_city": "Berlin",
  "address_zip": "10115",
  "address_country": "DE"
}

Die Antwort enthält nur die id des neuen Kunden:

{ "id": "uuid-des-neuen-kunden" }

Gruppen bei der Erstellung zuweisen

Über das Feld group_ids kann der Kunde direkt Gruppen zugewiesen werden:

{
  "name": "Endkunde GmbH",
  "external_id": "EXT-CU-0042",
  "group_ids": ["uuid-vip-gruppe", "uuid-promo-gruppe"]
}

Damit entfällt ein separater Gruppenaufruf.

External ID: Schlüssel zur nahtlosen Integration

External ID (external_id) ist Ihr eigener Kundenbezeichner aus CRM, ERP oder einem anderen System. Er ist beim Einreichen von Datensätzen entscheidend — ermöglicht die Identifizierung des Kunden ohne Kenntnis der internen UUID von BillingEngine:

// Beim Einreichen eines DR genügt Ihr Bezeichner:
{
  "customer_external_id": "EXT-CU-0042",
  "code": "SMS",
  "quantity": 1500,
  "time_from": "2026-03-31T14:00:00Z"
}

Der Wert external_id muss unter allen Ihren Kunden eindeutig sein.

Kundenverwaltung

GET    /api/v1/customers          # Kunden auflisten (mit Paginierung)
GET    /api/v1/customers/{id}     # Kundendetail
PUT    /api/v1/customers/{id}     # Kunden aktualisieren
DELETE /api/v1/customers/{id}     # Kunden löschen
GET    /api/v1/customers/{id}/groups  # Gruppen des Kunden

Die Aktualisierung (PUT) akzeptiert dieselben Felder wie die Erstellung, einschließlich group_ids. Das Löschen eines Kunden löscht nicht seine historischen Datensätze — diese verbleiben für Prüfzwecke in der Datenbank.

Kunden und Gruppen

Weisen Sie Kunden Gruppen entweder direkt bei der Erstellung/Aktualisierung über group_ids zu oder separat über den Gruppen-Endpoint:

POST /api/v1/groups/{groupId}/customers
Content-Type: application/json

{ "customer_id": "uuid-des-kunden" }

Gruppen des Kunden abrufen:

GET /api/v1/customers/{id}/groups

Ein Kunde kann gleichzeitig Mitglied mehrerer Gruppen sein.

Kunden-Lebenszyklus

1. Registrierung — Kunde wird in BillingEngine angelegt (manuell oder automatisch aus CRM)
2. Gruppenzuweisung — Kunde wird zu entsprechenden Segmenten hinzugefügt (möglich in Schritt 1 über group_ids)
3. Aktive Abrechnung — Kunde generiert Datensätze, Engine bewertet sie
4. Billing — am Periodenende wird eine Zusammenfassung über den Billing-Endpoint generiert
5. Segmentwechsel — Kunde wechselt in eine andere Gruppe (Preiserhöhung, Upgrade)
6. Vertragsende — aus Gruppen entfernen; entscheiden, ob löschen oder für historische Abfragen behalten

Best Practices

Immer external_id setzen. Auch wenn Sie es aktuell nicht benötigen, ist das nachträgliche Hinzufügen bei Hunderten von Kunden mühsam. Die DR-Einreichung über customer_external_id funktioniert dann sofort.

external_id nicht ändern. Nach der ersten Einstellung nicht mehr ändern — Datensätze referenzieren diesen Bezeichner. Eine Änderung führt zu Integrationsproblemen.

Abrechnungsdaten ausfüllen. tax_id, vat_id und Adressfelder sind optional, erleichtern aber die Rechnungserstellung und die Einhaltung gesetzlicher Anforderungen.

Kunden vorsichtig löschen. Historische Datensätze bleiben erhalten, aber der Verweis auf das Kundenobjekt geht verloren. Wenn Sie einen Kunden nur “deaktivieren” möchten, entfernen Sie ihn aus den Gruppen — Löschen ist nicht notwendig.

Fazit

Der Kunde ist die Schlüsselentität, die Datensätze mit Preislisten verbindet. External ID ermöglicht nahtlose Integration mit Ihren bestehenden Systemen. Kapitel 5 behandelt Datensätze — wie man sie strukturiert, einreicht und wie der gesamte Rating-Prozess abläuft.