Professionelles B2B-System für Magento 2 Open Source
- Kompatibilität
- 2.4.9, 2.4.8, 2.4.7
- Hyva Theme
- Hyva Theme Redy
Beschreibung / Professionelles B2B-System für Magento 2 Open Source
MAGENTO 2 · MAGENTO OPEN SOURCE · UNTERNEHMEN · B2B-HANDEL
Verbinden Sie B2B- und B2C-Verkauf in einer Magento-Installation.
Kowal B2B Suite erweitert Magento Open Source um Unternehmen, die Prüfung von EU-Umsatzsteuer-Identifikationsnummern in VIES, individuelle Handelsbedingungen, Einkaufslisten, RFQ-Angebote, Handelskredit, Freigaben, Dokumente und Integrationen.
Betreuen Sie Geschäftskunden in einem Selbstbedienungsportal und organisieren Sie den Vertrieb im Magento-Backend.
17 Module und Basistheme · REST und GraphQL · Hyvä-Kontoadapter
SO FUNKTIONIERT ES IN DER PRAXIS
01 · Handelsmodell festlegen
Unternehmen, Kanäle, Preise und Datenquellen definieren.
02 · B2B-Prozess konfigurieren
Rollen, Katalog, Bedingungen und Freigaben zuordnen.
03 · Systeme verbinden und bereitstellen
Adapter auswählen und vollständige Abläufe prüfen.
Der vollständige Funktionsumfang von Kowal B2B Suite
Von der Registrierung eines Geschäftskunden und Preisfindung bis zu Angebot, Bestellung, Dokumenten und Datenaustausch. Aktivieren Sie die Bereiche, die zu Ihren Vertriebsregeln passen.
Unternehmen und Betreuung von Geschäftskunden
Führen Sie Unternehmensstammdaten mit Name, Steuernummer, externer Kennung und zuständigem Vertriebsmitarbeiter.
- Registrierung und Freigabe von Unternehmen, Aktivierung, Sperrung oder Ablehnung.
- Status: ausstehend, aktiv, inaktiv, gesperrt und abgelehnt.
- Verknüpfungen mit Magento-Kundenkonten, Kundengruppen und Vertriebskanälen.
- Änderungshistorie für Unternehmen, Benutzer, Rollen, Adressen und Kontakte.
Benutzer, Rollen, Adressen und Kontakte
Ein Unternehmen kann mehrere Einkäufer und eigene Rollen mit festgelegten Berechtigungen haben.
- Benutzer zuweisen oder deaktivieren und ihre Rollen ändern.
- Separate Rechte für Bestellungen, die Einsicht in Unternehmensbestellungen, RFQ, Dokumente, Benutzer und Adressen.
- Rechnungs- und Lieferadressen, websitebezogene Standardadressen und gemeinsame Unternehmensadressen.
- Unternehmenskontakte einschließlich Hauptkontakt; Bearbeitung gemäß den Berechtigungen.
- Unternehmensdaten und Steuernummer bleiben von den privaten Adressdaten des Einkäufers getrennt.
Prüfung von EU-Umsatzsteuer-Identifikationsnummern in VIES
Prüfen Sie EU-Umsatzsteuer-Identifikationsnummern mit Länderpräfix direkt im B2B-Unternehmensdatensatz im Magento-Backend. Die Schaltfläche „In VIES prüfen“ startet die Prüfung und zeigt das Ergebnis neben dem Feld für die Steuer-ID an.
- EU-Umsatzsteuer-Identifikationsnummern mit Ländercode, beispielsweise
PL1234567890; die Prüfung umfasst Länder, die Magento als EU-Mitglieder erkennt. - Normalisierung der Eingabe: Leerzeichen, Punkte und Bindestriche werden ignoriert und Buchstaben vor der Prüfung in Großbuchstaben umgewandelt.
- Unterstützung des griechischen Präfixes EL durch Zuordnung zum von Magento verwendeten Ländercode GR.
- Prüfung von Format und Land vor der Anfrage an VIES, mit einem Hinweis bei erforderlichen Eingabekorrekturen.
- Unterscheidbare Ergebnisse: in VIES gültig, in VIES ungültig, ungültige Eingabe oder Prüfung nicht verfügbar.
Ein berechtigter Administrator startet die Prüfung für ein bereits gespeichertes Unternehmen und dessen Umsatzsteuer-Identifikationsnummer im Kontext eines zugeordneten aktiven B2B-Kanals. Eine geänderte Nummer muss zuerst gespeichert werden.
Gespeicherte VIES-Ergebnisse und Aktualität der Daten
Das Prüfergebnis wird sofort beim Unternehmen gespeichert, zusammen mit Datum und Uhrzeit der Prüfung sowie der geprüften Umsatzsteuer-Identifikationsnummer. So lässt sich leichter erkennen, welche Daten erneut geprüft werden müssen.
- VIES-Statusspalte in der Unternehmensliste mit Filtern für nicht geprüft, gültig, ungültig, ungültiges Format oder VIES nicht verfügbar.
- Spalte mit dem Prüfdatum und Filterung nach Datumsbereich.
- Zurücksetzen bei Änderung der Umsatzsteuer-Identifikationsnummer: Wird eine andere Nummer gespeichert, erhält das Unternehmen wieder den Status „nicht geprüft“. Das bisherige Prüfdatum und die gespeicherte geprüfte Nummer werden gelöscht.
- Beibehaltung des Ergebnisses bei reinen Formatänderungen, etwa bei Leerzeichen, Trennzeichen oder Groß- und Kleinschreibung, sowie bei Änderungen anderer Unternehmensdaten.
- Zuordnung des Ergebnisses zur richtigen Nummer: Ändert sich die Nummer während der Prüfung, verhindert das Modul das Speichern des Ergebnisses für die bisherige Nummer und fordert zu einem erneuten Versuch auf.
Kann der Dienst die Nummer nicht prüfen, erhält der Administrator eine separate Meldung zur Nichtverfügbarkeit der Prüfung mit der Bitte, es später erneut zu versuchen. Ein Verbindungsfehler wird von einem negativen VIES-Ergebnis unterschieden.
B2B und B2C in einer Installation
Aktivieren Sie B2B für ausgewählte Magento-Websites. Alle Store Views einer solchen Website verwenden den B2B-Modus; andere Websites können B2C bedienen.
- Ein Unternehmen kann mehreren aktiven B2B-Websites zugeordnet sein.
- Aktivität der Beziehung und Kundengruppe des Unternehmens werden je Website festgelegt.
- Preise, Kataloge, Dokumente, Limits, Angebote und Integrationen arbeiten im passenden Unternehmens- und Kanalkontext.
- Eine zusätzliche Website-Zuordnung verschiebt keine Magento-Kundenkonten und ändert deren Gruppen nicht automatisch.
Zugangskontrolle und geschlossenes B2B-Portal
Wählen Sie zwischen öffentlichem Shop, Shop mit Anmeldepflicht und öffentlichem Katalog mit Einschränkungen für Gäste.
- Erzwungene Anmeldung mit Ausnahmen für ausgewählte Aktionen oder URL-Pfade.
- Rückkehr zur ursprünglich angeforderten Seite nach der Anmeldung.
- Preise ausblenden und Gastkäufe unabhängig voneinander deaktivieren.
- Eigene Hinweise und ein Anmeldelink anstelle des Preises oder Kaufbuttons.
- Standardmäßige Warenkorbbuttons ausblenden und das Hinzufügen zum Warenkorb im klassischen Frontend serverseitig sperren.
- Kundenregistrierung offenlassen oder deaktivieren.
Der Schutz des Standard-Frontends muss in einer eigenen öffentlichen API oder einem Headless-Frontend separat umgesetzt werden.
Bestehende Kunden Unternehmen zuordnen
Mit der Massenaktion Assign or Create Company strukturieren Sie Ihre bestehende Magento-Kundendatenbank.
- Kunden mit oder ohne Unternehmenszuordnung filtern, auch für Exporte und Massenaktionen.
- Unternehmen anhand der normalisierten Steuernummer zuordnen oder neu anlegen; Konten ohne Steuernummer erhalten eigene Unternehmen.
- Standardadressen und Hauptkontakt in ein neu angelegtes Unternehmen übernehmen.
- Eine Einkäuferrolle mit grundlegenden B2B-Rechten vergeben.
- Bestehende Kundengruppen erhalten, bereits zugeordnete Konten überspringen und Migrationsergebnisse sowie Fehler ausgeben.
Administration und Massenbearbeitung
Verwalten Sie Unternehmen und zugehörige Daten über ein gemeinsames B2B-Menü. Der Magento-Kundendatensatz enthält ein Feld zur Unternehmenszuordnung.
- Listen und Formulare für Unternehmen, Benutzer, Rollen, Adressen, Kontakte und Audit-Einträge.
- Status, Vertriebsmitarbeiter, Website-Zuordnung, Beziehungsaktivität und Kundengruppe des Unternehmens gesammelt ändern.
- Rollen gesammelt anlegen oder aktualisieren und optional allen aktiven Benutzern ausgewählter Unternehmen zuweisen.
- Separate Transaktion und Audit-Einträge für jedes bearbeitete Unternehmen.
- Magento-Administratorrechte begrenzen den Zugriff auf einzelne Vorgänge.
Preislisten, Vertragspreise und Mengenstaffeln
Legen Sie Preise nach Unternehmen, Website, SKU, Währung und Menge fest. Vorrang haben Vertragspreise, danach zugewiesene B2B-Preislisten und schließlich Magento-Katalogpreise.
- Mehrere Preislisten und priorisierte Zuordnungen zu Unternehmen.
- Vertragspreise und Preislistenpositionen mit Mengenstaffeln und Feldern für Gültigkeitszeiträume.
- Anwendung der Vertrags- und Listenpreise im Warenkorb.
- Preisindexierung, Änderungsprotokoll und Explain Price zur Anzeige der gewählten Preisquelle.
- CSV-Import und -Export von Preislistenpositionen sowie Preiszugriff über die API.
Preisvorschläge in RFQ berücksichtigen Shop, Kunde, Menge, Währung und Steuern; bei Katalogpreisen auch passende Magento-Aktionen.
Unternehmensspezifischer Katalog
Steuern Sie die Produktsichtbarkeit mit Regeln für einzelne Geschäftskunden oder eine gesamte Website.
- Regeln für bestimmte Produkte, Kategorien oder den vollständigen Katalog.
- Aktionen allow und deny; ein Verbot hat Vorrang vor einer Freigabe.
- Sichtbarkeitsindex und Filterung der Produktlisten im Frontend.
- Zugriffskontrolle für ausgeblendete SKUs und erneute Prüfung in Einkaufslisten, RFQ und Checkout.
- Produktsichtbarkeit für ein Unternehmen prüfen und den Index über die API neu aufbauen.
Eine fehlende passende Regel blendet ein Produkt nicht automatisch aus. Grundlage bleibt der native Magento-Katalog.
Schnellbestellungen und Einkaufslisten
Kunden erstellen benannte Einkaufslisten und ergänzen mehrere Positionen per SKU, statt jedes Produkt einzeln zu suchen.
- Bis zu 100 Zeilen gleichzeitig einfügen: SKU, Menge und optionale Notiz, zum Beispiel
SKU-001;10;Lieferung ans Lager. - Listen mit Standardkennzeichnung, Positionen, letztem B2B-Preis und Währung.
- Prüfung von SKU, Produktstatus, Website-Zuordnung, Unternehmenssichtbarkeit, positiver Menge und B2B-Preis.
- Eine Liste nach erneuter Prüfung in den Warenkorb übernehmen.
- Administratoren können Listen einsehen, Positionen entfernen und als CSV exportieren.
- Debug SKU sowie Ansichten für Importprotokolle und Zeilenfehler aus Prozessen, die diese Daten bereitstellen.
RFQ: Angebotsanfragen im Kundenkonto
Berechtigte Einkäufer können eine Anfrage mit Titel, Notiz und 1 bis 200 Positionen absenden.
- Suche nach SKU, Produktname und vorhandenen Attributen EAN, EAN13, GTIN oder barcode.
- Vorschläge ausschließlich für aktive, sichtbare Produkte der Typen simple und virtual.
- Menge, optionaler gewünschter Netto-Stückpreis und Positionskommentar.
- Netto- und Bruttopreisvorschau; Mengenänderungen aktualisieren die Vorschläge und erhalten manuell eingegebene Preise.
- Preise in der Shopwährung und gemäß der Steuerkonfiguration des Shops.
- Prüfung der gesamten Anfrage: Ein Positionsfehler macht den Speichervorgang rückgängig; die Formulardaten bleiben zur Korrektur erhalten.
RFQ: Angebote erstellen und verhandeln
Vertriebsmitarbeiter erstellen RFQs auch im Magento-Backend und wählen Website, Store View, Unternehmen, Kunde, Währung und Produkte.
- Als Entwurf oder eingereichte Anfrage speichern; Produktsuche mit Netto- und Bruttopreisvorschlägen.
- Gewünschte und angebotene Preise, verhandelter Gesamtbetrag, Gültigkeitsdatum, Kommentare und Vertriebsnotizen.
- Prozessstatus, Entscheidungshistorie und Schutz vor Annahme abgelaufener Angebote.
- Fertige Angebote per E-Mail mit anmeldegeschützten Links zu Details und PDF versenden.
- Annahme oder Ablehnung durch den Kunden, optionaler Ablehnungsgrund und Administratorentscheidungen.
- Separate PDFs für Kunden und Administratoren; interne Notizen und Verwaltungshistorie bleiben in der Admin-Version.
Vom angenommenen Angebot zur Bestellung
Übernehmen Sie Positionen und vereinbarte Preise eines angenommenen Angebots in den Magento-Bestellprozess.
- Convert to Cart erstellt einen Kundenwarenkorb mit Angebotspositionen und Angebotspreisen.
- Kunden mit Bestellrecht wählen im Standard-Checkout Adresse, Versand und Zahlung.
- Create Order erstellt im Backend automatisch eine Bestellung, wenn die erforderlichen Adressen und eindeutige Zahlungs- und Versandmethoden verfügbar sind.
- Sind weitere Angaben erforderlich, wird das Angebot in das native Backend-Formular zur Bestellerstellung geladen.
- Der Store-View-Kontext des Angebots und die Verknüpfung mit Warenkorb oder Bestellung bleiben erhalten.
Checkout, Zahlung, Versand und PO-Nummer
Ergänzen Sie den Standard-Bestellprozess von Magento um B2B-Regeln.
- Prüfung des aktiven Unternehmens, seiner Website-Zuordnung und des Bestellrechts des Benutzers.
- Prüfung des Katalogs und der Verfügbarkeit eines B2B-Preises bei der Bestellung.
- Regeln für zulässige Zahlungs- und Versandmethoden je Unternehmen und Website.
- Unternehmensadressen für Rechnung und Lieferung mit kanalbezogenen Standardwerten.
- Bestellreferenz des Kunden (PO) und Bestellkommentar.
- Unternehmen, Einkäufer sowie Kredit-, Freigabe- und Exportstatus im B2B-Kontext der Bestellung speichern.
Kreditlimits und Zahlungsbedingungen
Überwachen Sie Kreditlimit, Nutzung und verfügbaren Betrag je Unternehmen, Website und Währung.
- Zahlungsbedingungen, Aktivierung oder Sperrung des Limits und optionale Zulassung einer Überschreitung.
- Zahlungsarten auswählen, die das Firmenkreditlimit nutzen; andere funktionieren ohne eingerichtetes Limit.
- Atomare Reservierung vor der Bestellung mit Zuordnung zur gespeicherten Bestellung.
- Freigabe nach einem Fehler ohne erstellte Bestellung, vollständiger Zahlung, Stornierung oder Abschluss.
- Manuelle Nutzungskorrekturen, Einsicht in Reservierungen und Ereignishistorie.
- Abgleich per Cron nach unterbrochenen Prozessen oder vorübergehenden Fehlern.
Bei Teilzahlung bleibt der volle Betrag bis zur vollständigen Abrechnung oder Stornierung reserviert.
Bestellfreigabe und Steuerung der Abwicklung
Definieren Sie Freigaberegeln nach Unternehmen, Website, Währung und Wertschwelle. Bei mehreren passenden Regeln entscheiden Priorität und Schwellenwert.
- Aktive Unternehmensbenutzer als Freigabeberechtigte zuweisen.
- Automatisch einen ausstehenden Antrag für passende Bestellungen erstellen.
- Genehmigen, ablehnen oder abbrechen, jeweils mit Kommentar und Audit-Protokoll.
- Den Export als gesperrt markieren und die Bestellung zurückstellen, sofern ihr Status dies erlaubt.
- Nach Genehmigung den B2B-Status aktualisieren und die Zurückstellung aufheben; bei Ablehnung oder Abbruch bleibt der Export gesperrt.
Der enthaltene Ablauf schließt einen ausstehenden Antrag mit einer Entscheidung. Mehrstufige Freigaben erfordern eine zusätzliche Erweiterung; die Integration muss den Export-Sperrstatus berücksichtigen.
Geschäftsdokumente im Kundenportal
Stellen Sie dem richtigen Unternehmen Rechnungen, Gutschriften, Lieferscheine und Bestellbestätigungen bereit.
- Automatische Dokumenterstellung aus Magento-Sales-Bestellungen, Rechnungen, Sendungen und Gutschriften.
- Dokumentquelle, Ausgangsstatus und Generierung einzelner Dokumenttypen konfigurieren; hybrides Modell Magento + API.
- Manueller PDF-Upload im Backend, Metadaten, Datumsangaben, Beträge, Währungen und Verknüpfungen mit Magento-Entitäten.
- Originaldateien aus externen Systemen unverändert bereitstellen.
- Downloads nach Prüfung von Unternehmen, Website, Berechtigungen und Dokumentstatus.
- Kundenzugriff, Dateien und Synchronisierungsprotokolle im Backend prüfen.
Bearbeitbare PDFs und Sprachversionen
Ein gemeinsamer PDF-Generator unterstützt Verkaufsdokumente und RFQ-Angebote.
- HTML/CSS-Vorlagen im Backend bearbeiten und mit Beispieldaten vorprüfen.
- Separate Vorlagen nach Dokumenttyp, Website und Empfänger; lokale Vorlagen haben Vorrang vor globalen.
- Eigene Titel für Bestätigungen, Rechnungen, Gutschriften, Lieferscheine und Angebote.
- Logo, Verkäufer- und Käuferdaten, Steuernummern, Adressen, Positionen, Summen sowie Zahlungs- und Versandinformationen und -hinweise in Verkaufsdokumenten.
- RFQ-Kundenversion getrennt von internen Administratordaten.
- Übersetzte Beschriftungen gemäß Shopsprache; Wörterbücher für Polnisch und viele weitere europäische Sprachen.
Vorlagenänderungen gelten für neu erzeugte PDFs. Bereits gespeicherte Dateien müssen neu generiert werden.
Unternehmenskonto und Hyvä-Themes-Adapter
Das Unternehmensportal vereint Stammdaten, Adressen, Kontakte, Benutzer, Dokumente, Kredit, Einkaufslisten und RFQ.
- Unternehmensadressen und die fünf neuesten Bestellungen im nativen Kontobereich.
- Eigene oder unternehmensweite Bestellungen je nach Berechtigung, geschützte PDF-Links und Wiederbestellung durch den berechtigten ursprünglichen Käufer.
- Sechs Schalter für native Links: Adressen, Bestellungen, Downloads, gespeicherte Zahlungen, Bewertungen und Newsletter.
- Enthaltener optionaler Hyvä-Themes-Adapter mit responsiven Tabellen, Formularen und Kontonavigation.
- Aktivierung je Store View; standardmäßig ausgeschaltet und nur mit Hyvä und B2B aktiv.
Der Adapter umfasst das Kundenkonto. Hyvä Checkout, Warenkorb und Minicart benötigen einen separaten Integrationsumfang. Menüschalter steuern die Sichtbarkeit von Links; Berechtigungen werden unabhängig geprüft.
CSV-Import und -Export von B2B-Daten
Übertragen und aktualisieren Sie Daten über Profile, die einer bestimmten Website zugeordnet sind.
- Unternehmen, Benutzerzuordnungen und Rollen mit Berechtigungen.
- Preislistendefinitionen, Vertragspreise und Katalogsichtbarkeitsregeln.
- Dokumentmetadaten, Zuordnungen vorhandener Dokumentdateien und Kreditlimits.
- CSV-Upload, Validierung und Dry-Run zur Prüfung vor dem Speichern.
- Auftragshistorie, Fehlerprotokolle mit Zeilennummern sowie Download von Fehlerberichten und Exportdateien.
- Separater Import und Export von Preislistenpositionen im Bereich Pricing.
Benutzerzuordnungen verwenden vorhandene Magento-Konten; Dokumentdatei-Importe verweisen auf Dateien, die bereits an einem zulässigen Speicherort liegen.
REST API und GraphQL
Stellen Sie B2B-Prozesse über die API für Integrationen und eigene Oberflächen bereit.
- REST: Website-Konfiguration, Unternehmen und Benutzer, Produkte, MSI-Verfügbarkeit, Preise, Katalog, Einkaufslisten, RFQ, Dokumente, Limits, Freigaben, Bestellkontext, Import/Export und Integrationen.
- Sammeloperationen für Unternehmen und Idempotenzschlüssel bei deren Erstellung.
- Produktberichte, einschließlich fehlender Übersetzungen und Bestandsdaten.
- GraphQL-Abfragen für Unternehmensdaten, Preise, Listen, Angebote, Dokumente, Kredit, Freigaben und Integrationsaufträge.
- GraphQL-Mutationen für Einkaufslisten, RFQ-Prozesse sowie Veröffentlichung, Verarbeitung und Wiederholung von Integrationsaufträgen.
Der Zugriff hängt von Berechtigungen und Vorgangskontext ab. REST und GraphQL stellen festgelegte Schnittstellen bereit; ihre Operationen sind nicht deckungsgleich.
Integrationen mit ERP, PIM, WMS und CRM
Das Paket liefert die Infrastruktur zur Anbindung von Magento an Ihre Unternehmenssysteme.
- Profile nach Website, Systemtyp, Übertragungsrichtung und Adapter.
- Zuordnung lokaler und externer Kennungen.
- Synchronisierungsaufträge mit geplantem Zeitpunkt, Eingabedaten und Idempotenzschlüssel erstellen.
- Verarbeitungsstatus, Ergebnisse, Anzahl der Versuche, Protokolle und Fehler.
- Den gleichen Auftrag manuell erneut ausführen und problematische Aufträge in der Dead Letter Queue prüfen.
Ein konkretes ERP-, PIM-, WMS-, CRM-, EDI- oder Beschaffungssystem benötigt einen Adapter und einen eingerichteten Verarbeitungsprozess. Bei der Implementierung werden die Quellen für Unternehmen, Preise, Bestände, Bestellungen und Dokumente festgelegt.
Dashboard, Berichte und Diagnose
Das B2B-Dashboard zeigt Unternehmenszahlen und -status, aktive Benutzer, Preislisten, Katalogregeln, Fehler und letzte Änderungen.
- Berichte zu Unternehmen ohne aktive Website, Benutzer oder Preisliste sowie Kunden ohne Unternehmen.
- Berichte zu fehlenden Indexpreisen, MSI-Quelldaten und Übersetzungen von Produktnamen.
- Dokumente ohne Datei, Import- und Integrationsfehler sowie Bestellungen, die auf Freigabe warten oder für den Export gesperrt sind.
- Berichte nach Website filtern, Datensätze vorprüfen und als CSV exportieren.
- Systemstatus, Unternehmens- und Entscheidungsaudits, Kredit- und Synchronisierungsprotokolle sowie Explain Price und Debug SKU.
- Konfiguration der B2B-Diagnose und Protokollaufbewahrung.
Ein Paket, modulare Architektur
kowal/metapackage-b2b-suite enthält 17 Magento-Module und das Basistheme frontend/Kowal/b2b: Base, Access Control, Company, Admin UI, Pricing, Catalog Permissions, Quick Order, Quote, Checkout, Credit Limit, Approval, Document, Import/Export, Integration, REST API, GraphQL und den optionalen Hyvä-Adapter.
Die Installation erfolgt über ein einziges Composer-Paket. Nach Freigabe des Repository-Zugangs umfasst die Bereitstellung die Aktivierung benötigter Module, die Aktualisierung der Magento-Datenbank, die Konfiguration von Websites und Unternehmen sowie Kompilierung, Veröffentlichung statischer Ressourcen und Cache-Bereinigung entsprechend dem Shopmodus.
Anforderungen und Implementierungsumfang
Das Projekt ist auf Magento Open Source 2.4.9 ausgerichtet; das Paket erfordert PHP ^8.3. Es nutzt den nativen Magento-Katalog, Warenkorb, Checkout und MSI sowie den PDF-Generator mPDF.
Verfügbar sind das klassische Magento-Frontend und ein optionaler Kontoadapter für Hyvä Themes. Das B2B-Basistheme dient als Ausgangspunkt für die Gestaltung des Portals.
Der Implementierungsumfang richtet sich nach Shopversion, Theme, Zahlungs- und Versandarten sowie externen Systemen. Kompatibilität und vollständiger Bestellprozess müssen in der Zielinstallation geprüft werden.
Planen Sie B2B passend zu Ihrem Unternehmen
Möchten Sie das Modul an Ihren Shop anpassen? Fragen Sie die Implementierung von Kowal B2B Suite an und besprechen Sie Konfiguration oder benötigte Erweiterungen.
Lesen Sie vor der Planung, wie sich manuelle B2B-Vertriebsarbeit in Magento 2 reduzieren lässt und was die manuelle Bearbeitung einer B2B-Bestellung tatsächlich kostet (Artikel auf Polnisch).
Weitere Informationen
| Hyva Theme | Hyva Theme Redy |
|---|---|
| Übereinstimmung mit der Vorlage | Gut, Luma / Leer, KOWAL |
Konfiguration der Integration
Kowal B2B API — vollständige REST-Dokumentation
Vertragsversion:
V1· Quelle der Wahrheit:Kowal_B2BApi/etc/webapi.xml· Zielgruppe: Shop-Administratoren, Implementierungspartner und Teams, die ERP, PIM, WMS oder ein Beschaffungssystem integrieren.
1. Zweck und Grenzen der API
Die Kowal B2B API stellt B2B-Daten und -Prozesse bereit, die in Magento 2 laufen: Firmen, Katalog und individuelle Preise, Schnellkäufe, Dokumente, Kreditlimit, Genehmigungen, RFQ sowie Integrationswarteschlangen. Es handelt sich um eine REST API für Systemintegrationen; sie ersetzt nicht die Standard-Endpunkte von Magento für Katalog, Warenkorb, Checkout und Kundenkonto.
Das Dokument beschreibt ausschließlich die aktuell bereitgestellten Endpoints des Moduls. Es enthält keine Zusage für Operationen, die der Vertrag V1 nicht bereitstellt, z. B. Erstellung einer Bestellung per REST, CRUD von Preislisten oder Bearbeitung der Website-Konfiguration.
2. Zugriff erhalten und Regeln der Zusammenarbeit
2.1. Prozess zur Inbetriebnahme der Integration
- Der Integrator übermittelt dem Shop-Administrator Ziel der Integration, Umgebung (Test/Produktion), Quellsystem, Datenumfang sowie die Liste der erforderlichen API-Bereiche.
- Der Administrator erstellt oder konfiguriert die Magento-Integration, weist ihr minimale ACL-Berechtigungen zu und übermittelt über einen sicheren Kanal:
baseUrl, Token,websiteId,companyId(falls zutreffend), Währung und Testdaten. - Der Integrator führt den Test
GET /V1/kowal-b2b/websites/:websiteId/configund anschließend Funktionstests in der Testumgebung aus. - Vor der Produktion vereinbaren beide Seiten den Synchronisationsplan, die maximale Datengröße, Retry, den Dateneigentümer und die Art der Fehlermeldung.
- Tokens werden ausschließlich in einem Secrets Vault gespeichert; der Administrator rotiert oder entzieht sie bei Wechsel des Anbieters, Benutzers oder Integrationsumfangs.
2.2. Verantwortlichkeiten
| Partei | Verantwortung |
|---|---|
| Shop-Administrator | Konfiguration der B2B-Website, Firma und Firmenbeziehung zur Website, des Tokens und der ACL; Bereitstellung von Testdaten; Entscheidung über den Zugriff auf Daten. |
| Integrator | Sichere Speicherung des Tokens, korrekte Verwendung des Kontexts websiteId/companyId, Datenvalidierung, Fehler- und Retry-Behandlung, keine Offenlegung von Daten anderer Firmen. |
| Verantwortlicher des Geschäftsprozesses | Abstimmung der Quelle der Wahrheit für Preise, Dokumente, RFQ, Limits und Synchronisationsstatus. |
Ein Administrator-Token sollte nicht in einer Client-Anwendung verwendet und ein einzelnes Token nicht von unabhängigen Systemen gemeinsam genutzt werden. Jede Integration sollte ein eigenes Token und ausschließlich die erforderlichen ACL haben.
2.3. Berechtigungen
Magento prüft das Bearer-Token sowie die ACL, die dem administrativen Benutzer oder der Integration zugewiesen sind. B2B-Endpoints erfordern eine der folgenden Berechtigungsgruppen:
| ACL | Umfang |
|---|---|
config | Websites und Feature Flags |
companies, company_save, company_users, batch | Firmen, ihre Benutzer und Batch-Import von Firmen |
products, prices, catalog_permissions | Katalog, Verfügbarkeit, Preise und Sichtbarkeit |
import_export, quick_order, documents | Import-/Exportprofile, Einkaufslisten und Dokumente |
credit_limits, approvals, orders, quotes | Limit, Genehmigungsworkflow, Bestellkontext und RFQ |
system_integrations | Profile, Zuordnungen und Integrationsjobs |
Der Umfang sollte sich aus dem Zweck der Integration ergeben. Beispiel: Ein Beschaffungssystem benötigt in der Regel products, prices, catalog_permissions, quick_order und quotes; ein ERP, das Dokumente verarbeitet — documents sowie, wenn es Eigentümer der Synchronisierung ist, system_integrations.
3. Technische Konventionen
Adresse, Header und Parameter
Die Basisadresse hat die Form https://b2b.example.com/rest/V1. Alle weiteren Pfade im Dokument werden ab /V1 angegeben; die vollständige Endpoint-Adresse ist BASE_URL + Pfad.
Authorization: Bearer Accept: application/jsonContent-Type: application/json Die API verwendet JSON. Namen in der URL sind camelCase (websiteId, companyId), und JSON-Felder entsprechen den Parameternamen der Magento-Verträge. :companyId, :quoteId, :sku usw. sind Pfadparameter. In Beispielen bedeutet ? einen optionalen Parameter.
websiteId ist bei Operationen erforderlich, die vom Vertriebskanal abhängig sind. Es muss auf eine bestehende Website mit aktiviertem B2B verweisen. companyId verweist auf eine Firma, die eine aktive Beziehung zu dieser Website haben muss, wenn die Operation in ihrem Kontext ausgeführt wird. Die API wählt weder eine Standard-Website noch eine Standardfirma aus.
Request Body und Idempotenz
Magento serialisiert das DTO-Objekt unter dem Namen des Methodenparameters: Die meisten Schreibvorgänge akzeptieren {'request': {...}}; die Erstellung einer Firma verwendet {'company': {...}}; Firmen-Batch — {'companies': [...]}. Endpoints mit einfachen Argumenten akzeptieren Felder ohne Wrapper, z. B. {'websiteId': 1, 'currency': 'PLN', 'items': [...]}.
Der Header Idempotency-Key (max. 128 Zeichen) wird derzeit von POST /companies unterstützt: Ein Retry mit demselben Schlüssel gibt die zuvor erstellte Firma zurück. Für einen Integrationsjob verwenden Sie das Feld request.idempotencyKey. Gehen Sie nicht von automatischer Idempotenz anderer Schreib-Endpoints aus; wiederholen Sie sie erst, nachdem der Status der Operation geklärt wurde.
Antworten und Fehler
Erfolgreiche Antworten sind Objekte oder Tabellen von Magento-Verträgen. Von Objekten zurückgegebene Felder können kompatibel erweitert werden; die Integration sollte unbekannte Felder ignorieren. Ein Geschäftsfehler kann enthalten:
{ 'code': 'b2b.company.not_assigned_to_website', 'message': 'B2B company is not assigned to website.', 'website_id': 1, 'trace_id': 'request-correlation-id', 'details': {'company_id': 10}, 'field_errors': []}| HTTP | Bedeutung | Reaktion des Integrators |
|---|---|---|
400 / 422 | Ungültige Daten oder Domain-Validierung | Daten korrigieren; nicht ohne Änderung des Payloads wiederholen. |
401 / 403 | Kein oder unzureichendes Token/ACL | Nicht wiederholen; dem Administrator den Token-Umfang melden. |
404 | Ressource oder Beziehung existiert im jeweiligen Kontext nicht | IDs und Website-Kontext prüfen. |
409 | Statuskonflikt oder Duplikat | Aktuellen Zustand lesen, bevor über eine Wiederholung entschieden wird. |
5xx / timeout | Technischer Fehler | Begrenzte Retries mit Backoff anwenden und trace_id aufbewahren. |
Loggen Sie keine Tokens, vollständigen personenbezogenen Daten oder Konfigurationsgeheimnisse. Eine Meldung an das Shop-Team sollte Zeit, Methode, Pfad ohne Secrets, HTTP-Status, trace_id sowie anonymisierten Payload enthalten.
4. Schemas der Eingabedaten
Die folgenden Schemas gelten gemeinsam für die Referenz-Endpoints. Ein Feld ohne ? ist durch den Vertrag erforderlich; ? bedeutet einen optionalen Wert. Die Felder metadata, config, configuration und payload sind JSON-Objekte.
| DTO / Wrapper | Felder |
|---|---|
company | websiteId, name, taxId, externalId?, status?, salesRepresentativeId?, customerGroupId?, websiteActive? |
companyUser | websiteId, roleId, active |
request — RFQ | websiteId, companyId, customerId?, externalId?, title, currency, validUntil?, customerNote?, salesNote?, metadata? |
request — RFQ-Position | quoteId, sku, productId?, name?, qty, requestedPrice?, offeredPrice?, comment?, metadata? |
request — RFQ-Entscheidung | customerId?, adminUserId?, message? |
request — RFQ-Kommentar | quoteId, customerId?, adminUserId?, authorType, message, visibleForCustomer |
request — Dokument | websiteId, companyId, orderId?, orderIncrementId?, invoiceId?, invoiceIncrementId?, creditmemoId?, creditmemoIncrementId?, externalId?, documentNumber, documentType, status, issueDate?, dueDate?, grandTotal?, currency?, metadata? |
request — Dokumentdatei | documentId, fileName, filePath, mimeType, fileSize, checksum?, primary |
request — Limit | websiteId, companyId, termsId?, creditLimit, currency, active, status, metadata? |
request — Limit-Exposure | websiteId, companyId, sourceType, sourceId, sourceIncrementId?, amount, currency, dueDate?, metadata? |
request — Zahlungsbedingungen | websiteId, code, name, daysDue, active, description? |
request — Genehmigungsregel | websiteId, companyId, name, thresholdAmount, currency?, priority, active, metadata? |
request — Genehmiger | ruleId, customerId, sortOrder, active |
request — Genehmigungsentscheidung | approverCustomerId?, comment? |
request — Genehmigungsantrag | websiteId, companyId, orderId?, orderIncrementId?, requesterCustomerId?, grandTotal, currency, comment?, metadata? |
request — Import-/Exportprofil | websiteId, code, name, direction, entityType, format, behavior, active, configuration? |
request — Integrationsprofil | websiteId, code, name, systemType, adapterCode, direction, active, maxAttempts, config? |
request — Zuordnung | websiteId, systemType, entityType, localId, externalId, metadata? |
request — Integrationsjob | profileId, direction?, entityType, operation, idempotencyKey?, maxAttempts?, payload?, scheduledAt? |
5. Endpoint-Referenz
In den Tabellen bezeichnet ACL die minimale Magento-Berechtigungsressource. Ergebnis bestimmt die Art der erfolgreichen Antwort.
5.1. Websites und Konfiguration
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /V1/kowal-b2b/websites | config | — | Tabelle der Websites (websiteId, Code, Name, B2B-Flag). Vor der Konfiguration der Integration abrufen. |
GET /V1/kowal-b2b/websites/:websiteId/config | config | path: websiteId | B2B-Konfiguration der Website (u. a. enabled/debug/Log-Aufbewahrung). Als Zugriffstest ausführen. |
GET /V1/kowal-b2b/websites/:websiteId/features | config | path: websiteId | Für die Website aktive Feature Flags; zur bedingten Aktivierung von Kundenfunktionen verwenden. |
5.2. Firmen und Firmenbenutzer
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /companies?websiteId= | companies | query: websiteId | Tabelle der Firmen, die der Website zugewiesen sind. |
POST /companies | company_save | body: company | Erstellt eine Firma und die Beziehung zur Website; bei Wiederholungen Idempotency-Key verwenden. Gibt die Firma zurück. |
POST /companies/batch | batch | body: companies — Tabelle company | Erstellt mehrere Firmen und gibt das Ergebnis pro Element einschließlich Fehlern zurück. |
GET /companies/:companyId?websiteId= | companies | path: companyId; query: websiteId | Im Website-Kontext verifizierte Firma. |
PUT /companies/:companyId | company_save | path: companyId; body: company | Aktualisiert Daten und Firmenbeziehung für company.websiteId. |
POST /companies/:companyId/activate?websiteId= | company_save | path: companyId; query: websiteId | Aktiviert die Firma in der angegebenen Website und gibt die Firma zurück. |
POST /companies/:companyId/block?websiteId= | company_save | path: companyId; query: websiteId | Sperrt die Firma in der angegebenen Website und gibt die Firma zurück. |
GET /companies/:companyId/users?websiteId= | company_users | path: companyId; query: websiteId | Tabelle der Kundenzuweisungen zur Firma. |
PUT /companies/:companyId/users/:customerId | company_users | path: companyId, customerId; body: companyUser | Vergibt/aktualisiert Rolle und Aktivität des Kunden in der Firma; gibt die Zuordnung zurück. |
5.3. Produkte, Preis und Katalogsichtbarkeit
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /products?websiteId= | products | query: websiteId | Tabelle grundlegender Magento-Produkte für die Website. |
GET /products/:sku?websiteId= | products | path: codiertes sku; query: websiteId | Produkt (id, sku, Name, Typ, Status, Websites). |
GET /products/:sku/availability?websiteId= | products | path: sku; query: websiteId | MSI-Verfügbarkeit und verkaufbare Menge für SKU. |
GET /products/:sku/b2b-status?websiteId= | products | path: sku; query: websiteId | B2B-Status: Zuweisung zur Website, Übersetzungen und Stock-Daten. |
GET /reports/products/missing-translations?websiteId= | products | query: websiteId | Bericht zu SKUs ohne erforderliche Übersetzungen, mit reason/details. |
GET /reports/products/missing-stock?websiteId= | products | query: websiteId | Bericht zu SKUs ohne erforderliche Stock-Daten. |
GET /companies/:companyId/products/:sku/price?websiteId=¤cy=&qty= | prices | path: companyId, sku; query: websiteId, currency, optional qty (standardmäßig 1) | Erklärung des für Firma, Währung und Menge gültigen Preises; vor dem Kauf abrufen. |
GET /companies/:companyId/products/:sku/visibility?websiteId= | catalog_permissions | path: companyId, sku; query: websiteId | Ergebnis der Sichtbarkeit/Kaufbarkeit der SKU für die Firma. |
GET /companies/:companyId/catalog-visibility?websiteId= | catalog_permissions | path: companyId; query: websiteId | Tabelle der Indexpositionen des für die Firma sichtbaren Katalogs. |
POST /companies/:companyId/catalog-visibility/reindex?websiteId= | catalog_permissions | path: companyId; query: websiteId | Erstellt den Index neu und gibt die Anzahl der indexierten Positionen zurück. Administrative Operation. |
5.4. Dateiimport und -export
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /import-export/profiles?websiteId= | import_export | query: websiteId | Tabelle der Import-/Exportprofile der Website. |
POST /import-export/profiles | import_export | body: request — Import-/Exportprofil | Speichert das Profil und gibt dessen Daten zurück. |
POST /import-export/import/:profileId?sourceFile=&dryRun= | import_export | path: profileId; query: sourceFile, optional dryRun=false | Startet den Import der auf Seite der Magento-Umgebung angegebenen Datei; gibt einen Job zurück. Sendet kein Multipart. |
POST /import-export/export/:profileId?resultFile= | import_export | path: profileId; optional query: resultFile | Erstellt einen Exportjob, optional mit Zielpfad der Datei. |
GET /import-export/jobs?websiteId= | import_export | query: websiteId | Tabelle der Import-/Exportjobs für die Website. |
GET /import-export/jobs/:jobId | import_export | path: jobId | Status, Ergebnis und Daten eines einzelnen Jobs. |
GET /import-export/jobs/:jobId/logs | import_export | path: jobId | Diagnoselogs des Jobs. |
5.5. Schnellbestellung und Einkaufslisten
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
POST /companies/:companyId/quick-order/validate | quick_order | path: companyId; body: websiteId, currency, items (sku, qty) | Validiert mehrere SKUs im Firmenkontext: Verfügbarkeit, Sichtbarkeit und Preis; gibt ein Sammelergebnis zurück. |
GET /companies/:companyId/shopping-lists?websiteId= | quick_order | path: companyId; query: websiteId | Tabelle der Einkaufslisten der Firma. |
POST /companies/:companyId/shopping-lists | quick_order | path: companyId; body: websiteId, name, optional customerId, isDefault=false | Erstellt eine Einkaufsliste und gibt sie zurück. |
GET /shopping-lists/:listId/items | quick_order | path: listId | Tabelle der Positionen der angegebenen Liste. |
POST /shopping-lists/:listId/items | quick_order | path: listId; body: currency, items (sku, qty) | Fügt Positionen zur Liste hinzu und gibt die gespeicherten Positionen zurück. |
5.6. Dokumente und Dateien
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /companies/:companyId/documents?websiteId=&documentType= | documents | path: companyId; query: websiteId, optional documentType | Dokumente der Firma, optional nach Typ gefiltert. |
GET /documents/:documentId?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Dokumentdetails nach Prüfung der Firmenzugehörigkeit. |
POST /documents | documents | body: request — Dokument | Erstellt oder speichert die Metadaten des Dokuments und gibt das Dokument zurück. |
POST /documents/files | documents | body: request — Dokumentdatei | Registriert eine in Magento Storage vorhandene Datei (Name, Pfad, MIME, Größe), sendet keine Binärdaten. |
GET /documents/:documentId/files?companyId=&websiteId= | documents | path: documentId; query: companyId, websiteId | Tabelle der Dateimetadaten des Dokuments. |
GET /documents/:documentId/sync-logs | documents | path: documentId | Synchronisationslogs des Dokuments; für administrative Integration vorgesehen. |
5.7. Kreditlimit und Zahlungsbedingungen
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /companies/:companyId/credit/status?websiteId=¤cy= | credit_limits | path: companyId; query: websiteId, currency | Limitstatus, Nutzung und verfügbarer Betrag der Firma. |
POST /credit-limits | credit_limits | body: request — Limit | Erstellt/aktualisiert das Firmenlimit und gibt das Limit zurück. |
POST /credit/exposures | credit_limits | body: request — Exposure | Reserviert eine Limit-Exposure für die Quelle (z. B. Bestellung) und gibt sie zurück. |
POST /credit/exposures/:exposureId/release | credit_limits | path: exposureId; optional body: message | Gibt die Exposure frei; gibt ihren Status zurück. |
GET /payment-terms?websiteId= | credit_limits | query: websiteId | Tabelle der aktiven/bekannten Zahlungsbedingungen der Website. |
POST /payment-terms | credit_limits | body: request — Zahlungsbedingungen | Speichert Zahlungsbedingungen und gibt sie zurück. |
5.8. Genehmigungsworkflow
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /companies/:companyId/approval/rules?websiteId=¤cy= | approvals | path: companyId; query: websiteId, optional currency | Genehmigungsregeln der Firma für Kanal/Währung. |
POST /approval/rules | approvals | body: request — Regel | Erstellt/aktualisiert eine Schwellenregel und gibt sie zurück. |
GET /approval/rules/:ruleId/approvers | approvals | path: ruleId | Tabelle der zugewiesenen Genehmiger, in der Reihenfolge sortOrder. |
POST /approval/approvers | approvals | body: request — Genehmiger | Speichert die Zuordnung des Kunden als Genehmiger. |
GET /companies/:companyId/approval/required?websiteId=&grandTotal=¤cy= | approvals | path: companyId; query: websiteId, grandTotal, currency | Boolean: ob der Betrag eine Genehmigung erfordert. |
POST /approval/requests | approvals | body: request — Genehmigungsantrag | Erstellt einen Request für eine Bestellung und gibt ihn zurück. |
GET /companies/:companyId/approval/requests?websiteId=&status= | approvals | path: companyId; query: websiteId, optional status | Tabelle der Genehmigungsrequests der Firma. |
POST /approval/requests/:requestId/approve | approvals | path: requestId; body: request — Entscheidung | Genehmigt den Request; gibt seinen aktuellen Status zurück. |
POST /approval/requests/:requestId/reject | approvals | path: requestId; body: request — Entscheidung | Lehnt den Request ab; gibt seinen aktuellen Status zurück. |
POST /approval/requests/:requestId/cancel | approvals | path: requestId; body: request — Entscheidung | Storniert den Request; gibt seinen aktuellen Status zurück. |
GET /approval/requests/:requestId/decisions | approvals | path: requestId | Entscheidungshistorie für den Request. |
5.9. B2B-Kontext von Bestellungen
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /orders/:orderId/b2b-context | orders | path: orderId | B2B-Kontext einer einzelnen nativen Magento-Bestellung (z. B. Firma, Genehmigungsstatus, Limit, Export). |
GET /companies/:companyId/orders/b2b-context?websiteId=&approvalStatus= | orders | path: companyId; query: websiteId, optional approvalStatus | Tabelle der Bestellkontexte der Firma, optional nach Genehmigungsstatus gefiltert. |
5.10. RFQ und kommerzielle Angebote
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /companies/:companyId/quotes?websiteId=&status= | quotes | path: companyId; query: websiteId, optional status | RFQ und Angebote der Firma, optional nach Status. |
POST /quotes | quotes | body: request — RFQ | Erstellt ein RFQ im Entwurf und gibt es zurück. Positionen über einen separaten Endpoint hinzufügen. |
GET /quotes/:quoteId | quotes | path: quoteId | Details des RFQ/Angebots. |
GET /quotes/:quoteId/items | quotes | path: quoteId | Tabelle der RFQ-Positionen. |
POST /quotes/items | quotes | body: request — RFQ-Position | Fügt SKU und Menge, optional Wunsch-/Angebotspreis sowie Kommentar hinzu. |
GET /quotes/:quoteId/comments | quotes | path: quoteId | RFQ-Kommentare. Der Kunde sieht nur als sichtbar markierte Kommentare. |
POST /quotes/comments | quotes | body: request — RFQ-Kommentar | Fügt eine Nachricht hinzu; authorType und visibleForCustomer bestimmen Autor und Sichtbarkeit. |
GET /quotes/:quoteId/history | quotes | path: quoteId | Historie von Statusänderungen und RFQ-Ereignissen. |
POST /quotes/:quoteId/submit | quotes | path: quoteId; body: request — RFQ-Entscheidung | Übergibt ein RFQ im Entwurf zur Kalkulation. |
POST /quotes/:quoteId/make-offer | quotes | path: quoteId; body: request — RFQ-Entscheidung | Der Vertriebsmitarbeiter erstellt/übermittelt ein Angebot; vor dem Aufruf Preise der Positionen festlegen. |
POST /quotes/:quoteId/accept | quotes | path: quoteId; body: request — RFQ-Entscheidung | Akzeptiert das aktuelle Angebot. Erstellt in diesem Vertrag keine REST-Bestellung. |
POST /quotes/:quoteId/reject | quotes | path: quoteId; body: request — RFQ-Entscheidung | Lehnt Angebot/RFQ ab. |
POST /quotes/:quoteId/cancel | quotes | path: quoteId; body: request — RFQ-Entscheidung | Storniert das RFQ, sofern der aktuelle Status dies zulässt. |
5.11. Integrationsprofile und -jobs
| Methode und Endpoint | ACL | Eingabe | Ergebnis und Verwendung |
|---|---|---|---|
GET /integrations/profiles?websiteId=&systemType= | system_integrations | query: websiteId, optional systemType | Integrationsprofile für die Website. |
POST /integrations/profiles | system_integrations | body: request — Integrationsprofil | Speichert ein ERP-/PIM-/WMS-Profil usw. und gibt es zurück. |
POST /integrations/mappings | system_integrations | body: request — Zuordnung | Speichert das Paar lokale ID ↔ externe ID. |
GET /integrations/mappings/local?websiteId=&systemType=&entityType=&localId= | system_integrations | query: alle Parameter erforderlich | Sucht die Zuordnung anhand der Magento-Kennung. |
GET /integrations/mappings/external?websiteId=&systemType=&entityType=&externalId= | system_integrations | query: alle Parameter erforderlich | Sucht die Zuordnung anhand der Kennung des externen Systems. |
POST /integrations/jobs | system_integrations | body: request — Job | Veröffentlicht einen Job zur Ausführung; idempotencyKey identifiziert die Geschäftsoperation. |
GET /integrations/jobs?websiteId=&status= | system_integrations | query: websiteId, optional status | Tabelle der Integrationsjobs. |
GET /integrations/jobs/:jobId | system_integrations | path: jobId | Status und Details eines einzelnen Jobs. |
POST /integrations/jobs/:jobId/process | system_integrations | path: jobId | Verarbeitet den Job und gibt seinen aktuellen Status zurück. |
POST /integrations/jobs/:jobId/retry | system_integrations | path: jobId | Wiederholt den Job nach einem Fehler gemäß seinem Versuchslimit. |
GET /integrations/jobs/:jobId/logs | system_integrations | path: jobId | Ausführungslogs des Jobs. |
GET /integrations/jobs/:jobId/errors | system_integrations | path: jobId | Domain-/technische Fehler des Jobs. |
6. Aufrufbeispiele
export BASE_URL='https://b2b.example.com/rest/V1'export TOKEN='token-przekazany-przez-administratora'export WEBSITE_ID=1 COMPANY_ID=10 SKU='B2B-SKU-001' CURRENCY='PLN'# Test dostępu i konfiguracji kanałucurl -sS '$BASE_URL/kowal-b2b/websites/$WEBSITE_ID/config' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Cena kontraktowa firmy dla konkretnej ilościcurl -sS '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/products/$SKU/price?websiteId=$WEBSITE_ID¤cy=$CURRENCY&qty=5' \ -H 'Authorization: Bearer $TOKEN' -H 'Accept: application/json'# Walidacja koszyka po SKUcurl -sS -X POST '$BASE_URL/kowal-b2b/companies/$COMPANY_ID/quick-order/validate' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'websiteId':1,'currency':'PLN','items':[{'sku':'B2B-SKU-001','qty':5}]}'# Utworzenie RFQcurl -sS -X POST '$BASE_URL/kowal-b2b/quotes' \ -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \ --data '{'request':{'websiteId':1,'companyId':10,'customerId':25,'title':'Dostawa kwartalna','currency':'PLN','externalId':'ERP-RFQ-2026-001'}}'7. Empfohlene Integrationsszenarien
Kauf nach SKU
- Lesen Sie die Website-Konfiguration aus und speichern Sie die übermittelte
websiteId,companyIdund Währung. - Verwenden Sie quick order zur Sammelvalidierung von SKU, Menge, Sichtbarkeit und Verfügbarkeit.
- Rufen Sie für akzeptierte Positionen den Preis aus
pricemit dem richtigenqtyab. - Erstellen Sie ein RFQ, fügen Sie Positionen hinzu und senden Sie sie über
submit, wenn der Kauf ein Angebot erfordert. - Verfolgen Sie Status und Historie des RFQ; gehen Sie nach der Annahme gemäß dem vereinbarten Magento-Bestellprozess vor, da
V1keinen Endpoint zur Erstellung einer order bereitstellt.
Dokumente und Abrechnung
- Rufen Sie die Dokumentenliste der Firma ab, optional gefiltert nach
documentType. - Rufen Sie für das ausgewählte Dokument Metadaten und Dateiliste ab; der Dateipfad ist nicht automatisch eine öffentliche URL — die Art des Abrufs der Binärdatei stimmen Sie mit dem Shop-Administrator ab.
- Lesen Sie den Limitstatus vor dem Kaufprozess aus; nur eine Integration mit ACL
credit_limitskann ihn verwalten.
Asynchrone Operationen
- Speichern Sie das Integrationsprofil und die ID-Zuordnungen.
- Veröffentlichen Sie einen Job mit einem geschäftlichen
idempotencyKeyund bewahren Sie diejobIdauf. - Lesen Sie Job sowie Logs/Fehler aus;
retryrufen Sie erst nach Analyse des Fehlers und Beseitigung seiner Ursache auf.
8. Abnahmeliste vor der Produktion
- Das Token hat ausschließlich die erforderlichen ACL und ist kein Administrator-Token, das von der UI verwendet wird.
- Der Integrator behandelt
401,403,404, Validierung422, Konflikt409und Timeouts korrekt. - Jeder Request im B2B-Kontext übermittelt die richtige
websiteId, und Firmendaten verwenden die korrektecompanyId. - Preise, Sichtbarkeit und Verfügbarkeit werden vor Erstellung des Kaufprozesses geprüft.
- Die Erstellung einer Firma verwendet
Idempotency-Key; Integrationsjobs haben einen stabilenidempotencyKeyim Body. - Logs enthalten keine Tokens oder sensiblen Daten, und das Supportverfahren übermittelt
trace_id. - Tests wurden in der Testumgebung mit einer Firma durchgeführt, die eine aktive Beziehung zur B2B-Website hat.
9. Kompatibilität
Der Vertrag ist über /V1 versioniert. Die Erweiterung der Antwort um neue Felder ist kompatibel; der Integrator sollte unbekannte Felder tolerieren. Eine Änderung, die ein Feld, die Bedeutung eines Feldes oder einen Endpoint entfernt, erfordert eine neue API-Version. Bei Abweichungen zwischen Dokument und laufender Installation ist der aktive Vertrag webapi.xml der jeweiligen Modulversion maßgeblich.
Installationsanleitung für das Modul
Installation und Konfiguration der Kowal B2B Suite
Dieses Handbuch richtet sich an Personen, die die Kowal B2B Suite gekauft haben und sie in einer bestehenden Magento Open Source Installation in Betrieb nehmen sollen. Es führt durch zwei Schritte:
- technische Installation— durchgeführt durch einen Developer oder Serveradministrator;
- geschäftliche Konfiguration— durchgeführt im Magento-Panel durch den Shop-Administrator.
Erstellen Sie vor Beginn ein Backup der Magento-Datenbank und -Dateien. Wir empfehlen, die erste Inbetriebnahme in einer Testumgebung durchzuführen und erst danach in die Produktion zu übernehmen.
1. Lieferumfang und Voraussetzungen
Die Kowal B2B Suite wird als Composer-Paketkowal/metapackage-b2b-suitebereitgestellt. Sie enthält B2B-Module sowie das Themefrontend/Kowal/b2bverwenden.
Anforderungen
| Element | Anforderung |
|---|---|
| Magento | Magento Open Source 2.4.9 |
| PHP | 8.3 |
| Composer | Composer 2 |
| Serverzugriff | SSH und Ausführungsmöglichkeit fürbin/magento |
| Magento | funktionierende Funktionen für Katalog, Kunden, Checkout, Sales, MSI und Cron |
Schreibmöglichkeit invar/durch den PHP-Prozess |
Von Kowal erhalten Sie:
- die Adresse des privaten Composer-Repositorys — im Folgenden
REPOSITORY_URL; - den Benutzernamen oder die Zugriffskennung —
USERNAME; - das Zugriffstoken —
ACCESS_TOKEN; - den zulässigen Versionsbereich des Pakets.
Speichern Sie das Token nicht im Git-Repository, in Tickets oder in der Shell-Historie, die mit anderen Personen geteilt wird.
2. Technische Installation
Führen Sie alle Befehle im Stammverzeichnis der bestehenden Magento-Installation aus, als Benutzer mit Zugriff auf die Dateien und auf den Befehlbin/magentoverwenden.
2.1. Vorbereitung
- Stellen Sie sicher, dass Magento vor der Änderung korrekt funktioniert.
- Dokumentieren Sie den Deployment-Stand und erstellen Sie ein Backup der Datenbank sowie der Verzeichnisse
app/etc,pub/mediaundvarverwenden. - Aktivieren Sie in der Produktion für die Dauer der Aktualisierung den Maintenance-Modus:
bin/magento maintenance:enable
2.2. Privates Repository ergänzen
Fügen Sie das Composer-Repository von Kowal hinzu und konfigurieren Sie die erhaltenen Zugangsdaten.
Die Zugangsdaten für das Composer-Repository – E-Mail-Adresse des Kunden und Lizenz-Token – erhalten Sie nach dem Kauf per E-Mail. Sie sind nach der Anmeldung auf kowal.storeebenfalls im Kundenkonto verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch das erhaltene Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.
composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
Composer speichert Zugangsdaten in der Regel in einer lokalenauth.json; fügen Sie diese Datei nicht zu Git hinzu.
2.3. Paket installieren
Installieren Sie die Version, die mit der Lizenz übermittelt wurde. Für die aktuelle Paketlinie sieht ein Beispielbefehl wie folgt aus:
composer require kowal/metapackage-b2b-suite:^0.2 --with-all-dependencies
Führen Sie nach dem Herunterladen der Abhängigkeiten die Aktualisierung des Magento-Schemas und der Konfiguration aus:
bin/magento setup:upgrade
bin/magento cache:clean
Im Produktionsmodus führen Sie zusätzlich aus:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f pl_PL en_US
bin/magento cache:flush
Verwenden Sie nur die Locales, die im Shop aktiv sind. Wenn die Installation einen anderen Deployment-Prozess verwendet, nehmen Sie die oben genannten Befehle in dessen Standardverfahren auf.
2.4. Installation prüfen
bin/magento module:status | grep Kowal
bin/magento indexer:status
Im Administrationspanel sollten das MenüB2Bsowie der TabStores > Configuration > Kowal > B2Berscheinen. Wenn sie fehlen, prüfen Sie das Ergebnis vonsetup:upgrade, den Cache sowie die ACL-Rollen des Administratorbenutzers.
2.5. PDF-Dateiberechtigungen
Die von B2B generierten PDFs verwenden mPDF und Verzeichnisse untervar/, daruntervar/tmp/kowal_b2b_mpdfsowievar/kowal_b2b_documents. Der PHP-Prozess muss diese erstellen und beschreiben können. Fehlende Berechtigungen äußern sich durch einen Fehler bei der Dokument- oder PDF-Erzeugung.
Deaktivieren Sie nach Abschluss des Produktionsdeployments den Maintenance-Modus:
bin/magento maintenance:disable
3. B2B-Shopstruktur konfigurieren
3.1. Website und Store View
Die Suite arbeitet im Scopewebsiteund nicht global. Sie können B2C und B2B in derselben Magento-Installation betreiben, B2B sollte jedoch in einer separaten Website oder in einer bewusst ausgewählten Website für den Firmenvertrieb laufen.
- Definieren Sie unterStores > Settings > All Storesdie B2B-Website, ihren Store und die Store View aus.
- Merken Sie sich die
website_id— sie wird von Firmen, Preisen, Dokumenten, API und Integrationen verwendet. - Definieren Sie unterContent > Design > Configurationdas Theme
frontend/Kowal/b2bnur der B2B Store View zu. - Prüfen Sie, ob aktive Währungen, Steuern, Versandmethoden und Zahlungsmethoden für denselben Scope konfiguriert sind.
Weisen Sie das B2B-Theme keiner B2C Store View zu, wenn Sie deren Darstellungsebene nicht ändern möchten. Die reine Installation der Module aktiviert die B2B-Logik nicht für alle Websites.
3.2. B2B aktivieren
- Öffnen SieStores > Configuration > Kowal > B2Bverwenden.
- Wählen Sie im Scope-Umschalter die richtigeWebsiteverwenden.
- Setzen Sie im AbschnittGeneraldie OptionEnable B2Bauf
Yesverwenden. - Für die Dauer des Deployments können SieDebug Modeaktivieren; deaktivieren Sie ihn nach den Tests.
- Legen Sie im Scope Default Config den Aufbewahrungszeitraum für Logs fest.
- Speichern Sie die Konfiguration und leeren Sie den Cache.
Nach der Aktivierung werden alle Store Views, die zu dieser Website gehören, als B2B behandelt. Eine Firma ohne aktive Beziehung zu dieser Website erhält keinen Zugriff darauf.
3.3. Verkäuferdaten
Ergänzen Sie die Daten des verkaufenden Unternehmens unterStores > Configuration > General > Store Information: Name, Adresse, Telefon und Umsatzsteuer-ID. Sie werden in Dokumenten und RFQ-PDFs verwendet. Ergänzen Sie außerdem die allgemeine E-Mail-Adresse des Absenders in der Sales Emails-Konfiguration sowie das E-Mail-Logo, wenn es im PDF erscheinen soll.
4. Ersten B2B-Kunden konfigurieren
Verwenden Sie die folgende Reihenfolge für jede Firma. So vermeiden Sie Situationen, in denen der Kunde zwar ein Konto hat, aber das Angebot nicht sieht oder den Checkout nicht durchlaufen kann.
4.1. Unternehmen, Personen und Adressen
- Öffnen SieB2B > Companiesund erstellen Sie eine Firma.
- Geben Sie Name, Umsatzsteuer-ID, externe Kennung (falls die Firma mit ERP synchronisiert wird), den Status
Activesowie die Zuordnung zur B2B-Website an. - Fügen Sie einen Firmenbenutzer hinzu oder weisen Sie einen bestehenden Magento-Kunden zu. Weisen Sie ihm die passende Rolle zu und aktivieren Sie die Zuordnung.
- Definieren Sie unterB2B > Company Addressesdie Firmenadressen hinzu; markieren Sie die Standard-Rechnungs- und Versandadresse für die B2B-Website.
- Definieren Sie unterB2B > Company Contactseinen aktiven Hauptkontakt mit E-Mail und Telefon hinzu.
Die Rechnungsadresse und der Hauptkontakt werden ebenfalls in RFQ-PDFs verwendet. Fehlende Daten blockieren das PDF nicht, das Dokument ist jedoch weniger vollständig.
4.2. Unternehmensrollen
Vergeben Sie Benutzern nur die benötigten Berechtigungen. Eine typische Aufteilung ist:
| Rolle | Beispielaufgaben |
|---|---|
| Firmenadministrator | Benutzer, Rollen, Adressen, Dokumente und Firmenhistorie |
| Einkäufer | Katalog, Schnellbestellung, Warenkorb, RFQ und Bestellungen |
| Genehmiger | Entscheidungen im Genehmigungsworkflow |
| Buchhaltung | Dokumente und Abrechnungsinformationen |
Testen Sie ein Konto jedes Typs, insbesondere die Berechtigung zum Aufgeben und Genehmigen von Bestellungen. Verwenden Sie nicht ein gemeinsames Konto für die gesamte Firma.
5. Angebot, Preise und Checkout
5.1. Katalog und Preise
- Stellen Sie sicher, dass die Magento-Produkte der B2B-Website zugewiesen, aktiv und mit korrekten MSI-Daten versehen sind.
- Konfigurieren Sie Preislisten oder Vertragspreise für die Firma im BereichB2B > Pricing(Price Lists, Price List Assignments oder Contract Prices).
- Konfigurieren Sie die Regeln für die Katalogsichtbarkeit der Firma gemäß dem implementierten Berechtigungsmodell und prüfen Sie anschließend die Sichtbarkeit im Kundenkonto.
- Testen Sie im Firmenkonto: Suche nach SKU, Produktsichtbarkeit und Preis für die Menge
1sowie für eine Mengenstaffel.
Der B2B-Preis hängt von Firma, Website, Währung und Menge ab. Ein in B2C sichtbares Produkt muss für einen B2B-Kunden nicht verfügbar sein.
5.2. Versand und Zahlung
- Aktivieren Sie die erforderlichen Versand- und Zahlungsmethoden in der Standardkonfiguration von Magento für die B2B Store View.
- Definieren Sie unterB2B > CheckoutRegeln für verfügbare Methoden für Firma/Website hinzu, wenn Sie die Auswahl einschränken möchten.
- Führen Sie einen Warenkorbtest mit den Standardadressen der Firma durch.
Wenn die Erstellung einer Bestellung aus RFQ automatisch auf Administratorseite funktionieren soll, muss die Firma eindeutige Standardadressen sowie eine aktive Zahlungs- und Versandmethode haben. Andernfalls lädt die Suite die Daten in das native Backend Order Create, wo der Administrator fehlende Elemente ergänzt.
5.3. Limits und Freigaben
Diese Funktionen sind optional, sollten jedoch konfiguriert werden, bevor sie für Kunden aktiviert werden.
- Definieren Sie unterB2B > Credit > Payment TermsZahlungsbedingungen hinzu.
- Definieren Sie unterB2B > Credit > Credit LimitsLimit, Währung, Status und Zahlungsbedingung zu.
- Definieren Sie unterB2B > Approvals > Ruleseine Betragsgrenzenregel für Firma und Website.
- Definieren Sie unterB2B > Approvals > ApproversGenehmiger zu.
- Testen Sie den Warenkorb unterhalb und oberhalb der Grenze und prüfen Sie, ob die Entscheidung des Genehmigers den weiteren Prozess ändert.
6. Dokumente, PDF und RFQ
6.1. Magento-Dokumente
Definieren Sie unterStores > Configuration > Kowal > B2B > Documentsdie Dokumentenquelle und entscheiden Sie, welche Dokumente automatisch generiert werden sollen: Auftragsbestätigungen, Rechnungen, Lieferscheine und Gutschriften. Legen Sie außerdem den Zielstatus des Dokuments fest.
Definieren Sie unterB2B > Documents > PDF Templatesfest:
- prüfen Sie die aktive Vorlage für jeden Typ und jede Website;
- führen Sie eine Vorschau aus;
- passen Sie HTML/CSS nur dann an, wenn Sie eine Person haben, die Magento-Templates und mPDF-CSS kennt;
- generieren Sie eine Testrechnung oder Bestätigung und prüfen Sie den Download aus dem Firmenkonto.
6.2. RFQ und PDF-Angebot
- Definieren Sie unterB2B > Quotes > RFQein Test-RFQ für eine aktive Firma und einen aktiven Benutzer.
- Fügen Sie eine für die Firma sichtbare SKU, Menge und Angebotspreis hinzu.
- Legen Sie die Gültigkeitsfrist fest, senden Sie das Angebot an den Kunden und generieren Sie das PDF.
- Prüfen Sie die Kundenvariante: Verkäufer-/Käuferdaten, Positionen, Preis, Summe und Gültigkeitsfrist.
- Prüfen Sie die Administratorvariante: zusätzlich Vertriebsnotizen, Kommentare, Historie und interne Informationen zu den Positionen.
Das Kunden-PDF darf keine Notizen des Vertriebsmitarbeiters oder interne Statushistorie enthalten.
7. Schnellbestellungen, Importe und Integrationen
Schnellbestellungen
Definieren Sie unterB2B > Quick Order > Debug SKUdie ListeSKU,qtyfür Firma, Website und Währung. Erstellen Sie anschließend eine Einkaufsliste und testen Sie deren Verwendung durch den Kunden im Storefront.
Import und Export
Definieren Sie unterB2B > Import/Exportein Profil erst, nachdem die Datenquelle festgelegt wurde. Die Profilkonfiguration ist ein JSON-Objekt und muss Dateipfade enthalten, die auf dem Magento-Server verfügbar sind. Starten Sie den Import zunächst im Testmodus und analysieren Sie Job und Logs.
API-Integrationen
Legen Sie vor dem Erstellen eines Integrationstokens den Datenumfang und den Verantwortlichen für die Synchronisierung fest. Verwenden Sie für jedes ERP, PIM, WMS oder jede Middleware eine separate Magento-Integration und vergeben Sie ausschließlich die benötigten B2B-ACL. Die vollständige Liste der Endpoints, Tokens und Sicherheitsregeln finden Sie in derAPI-Dokumentation für Integratorenverwenden.
8. Abnahmecheckliste
Bestätigen Sie vor dem Produktionsstart:
- ☐ Die Kowal-Module sind aktiv, cron läuft, Cache und Indizes sind korrekt.
- ☐ B2B ist ausschließlich für die richtige Website aktiviert.
- ☐ Das B2B-Theme ist ausschließlich der B2B Store View zugewiesen.
- ☐ Die Testfirma hat den Status Active, einen Benutzer, eine Rolle, einen Kontakt und Standardadressen.
- ☐ Das Testprodukt ist aktiv, der Website zugewiesen, für die Firma sichtbar und hat einen korrekten B2B-Preis.
- ☐ Der Kunde kann sich anmelden, nach SKU suchen, quick order verwenden und das Produkt in den Warenkorb legen.
- ☐ Der Checkout zeigt nur zulässige Versand- und Zahlungsmethoden an.
- ☐ Limit und Genehmigungsregel funktionieren gemäß der Firmenrichtlinie, sofern diese Funktionen verwendet werden.
- ☐ Dokument und RFQ-PDF werden generiert und sind ausschließlich für die richtige Firma verfügbar.
- ☐ RFQ kann gesendet, akzeptiert und in den Prozess zur Auftragserstellung übergeben werden.
- ☐ Integrationen haben separate Tokens und eingeschränkte ACL, sofern sie verwendet werden.
9. Häufige Probleme
| Symptom | Was prüfen? |
|---|---|
| Es gibt kein B2B-Menü | setup:upgrade, Modulstatus, Cache und Administrator-ACL. |
| Firma oder Kunde sieht B2B nicht | Ob B2B für die richtige Website aktiv ist und ob die Firma eine aktive Beziehung zu dieser Website hat. |
| Produkt ist nicht sichtbar oder hat keinen Preis | Produktzuweisung zur Website, Aktivität der SKU, MSI-Daten, Katalogregeln, Firmenpreis, Währung und Menge. |
| Versand- oder Zahlungsmethode fehlt | Standardkonfiguration von Magento, Scope der B2B Store View und B2B Checkout-Regeln. |
| PDF wird nicht erstellt | Aktive PDF-Vorlage, mPDF-Paket, Berechtigungen fürvar/, Verkäuferdaten und Magento-Logs. |
| RFQ erstellt die Bestellung nicht automatisch | Standardadressen der Firma, eindeutige Zahlung und Lieferung; verwenden Sie in den übrigen Fällen Backend Order Create. |
API gibt403 |
Dem Integrationstoken fehlt die erforderliche ACL; verwenden Sie in externen Anwendungen keinen Administratortoken. |
Geben Sie bei Supportanfragen Magento-Version, Paketversion, Reproduktionsschritte, Ereigniszeit, sicher anonymisierte Protokolle und gegebenenfallstrace_idan. Senden Sie keine Tokens oder Passwörter.
10. Paket aktualisieren
- Lesen Sie die von Kowal übermittelten Versionsinformationen.
- Führen Sie die Aktualisierung zuerst in der Testumgebung durch.
- Erstellen Sie ein Backup, führen Sie
composer update kowal/metapackage-b2b-suite --with-all-dependencies,bin/magento setup:upgradeund in der Produktion zusätzlich die DI-Kompilierung und das Deployment statischer Inhalte aus. - Wiederholen Sie die Abnahme-Checkliste mit besonderem Fokus auf Preise, Checkout, Dokumente und Integrationen.
Aktualisieren Sie das Paket nicht durch manuelles Kopieren von Dateien nachapp/code; dies verursacht Probleme mit Composer und erschwert späteren Support.