Gruppenlogik / Bestellungen für mehrere Benutzer

1. Einleitung – onOffice Strukturen und warum Gruppenfähigkeit wichtig ist

Diese Seite beschreibt die technische Umsetzung der Gruppenfähigkeit im onOffice Marketplace. Sie zeigt auf, wie Sie die Strukturen von Maklerunternehmen in Ihrem Service abbilden und Gruppenkäufe (Pakete/Abonnements) optimal verwalten.

Eine Instanz des onOffice-CRMs wird als Mandant bezeichnet. Diese Mandanten unterscheiden sich stark in ihrer Struktur: Während es Einzelmakler gibt, bilden größere Maklerfirmen ihre verschiedenen Standorte in onOffice enterprise häufig als sogenannte Bürogruppen ab.

Ihr Service sollte diese unterschiedlichen Strukturen berücksichtigen. Für Einzelkäufe (z. B. die Bestellung eines einzelnen Grundrisses) spielt die Gruppenstruktur keine große Rolle. Bieten Sie jedoch Abonnements oder Paketkäufe mit Kontingenten an, ist die Gruppenlogik essenziell. 

  • Beispiel 1: Wenn ein Kunde ein Paket von 50 Immobilienbewertungen kauft, sollte dieses Kontingent für den gesamten Mandanten oder eine bestimmte Bürogruppe nutzbar sein, da ein Einzelnutzer dieses Volumen oft nicht allein ausschöpft. 
  • Beispiel 2: Ein Abonnement für 20 3D-Rundgänge pro Monat wird von einem einzelnen Makler selten aufgebraucht; er möchte dieses Kontingent mit seinen Team-Kollegen teilen.

Sie sollten daher in Ihrem Service bei Abos / Paketkäufen die Möglichkeit anbieten, Käufe für den gesamten Mandanten, für einzelne Bürogruppen und einzelne User durchzuführen und die entsprechend gebuchten Kontingente korrekt in Ihrem Service verarbeiten.

Marketplace - Verbrauch in Nutzergruppen

2. onOffice als „Single Source of Truth“ (Struktur-Mapping)

Um den administrativen Aufwand auf Ihrer Seite so gering wie möglich zu halten, sollten Sie keine eigene Benutzer- oder Gruppenverwaltung in Ihrem Service bauen. Alles entsteht implizit aus den Parametern, die onOffice beim Aufruf Ihrer Iframe-URL (Service-URL) automatisch an Sie übergibt. Folgende Parameter / Informationen erhalten Sie immer: 
  • Organisation (Mandant): Wird über die customerWebId abgebildet. Die Mandanten-ID wird Ihnen bereits bei der Freischaltung Ihres Services übermittelt.
  • Team (Bürogruppe): Wird über die groupId abgebildet. Sie wird automatisch übermittelt, wenn der Mandant Gruppenstrukturen nutzt und ein Benutzer einer Bürogruppe Ihren Service aufruft. Wenn der Mandant kein Gruppenmodul bzw. keine Gruppenstrukturen nutzt, gibt es nur die Ebenen „Mandant” und „Benutzer”. (Kauf für alle oder einzelne Benutzer)
  • User (Benutzer): Wird über die userId abgebildet. Sie wird übermittelt, wenn ein Benutzer Ihren Service aufruft.

Vollautomatische Verwaltung: Es braucht keine manuelle Verwaltung der Gruppenstrukturen auf Ihrer Seite. Wechselt z.B. ein Benutzer in onOffice seine Bürogruppe, bekommen Sie beim nächsten Aufruf Ihres Services automatisch die neue groupId übergeben und können diese Änderung in Ihrem System direkt nachziehen.

Bei größeren Kunden mit komplexen Gruppenstrukturen kommt es in der Praxis häufig vor, dass Benutzer nachträglich die Gruppe wechseln, neu hinzukommen oder aus Gruppen entfernt werden. Für Sie als Anbieter ist hierbei das technische Prinzip der vollständigen Entkopplung von Kauf-Scope (Abrechnung) und Verbrauchs-Scope (Nutzung) entscheidend:

  • Abrechnung (Kauf-Scope): Die Zahlungsabwicklung läuft komplett über MangoPay im Marketplace. Administratoren in onOffice steuern, welche Benutzer Käufe tätigen dürfen. Der Kauf eines Produkts oder Abonnements ist fest an das ursprüngliche Marktplatz-Rechnungskonto des Käufers gebunden. Wechselt ein Benutzer später die Gruppe, hat dies keine Auswirkung auf das bestehende Abonnement. Bei Abos wird unabhängig von organisatorischen Änderungen weiterhin zyklisch vom Ursprungskonto abgebucht. Sie können die Daten des Käufers oder Rechnungsempfängers über den API-Call ‚Daten des Rechnungsempfängers‘ auslesen.

  • Nutzung (Verbrauchs-Scope): Die Berechtigung zur eigentlichen Nutzung des Produkts ist dynamisch an den aktuellen Scope (z. B. die Gruppe) des Nutzers gekoppelt. Verlässt ein Benutzer eine lizenzierte Gruppe und wechselt in eine neue, verliert er den Zugriff auf die Produkte der alten Gruppe. Er kann stattdessen sofort die Produkte der neuen Gruppe nutzen – vorausgesetzt, für diese Gruppe existiert ein aktives Abonnement.

