B2B-Firmenkonten in Magento 2: Rollen, Struktur und Freigaben

1. Was B2B-Firmenkonten in Magento 2 sind und wofür sie gedacht sind

Ein klassisches Magento-Kundenkonto bildet eine einzelne Person ab: eine E-Mail-Adresse, ein Passwort, eine Adresse. B2B-Firmenkonten lösen dieses 1:1-Modell auf und bilden stattdessen eine ganze Organisation ab, unter der beliebig viele Einkäufer mit unterschiedlichen Rollen agieren. Das Company-Modul aus dem Magento Commerce B2B-Paket stellt dafür ein eigenes Entity-Modell bereit, das über Service Contracts, deklaratives Schema und GraphQL vollständig erweiterbar ist, ohne den Kern zu verändern.

Der Business Case ist eindeutig: Ein Einzelhandelskunde kauft für sich selbst ein, ein B2B-Einkäufer kauft im Auftrag einer Firma und mit einem Budget, das jemand anderes freigeben muss. B2B-Firmenkonten bündeln deshalb mehrere Kundenkonten unter einer Company, ordnen sie Teams zu, vergeben Rollen mit granularen Berechtigungen und koppeln Bestellungen an Freigabeworkflows. Ohne dieses Modell müssten Agenturen jede Genehmigungslogik individuell nachbauen, was in der Praxis zu inkonsistenten, schwer wartbaren Insellösungen führt.

Dieser Artikel deckt das komplette Bild ab: das Datenmodell hinter B2B-Firmenkonten, die Team-Hierarchie als Baumstruktur, das Rollen- und ACL-System, Purchase Order Approval Rules, die GraphQL-Schnittstelle, eigene Plugin-Erweiterungen sowie das Zusammenspiel mit Shared Catalogs und Multi-User Quotes. Der Fokus liegt durchgehend auf Magento 2.4.8-p4 mit PHP 8.4, Service Contracts und Constructor Property Promotion.

2. Firmenstruktur im Datenmodell: company, company_team und Service Contracts

Im Kern jedes B2B-Firmenkontos steht die Tabelle company mit Feldern wie company_name, legal_name, sales_representative_id, customer_group_id und status. Jeder Einkäufer, der zu dieser Firma gehört, bekommt über company_advanced_customer_entity zusätzliche Attribute wie company_id, job_title, telephone und status, die als Extension Attributes an customer_entity angehängt werden. Diese Trennung erlaubt es, ein normales Kundenkonto ohne Datenverlust in ein Firmenkonto zu überführen und wieder zurückzuwandeln.

Der Zugriff auf diese Tabellen erfolgt konsequent über Service Contracts statt über direkte Collection-Zugriffe. CompanyRepositoryInterface mit den Methoden get(), save(), getList() und delete() kapselt die Persistenz, CompanyManagementInterface liefert Business-Logik wie das Zuordnen eines Kunden zu einer Firma. Alle Tabellen der Company-Module werden per db_schema.xml deklariert, InstallScripts kommen hier nicht mehr zum Einsatz. Wer eigene Attribute an B2B-Firmenkonten anfügen will, erweitert das Schema deklarativ und liest die neuen Felder über eigene Service Contracts aus, statt die Kern-Repositories zu preferencen.

Neben Firmen und Kunden gibt es die Tabelle company_team, die organisatorische Einheiten abbildet, die selbst keine Kundenkonten sind, etwa eine Abteilung oder ein Projektteam. Teams dienen als Knoten im Strukturbaum und gruppieren Einkäufer unabhängig von ihrer konkreten Rolle. Das folgende Repository zeigt, wie ein eigener Service Contract für firmenbezogene Genehmigungsregeln mit Constructor Property Promotion implementiert wird.

<?php

declare(strict_types=1);

namespace Mironsoft\B2bApproval\Model;

use Magento\Company\Api\CompanyRepositoryInterface;
use Magento\Framework\Exception\NoSuchEntityException;
use Mironsoft\B2bApproval\Api\ApprovalRuleRepositoryInterface;
use Mironsoft\B2bApproval\Api\Data\ApprovalRuleInterface;
use Mironsoft\B2bApproval\Model\ResourceModel\ApprovalRule as ApprovalRuleResource;
use Mironsoft\B2bApproval\Model\ResourceModel\ApprovalRule\CollectionFactory;

/**
 * Service contract implementation for reading and persisting company specific approval rules.
 */
class ApprovalRuleRepository implements ApprovalRuleRepositoryInterface
{
    /**
     * @param ApprovalRuleResource $resource
     * @param CollectionFactory $collectionFactory
     * @param CompanyRepositoryInterface $companyRepository
     */
    public function __construct(
        private readonly ApprovalRuleResource $resource,
        private readonly CollectionFactory $collectionFactory,
        private readonly CompanyRepositoryInterface $companyRepository
    ) {
    }

    /**
     * Load all approval rules assigned to a B2B company account.
     *
     * @param int $companyId
     * @return ApprovalRuleInterface[]
     * @throws NoSuchEntityException
     */
    public function getByCompanyId(int $companyId): array
    {
        $company = $this->companyRepository->get($companyId);
        $collection = $this->collectionFactory->create();
        $collection->addFieldToFilter('company_id', ['eq' => $company->getId()]);

        return $collection->getItems();
    }

    /**
     * Persist a single approval rule for a company account.
     *
     * @param ApprovalRuleInterface $rule
     * @return ApprovalRuleInterface
     * @throws \Exception
     */
    public function save(ApprovalRuleInterface $rule): ApprovalRuleInterface
    {
        $this->resource->save($rule);

        return $rule;
    }
}

3. Team-Hierarchie und Structure-Tree programmatisch abbilden

Die eigentliche Organisationsstruktur eines B2B-Firmenkontos lebt nicht in company selbst, sondern in einem separaten Strukturbaum, der Kunden und Teams als Knoten miteinander verbindet. StructureRepositoryInterface liefert diesen Baum als verschachtelte Knotenliste, wobei jeder Knoten einen Typ trägt, entweder Kunde oder Team, sowie eine Referenz auf den übergeordneten Knoten. Diese Modellierung erlaubt beliebig tiefe Hierarchien, von der flachen Zwei-Ebenen-Struktur eines kleinen Betriebs bis zur mehrstufigen Matrixorganisation eines Konzerns.

Programmatischer Zugriff auf die Struktur läuft über moveNode() und getStructureByCompanyId(), wobei jede Verschiebung eines Knotens serverseitig validiert wird, damit kein Zyklus im Baum entsteht und ein Kunde nicht versehentlich unter sein eigenes Team gehängt wird. Für Migrationen, etwa beim Import einer bestehenden Kundenhierarchie aus einem ERP-System, lohnt sich ein eigener Batch-Service, der die Struktur in der richtigen Reihenfolge von oben nach unten aufbaut, damit Parent-Knoten immer existieren, bevor ihre Kinder angelegt werden.

Ein häufiger Fehler bei eigenen Erweiterungen von B2B-Firmenkonten ist, die Struktur direkt über SQL oder Collection-Writes zu manipulieren. Das umgeht die interne Validierung und kann inkonsistente Bäume erzeugen, die sich in der Admin-Oberfläche nicht mehr korrekt rendern lassen. Jede Änderung an der Team-Hierarchie sollte deshalb ausschließlich über StructureRepositoryInterface laufen, auch wenn das für Massenimporte zunächst langsamer wirkt als ein direkter Bulk-Insert.

4. Berechtigungsrollen verwalten: Company Role Resource Model und ACL

Jedes B2B-Firmenkonto benötigt ein eigenes Rollensystem, das unabhängig von der globalen Magento-Admin-ACL funktioniert, aber demselben Prinzip folgt: Ressourcen werden Rollen zugewiesen, Rollen werden Einkäufern zugewiesen. Das Company Role Resource Model persistiert Rollen wie Einkäufer, Manager oder Freigabeberechtigter mit einer Liste erlaubter Ressourcen, etwa das Anlegen von Bestellungen, das Einsehen von Preisen oder das Freigeben von Purchase Orders. RoleRepositoryInterface stellt CRUD-Operationen für diese Rollen bereit und arbeitet dabei mit denselben Search-Criteria-Mustern wie andere Magento-Repositories.

Die Berechtigungsprüfung selbst nutzt intern dasselbe ACL-Framework, das auch im Admin-Bereich verwendet wird, nur mit einem eigenen Ressourcenbaum für B2B-Kontexte. Jede Ressource, etwa Magento_PurchaseOrder::approve oder Magento_Company::view_addresses, wird gegen die der aktuellen Rolle zugewiesenen Ressourcen geprüft. Das erlaubt feingranulare Freigaben: Ein Einkäufer darf Bestellungen anlegen, aber nicht freigeben, ein Manager darf beides, ein Freigabeberechtigter darf ausschließlich Bestellungen prüfen und genehmigen, ohne selbst einkaufen zu dürfen.