💡 Entwickler-Hinweis: Schränken Sie den Zugriff in Ihrer App-Logik nicht starr anhand historischer Kaufdaten ein, sondern prüfen Sie bei jedem App-Aufruf dynamisch über die API die aktuelle Gruppenzugehörigkeit und die dafür lizenzierten Scopes.

3. Best Practice: Kauf-Scopes und Subscription-Vererbung

Um Pakete oder Abonnements sauber abzubilden, hat sich ein Abrechnungsmodell bewährt, das Käufe in drei Scopes (Ebenen) aufteilt:
  1. Persönlich (User): Nur der kaufende User profitiert. Features, Kontigente oder Credits stehen exklusiv der übergebenen userId zur Verfügung.
  2. Team (Gruppe): Der Kauf gilt für alle User mit derselben groupId. Ein Nutzer kauft zentral ein Abo für sein Team, und alle Gruppenmitglieder nutzen den geteilten Credit-Pool, ohne selbst zahlen zu müssen. 
  3. Organisation (Mandant): Der Kauf gilt global für das gesamte Maklerunternehmen anhand der customerWebId. Jedes Mitglied des Mandanten erhält Zugriff / jeder Benutzer aus dem Mandanten kann die Stückzahl aus dem Abo / Paket verbrauchen..
Best Practises für Gruppen-Abonnements:
  • Ein Abo pro Scope: Pro Mandant, Gruppe oder Benutzer sollte standardmäßig immer nur ein einziges aktives Abonnement existieren.
  • Inhaberschaft: Die Verwaltung des Abos (Kündigung, Upgrade, Downgrade) sollte dem Benutzer vorbehalten sein, der den Kauf getätigt hat. Andere Teammitglieder können die Kontingente nutzen, besitzen jedoch keine administrativen Rechte über die Zahlungen.

Pakete und Abos mit verschiedenen Kontigenten als eigene Produkte:

Wenn Sie Ihren Kunden unterschiedliche Preismodelle anbieten möchten – beispielsweise eine Einzelplatz-Lizenz (z. B. 20 € pro Benutzer/Monat) für kleinere Teams oder ein pauschales Gruppen- bzw. Organisationspaket (z. B. eine Flatrate für 170 €/Monat) für größere Kunden –, lässt sich dies wie folgt über das System abbilden.

Da der onOffice Marketplace Preise produktbasiert verwaltet (keine dynamische Preisberechnung innerhalb eines einzelnen Produkts basierend auf der Nutzeranzahl), müssen unterschiedliche Pakete als eigenständige Produkte angelegt werden. Beispiel:

  • Produkt A: Einzelplatz-Abonnement (z. B. 20 € / Benutzer)
  • Produkt B: Gruppen-Paket (z. B. 170 € / 10 Benutzer)
  • Produkt C: Kontingent-Flatrate (500 € pauschal / alle Benutzer)

Ob Sie alle Ihre Produkte jedem Kunden pauschal anzeigen oder die Sichtbarkeit einschränken, bleibt Ihnen als Anbieter überlassen und hängt von der Komplexität Ihres Produktkatalogs ab.

Technische Ermittlung der Kundengröße (User Count) via API:
Um zu erkennen, wann ein Kunde „groß genug“ für ein Pauschalpaket ist, oder um zu validieren, welches Paket ihm in der App vorgeschlagen werden soll, können Sie die Anzahl der Benutzer im Mandanten oder in der spezifischen Gruppe direkt abfragen

  • Nutzen Sie dazu die entsprechenden Endpunkte zur Abfrage der Benutzerstruktur über die onOffice API. „Read user“ ohne Parameter liefert in der Response unter cntabsolute die Anzahl der Benutzer im Mandanten. Über „Get users“ können Sie die Anzahl der Benutzer einer Bürogruppe ermitteln, indem Sie die IDs in der Response zählen.
  • Oder bitten Sie uns, die entsprechenden Makros für die Benutzeranzahl in Ihre Service-URL einzubauen. Dann bekommen Sie diese Informationen direkt übermittelt.
  • Über Ihre eigene App-Logik können Sie die so ermittelte Benutzeranzahl auslesen und dem Kunden dynamisch das passende Produkt (z. B. das optimierte 170-€-Paket ab einer bestimmten Teamgröße) im Marketplace vorschlagen.