Bei eigenen Erweiterungen von B2B-Firmenkonten ist es wichtig, neue ACL-Ressourcen sauber über acl.xml im eigenen Modul zu registrieren und nicht in den Kern-Ressourcenbaum von Magento einzugreifen. So bleiben Rollen upgrade-sicher, und Kunden können neue Ressourcen in der gewohnten Rollenverwaltung im Storefront-Account zuweisen, ohne dass ein Custom-Interface dafür notwendig wird.

5. Freigabeworkflows: Purchase Order Approval Rules implementieren

Freigabeworkflows sind der eigentliche Mehrwert von B2B-Firmenkonten gegenüber einfachen Kundengruppen. Eine Purchase Order Approval Rule definiert eine Bedingung, meist einen Schwellenwert für den Bestellwert, und eine Liste von Rollen oder konkreten Personen, die eine Bestellung oberhalb dieses Schwellenwerts freigeben müssen. Überschreitet eine Bestellung den konfigurierten Betrag, wechselt sie automatisch in den Status "wartet auf Freigabe", statt direkt an die Order-Pipeline weitergereicht zu werden.

Native Approval Rules lassen sich über die Storefront-Verwaltung eines Firmenkontos konfigurieren und decken die meisten Standardfälle ab: einen Betrag pro Rolle, eine sequentielle Freigabekette über mehrere Rollen hinweg. Für komplexere Szenarien, etwa Freigaben abhängig von Produktkategorie, Kostenstelle oder Lieferland, reicht die Standardkonfiguration jedoch nicht aus. Hier zeigt sich, wo native Regeln enden und eigene Erweiterungen über Plugins beginnen müssen.

Die Prüfung, ob ein Einkäufer eine Bestellung tatsächlich freigeben darf, kombiniert immer zwei Bedingungen: die ACL-Berechtigung der zugewiesenen Rolle und den in der Approval Rule konfigurierten Schwellenwert. Der folgende Validator zeigt exemplarisch, wie beide Prüfungen für ein eigenes B2B-Firmenkonten-Feature zusammengeführt werden.

<?php

declare(strict_types=1);

namespace Mironsoft\B2bApproval\Model\Validator;

use Magento\Framework\Authorization;
use Magento\Sales\Api\Data\OrderInterface;
use Mironsoft\B2bApproval\Api\Data\ApprovalRuleInterface;

/**
 * Validates whether the current company user role is allowed to approve
 * a purchase order once the configured approval rule threshold is exceeded.
 */
class RoleAwareApprovalValidator
{
    private const ACL_RESOURCE_APPROVE_PURCHASE_ORDER = 'Magento_PurchaseOrder::approve';

    /**
     * @param Authorization $authorization
     */
    public function __construct(
        private readonly Authorization $authorization
    ) {
    }

    /**
     * Check if the current role may approve the order under the given rule.
     *
     * @param ApprovalRuleInterface $rule
     * @param OrderInterface $order
     * @return bool
     */
    public function isApprovalRequired(ApprovalRuleInterface $rule, OrderInterface $order): bool
    {
        $grandTotal = (float) $order->getGrandTotal();
        $threshold = (float) $rule->getConditionThreshold();

        if ($grandTotal < $threshold) {
            return false;
        }

        return !$this->authorization->isAllowed(self::ACL_RESOURCE_APPROVE_PURCHASE_ORDER);
    }
}

6. GraphQL-API für B2B-Company-Accounts

Für Headless- und Hyvä-Frontends stellt Magento eine eigene GraphQL-Schicht für B2B-Firmenkonten bereit. Die Query company liefert Stammdaten der Firma inklusive zugewiesener Rollen, während companyStructure den kompletten Team- und Kundenbaum als paginierbare Struktur zurückgibt. Beide Queries respektieren die ACL-Berechtigungen des anfragenden Kunden, ein Einkäufer ohne entsprechende Rolle sieht in der Struktur-Query nur die Teile des Baums, für die er tatsächlich Leserechte besitzt.

Mutations wie das Anlegen, Aktualisieren oder Deaktivieren eines Team-Mitglieds laufen über dedizierte Resolver, die dieselben Service Contracts im Hintergrund aufrufen wie die Storefront-Formulare. Das folgende Schema-Fragment zeigt, wie ein eigener Resolver für das Anlegen eines Team-Mitglieds in ein bestehendes B2B-Firmenkonto per schema.graphqls registriert wird, konsistent mit dem nativen Company-Schema.

type Query {
    company: Company @resolver(class: "Magento\\CompanyGraphQl\\Model\\Resolver\\Company")

    companyStructure(rootId: Int, pageSize: Int = 20, currentPage: Int = 1): CompanyStructure
        @resolver(class: "Magento\\CompanyGraphQl\\Model\\Resolver\\Structure")
}

type Mutation {
    createCompanyTeamMember(input: CompanyTeamMemberInput!): CompanyTeamMemberOutput
        @resolver(class: "Mironsoft\\B2bApproval\\Model\\Resolver\\CreateCompanyTeamMember")
}

input CompanyTeamMemberInput {
    company_id: Int!
    team_id: Int
    role_id: Int!
    email: String!
    firstname: String!
    lastname: String!
}

type CompanyTeamMemberOutput {
    customer_id: Int!
    status: String!
}

Bei eigenen GraphQL-Erweiterungen für B2B-Firmenkonten gilt dieselbe Regel wie im REST- und Admin-Kontext: Resolver dürfen keine eigene Berechtigungslogik erfinden, sondern müssen dieselben Service Contracts und ACL-Prüfungen wiederverwenden, die auch von Repository und Validator genutzt werden. Andernfalls entstehen zwei parallele Berechtigungssysteme, die bei jeder Änderung synchron gehalten werden müssten.

7. Eigene Genehmigungsregeln per Plugin erweitern

Gemäß den Coding Standards für dieses Projekt werden Erweiterungen an Kernlogik grundsätzlich über Plugins statt über Preferences realisiert. Für B2B-Firmenkonten bedeutet das konkret: Statt die native Approval-Rule-Validierung zu ersetzen, wird ein Plugin registriert, das die bestehende Prüfung um zusätzliche Bedingungen ergänzt, etwa eine Kostenstellen-Prüfung oder eine Sperrliste für bestimmte Produktkategorien.

Die Registrierung erfolgt über di.xml im eigenen Modul und zeigt auf den nativen Validator der Purchase-Order-Regel-Engine. Ein around-Plugin kann die native Entscheidung unverändert übernehmen und zusätzlich verschärfen, niemals aber abschwächen, ohne dass das an anderer Stelle explizit dokumentiert und im Code Review sichtbar gemacht wird. Diese Zurückhaltung schützt davor, dass eine scheinbar harmlose Erweiterung eine bestehende Freigabeprüfung versehentlich aushebelt.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\PurchaseOrderRule\Model\Validator\Rule\ApprovalRule">
        <plugin name="MironsoftB2bApprovalExtendApprovalRule"
                type="Mironsoft\B2bApproval\Plugin\ExtendApprovalRulePlugin"
                sortOrder="10" />
    </type>
</config>

Wichtig bei jeder Plugin-basierten Erweiterung von B2B-Firmenkonten ist die Testabdeckung: Ein fehlerhaftes Plugin, das eine Freigabebedingung falsch invertiert, kann dazu führen, dass Bestellungen ohne notwendige Genehmigung direkt durchlaufen. Ein Integrationstest, der gezielt Bestellungen oberhalb und unterhalb des Schwellenwerts erzeugt und die resultierenden Order-Status prüft, gehört deshalb zur Definition of Done jeder Freigabeerweiterung.

8. Multi-User Quotes und Shared Catalogs im Zusammenspiel mit Firmenkonten

B2B-Firmenkonten entfalten ihren vollen Nutzen erst im Zusammenspiel mit zwei weiteren B2B-Funktionen: Negotiable Quotes und Shared Catalogs. Ein Angebot, das ein Vertriebsmitarbeiter für eine Firma erstellt, kann von mehreren Einkäufern derselben Company eingesehen und kommentiert werden, bevor ein Freigabeberechtigter das finale Angebot in eine Bestellung überführt. Diese Multi-User-Fähigkeit setzt voraus, dass die Team-Hierarchie und die Rollen des Firmenkontos korrekt gepflegt sind, sonst sehen Einkäufer entweder zu viele oder zu wenige Angebote.

Shared Catalogs koppeln eine eigene Preisliste und ein eigenes Sortiment an eine oder mehrere Firmen, unabhängig von der klassischen Kundengruppen-Logik. Ein B2B-Firmenkonto kann dabei genau einem Shared Catalog zugeordnet sein, wodurch alle Einkäufer dieser Firma automatisch dieselben Sonderpreise und dasselbe freigegebene Sortiment sehen. Für Agenturen bedeutet das: Preis- und Sortimentslogik gehört nicht in individuelle Kundengruppen-Regeln, sondern konsequent in die Shared-Catalog-Zuordnung des jeweiligen Firmenkontos.