4. API-Calls zur Abfrage von Gruppen, Benutzern und Mandanteninformationen

Um tiefere Informationen über die Gruppenstrukturen eines Mandanten abzufragen, können Sie die onOffice-API nutzen. Folgende Calls sind relevant:

Gruppen abfragen (Get groups)

Mit der API-Ressource groups können Sie sich die vorhandenen Gruppen ausgeben lassen.

  • Filter: Nutzen Sie den Parameter "groupfilter": "officeGroups", um die Ausgabe strikt auf die relevanten Bürogruppen zu beschränken, da dies die am häufigsten genutzte Gruppenstruktur ist.
  • Rückgabewerte: Die Response liefert wichtige Arrays:
    • userIds: Alle IDs der Benutzer, die dieser Gruppe angehören.
    • leaders: Die User-IDs der definierten Gruppenleiter.
    • groupType: Der Typ der Gruppe (z. B. GroupOffice für Bürogruppen oder GroupRegion für Regionengruppen).

Benutzer einer Gruppe abfragen (Get users)

Mit der API-Ressource users können Sie gezielt alle verknüpften Nutzer einer spezifischen Gruppe ermitteln, beispielsweise um Team-Mitgliederlisten intern aktuell zu halten.
  • Filter: Nutzen Sie den Parameter "userfilter": "byGroupId" und übergeben Sie zusätzlich die groupId, um nur die Benutzer dieser speziellen Gruppe auszulesen. 

Benutzerinformationen abfragen (Read User)

Für detaillierte Informationen zu einzelnen Benutzern steht Ihnen zudem der API-Call Read user zur Verfügung.

Benutzerphotos abfragen (Read User Photo)

Wenn Sie in Ihrem Service Benutzerfotos anzeigen möchten, nutzen Sie diesen Call.

Mandanten bzw. Gruppeninformationen abfragen (Read Imprint)

Um die Mandanten- bzw. Gruppendaten eines bestimmten Benutzers abzurufen, nutzen Sie diesen Call.

Informationen zu Corporate Identity (CI) abfragen (Read Basis Settings)

Um Informationen zur Corporate Identity wie Logo, Unternehmensfarben oder Claim des Mandanten abzurufen, nutzen Sie diesen Call.

5. Optionale Service-URL-Makros für Gruppen

Falls Sie für Ihren Service keine aufwändigen API-Calls programmieren möchten, können Sie uns beim Onboarding darüber informieren, dass Sie spezifische Gruppen-Makros in Ihrer Service-URL benötigen. onOffice injiziert dann zur Laufzeit konkrete Werte der Bürogruppe in Ihre URL:
  • _OfficeGroupUserStatus: Gibt an, ob der aufrufende Nutzer Gruppenleiterrechte in seiner aktuellen Bürogruppe besitzt (liefert 1 für Gruppenleiter, ansonsten 0).
  • _CntUserOfficeGroup: Liefert die exakte Anzahl der Benutzer, die sich in dieser spezifischen Bürogruppe befinden.
  • _CntUserMdt: Liefert die Anzahl Benutzer im Mandanten.
  • _OfficeGroupName: Übergibt den Klartext-Namen der entsprechenden Bürogruppe.

6. Best practise Rechte / Daten im Service

Die Benutzerrechte in onOffice legen fest, welche Daten der Benutzer lesen und schreiben kann. Nur diese Daten können Sie in Ihrem Service für den aktuellen Benutzer abfragen bzw. bearbeiten. D.h. onOffice steuert, wer was sehen darf. Daher ist es notwendig, dass Sie bei jedem API-Aufruf den Parameter „extendedclaim” mitschicken, um zu verifizieren, dass der Benutzerkontext beachtet wird.

Achten Sie darauf, dem aktuellen Benutzer nur die für Ihren Service benötigten Daten anzuzeigen. Bei Immobilienservices ist es beispielsweise meist sinnvoll, nur die Immobilien abzurufen, bei denen der Benutzer Betreuer der Immobilie ist und die Immobilie den Status „aktiv” hat.

Bei Unklarheiten oder Fragen wenden Sie sich an Ihren Ansprechpartner bei onOffice an oder bei technischen Fragen an unseren Marketplace-Support unter marketplace-dev@onoffice.de

This post is also available in: Englisch