9. Sicherheits- und Skalierungsaspekte bei großen Firmenstrukturen

Je tiefer die Team-Hierarchie eines B2B-Firmenkontos verschachtelt ist, desto teurer werden naive Baumabfragen. Ein Konzern mit mehreren tausend Einkäufern und einer sechsstufigen Teamstruktur sollte niemals den kompletten Baum bei jeder Storefront-Anfrage neu aus der Datenbank materialisieren. Stattdessen lohnt sich ein eigener Cache für die Strukturabfrage, invalidiert über die Standard-Cache-Tags von Magento, sowie ein Index auf die Fremdschlüssel-Spalten der Struktur- und Team-Tabellen.

Sicherheitsseitig ist die größte Gefahr bei eigenen Erweiterungen von B2B-Firmenkonten eine unvollständige ACL-Prüfung in eigenem Code: Wer eine neue GraphQL-Query oder einen neuen Controller schreibt, muss explizit prüfen, ob der anfragende Kunde tatsächlich zu der abgefragten Firma gehört, und nicht nur, ob er irgendein B2B-Firmenkonto besitzt. Ohne diese company-scope-Prüfung könnte ein Einkäufer der Firma A theoretisch Daten der Firma B abfragen, sobald IDs erraten oder durchprobiert werden.

Für Audit-Zwecke lohnt sich zusätzlich eine eigene Protokolltabelle, die jede Freigabeentscheidung mit Firma, Bestellung, genehmigendem Kunden und Zeitstempel festhält. Das folgende db_schema.xml-Fragment zeigt eine solche Audit-Tabelle inklusive Fremdschlüssel auf die native company-Tabelle und einem Index, der Auswertungen auch bei großen Firmenstrukturen performant hält.

<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">
    <table name="mironsoft_b2b_approval_audit" resource="default" engine="innodb" comment="B2B Approval Audit Log">
        <column xsi:type="int" name="entity_id" padding="10" unsigned="true" nullable="false" identity="true" comment="Entity ID"/>
        <column xsi:type="int" name="company_id" padding="10" unsigned="true" nullable="false" comment="Company ID"/>
        <column xsi:type="int" name="purchase_order_id" padding="10" unsigned="true" nullable="false" comment="Purchase Order ID"/>
        <column xsi:type="int" name="approver_customer_id" padding="10" unsigned="true" nullable="false" comment="Approver Customer ID"/>
        <column xsi:type="varchar" name="decision" nullable="false" length="32" comment="Approval Decision"/>
        <column xsi:type="timestamp" name="created_at" on_update="false" nullable="false" default="CURRENT_TIMESTAMP" comment="Created At"/>
        <constraint xsi:type="primary" referenceId="PRIMARY">
            <column name="entity_id"/>
        </constraint>
        <constraint xsi:type="foreign" referenceId="MIRONSOFT_B2B_APPROVAL_AUDIT_COMPANY_ID_COMPANY_ENTITY_ID"
                    table="mironsoft_b2b_approval_audit" column="company_id"
                    referenceTable="company" referenceColumn="entity_id" onDelete="CASCADE"/>
        <index referenceId="MIRONSOFT_B2B_APPROVAL_AUDIT_COMPANY_ID" indexType="btree">
            <column name="company_id"/>
        </index>
    </table>
</schema>

10. Zusammenfassung

B2B-Firmenkonten in Magento 2 lösen ein Problem, das klassische Kundenkonten grundsätzlich nicht abbilden können: mehrere Einkäufer, eine gemeinsame Organisation, klare Rollen und Genehmigungsketten. Das Datenmodell aus company, company_advanced_customer_entity und company_team wird konsequent über Service Contracts angesprochen, die Team-Hierarchie über StructureRepositoryInterface gepflegt. Rollen und ACL-Ressourcen regeln, wer was darf, Purchase Order Approval Rules regeln, ab welchem Betrag eine Freigabe notwendig wird.

Eigene Erweiterungen an B2B-Firmenkonten gehören konsequent in Plugins statt in Preferences, neue Tabellen ausschließlich in db_schema.xml, neue GraphQL-Felder in eigene schema.graphqls-Dateien, die dieselben Service Contracts wiederverwenden wie Storefront und Admin. Wer diese Prinzipien einhält, bekommt B2B-Firmenkonten, die auch bei tausenden Einkäufern und tiefen Teamstrukturen performant, sicher und wartbar bleiben.

11. FAQ: B2B-Firmenkonten in Magento 2