Xentral Adobe Commerce/Magento Connector

1. Vorbereitung
2. Erstellen einer neuen Integration in Magento
3. Weitere Magento Einstellungen
4. Informationen für die Xentral-Konfiguration sammeln
5. Einrichtung in Xentral
6. Installation der Connect-App (SCMA)
7. Integration erstellen
8. Artikelzuordnung
9. Workflows konfigurieren
10. Journal verwenden
11. FAQ

Diese Dokumentation richtet sich an alle Xentral-Anwender, die einen bestehenden Magento- oder Adobe Commerce 2.4.x Online-Shop anbinden möchten. Dabei ist es unerheblich, ob Shopbetreiber die bisherige Legacy-Schnittstelle bereits nutzen oder einen neuen Magento-Shop mit ihrem Xentral ERP integrieren möchten. Die Umstellung auf die hier dokumentierte neue Schnittstelle mit der einheitlichen Xentral Connect Technologie wird jedem Nutzer empfohlen. Neben dem zukünftigen EOL der Legacy-Schnittstelle, bietet die neue Technologie mehr Stabilität, Performance und eine aktive Entwicklung neuer Features.

Hinweis: Die Synchronisierung von Beständen mit mehreren Lagerplätzen wird erst in Zukunft unterstützt (Multi Inventory).

Hinweis: Wenn Sie die Bestandssynchronisierung verwenden und dabei offene Aufträge von Ihren Beständen subtrahieren möchten (SCMA Option: “Offene Aufträge beachten”), müssen Sie ggf. selber Shipments/Lieferscheine im Shop anlegen. Magento reserviert automatisch Bestände aus offenen Bestellungen, die durch das Anlegen von Shipments/Lieferscheinen wieder aufgelöst werden. Wenn Sie sich für die Strategie entschieden haben, dass der Auftragsstatus an Magento zurückgemeldet wird, sobald Trackinginformationen verfügbar sind, erstellt die Schnittstelle automatisch Shipments. Ansonsten müssen Sie diese Aufgabe manuell übernehmen.

Um API-Zugangsdaten für Magento zu erstellen, ist eine Integration notwendig. Die Integrationseinstellungen in der Magento Administration befinden sich unter System → Extensions → Integrations. Fügen Sie hier nun eine neue Integration hinzu. Der Name kann dabei frei gewählt werden, optionale Felder können zunächst leer bleiben. Im Abschnitt “API” kann entweder der Zugriff auf alle APIs gewährt werden.

Nach dem Anlegen der Integration muss diese noch autorisiert werden. Nach dem Autorisierungsschritt werden vier verschiedene Zugangsschlüssel angezeigt: Der Consumer Key, Consumer Secret, Access Token und Access Token Secret. Diese Werte sind relevant für die nachfolgende Verbindung von Xentral mit der Magento-Instanz.

Abschließend muss nun noch der Zugriff auf Magento über die API mit einem Access Token aktiviert werden. Dafür navigieren Sie nach Stores → Configuration → Services → OAuth → Consumer Settings und setzen die Einstellung “Allow OAuth Access Tokens to be used as standalone Bearer tokens” auf den Wert “Yes”. Beachten Sie, dass diese Option auf der Standardkonfigurationsebene gesetzt werden muss und nicht nur für einen einzelnen Store View.

Erforderliche Scopes für die API:

• Sales (Zum Abrufen der Aufträge)
• Catalog (Zum Synchronisieren der Produktdaten)
• Inventory (Zum Bestandssynchronisation)
• Stores → Settings → Configuration → Inventory Section, Stores → Inventory (Bestandssynchronisation)
• Stores → Attributes (Produktdatensynchronisation)
• Customers → Customer Groups (Kundengruppenspezifische Preise synchronisieren)

• Prüfen Sie die Währungseinstellungen unter Stores → Configuration → General → Currency Setup
  • Ihre Basiswährung muss mit ihrer Standardwährung in Xentral übereinstimmen (in den meisten Fällen EUR). Sollte Ihr Magentoshop verschiedene Währungen unterstützen, muss die Basiswährung weiterhin mit Xentral übereinstimmen und die Umrechnung von Magento verwendet werden.

• Prüfen Sie die Steuereinstellungen unter Stores → Configuration → Sales → Tax
  • Die Steuerklasse für den Versand und für Produkte muss auf “Taxable Goods” gesetzt sein
  • Die Einstellung “Tax calculation based on” muss auf “Total” gesetzt sein. Ansonsten kann es dazu kommen, dass Rabatte nicht korrekt in die Steuer einberechnet werden und schließlich Xentral Rechnungen von den Magento Auftragssummen abweichen.
  • Die Einstellung “Catalog Prices” sollte standardmäßig auf “Including Tax” sein. Sollten sie diesen Wert explizit auf “Excluding Tax” gesetzt haben, beachten Sie, dass sie bei der Konfiguration der Schnittstelle in Xentral im nächsten Schritt den Export von Nettopreisen aktivieren.
  • Shipping prices sollten ebenfalls “Including Tax” konfiguriert sein.
  • Setzen sie die Einstellung Apply customer Tax auf den Wert “After Discount” und Apply Discount on prices auf “Including Tax”. Ansonsten kann es zu Abweichungen bei Xentral Rechnungen mit Rabatten kommen.
  • Beachten Sie, dass das Land ihres Shops zu ihren Steuereinstellungen passen muss. Unter General → General → Store Information muss das Land mit Xentral übereinstimmen, ansonsten kommt es zu Abweichungen der Rechnungsbeträge.

Ihr Magento-Shop sollte nun bereit für die Anbindung an Xentral mit Connect sein. Die folgenden Informationen sollten Sie bereithalten, um die Einrichtung in Xentral schneller durchführen zu können.

• Aus dem vorherigen Einrichtungsschritt: Consumer Key, Consumer Secret, Access Token und Access Token Secret
• Codes der Zahlungsmethoden
• Verwendete Sprachcodes (im Normalfall nur DE)
• Codes der Versandmethoden
• Wenn sie Tracking-Informationen aus Xentral an Magento übertragen möchten: Codes der Versanddienstleister
• Optional: Attribut-Codes, wenn diese manuell auf Xentral Freifelder gemappt werden müssen

Die folgenden Anweisungen aus dem Xentral-Handbuch sind beispielhaft für Shopify angeführt, gelten aber genau so für Magento und können daher an dieser Stelle übernommen werden.

Xentral Connect Übersicht

Installation der Connect-App (SCMA)

Integration erstellen

Artikelzuordnung

Workflows konfigurieren

Journal verwenden

Produktdaten

• Meine Kategorien werden nur teilweise synchronisiert.
  • Da Kind-Kategorien verschiedener Eltern-Kategorien die gleichen Bezeichnungen verwenden könnten, kann die Zuordnung der Kategorien zwischen Xentral ERP und Shop nur über den vollständigen Pfad erfolgen. Achten Sie daher darauf, dass einem Produkt in Xentral auch die Kategorien aus dem Artikelbaum entlang des Pfades zugewiesen wurden. Darüber hinaus muss der Kategoriebaum in Magento mit dem Artikelbaum in Xentral übereinstimmen.
  • Beispiel: Ein Artikel aus der Kategorie “Mode → Sommer → Kleid” muss im Xentral Artikelbaum den Kategorien “Mode”, “Sommer” und “Kleid” zugeordnet sein. Nur so kann die Schnittstelle das Produkt auch in Magento diesen drei Kategorien zuordnen.

• Der Bestand in Magento ist geringer, als in Xentral
  • Prüfen Sie die Einstellungen der Magento-Integration in der Xentral-App. Diese befinden sich unter Workflows → Bestände. Achten Sie darauf, dass die Optionen offene Aufträge, Reservierungen, Lagerkorrektur- und Pseudo-Lagerwerte wie erwartet gesetzt sind.
  • Vergleichen Sie den Bestand und die “Salable Quantity” in Magento. Magento-interne Reservierungen werden erst durch erfolgreiche Shipments aufgelöst.

• Meine Freifelder werden nicht synchronisiert.
  • Führen Sie eine manuelle Zuordnung in der Workflow-Konfiguration in Xentral durch.
  • Ist die automatische Zuordnung der Freifelder aktiviert, müssen die entsprechenden Attribute in Magento existieren. Die automatische Zuordnung generiert den Attribut-Code anhand der Freifeldbezeichnung ohne Sonderzeichen, in Kleinbuchstaben und mit Unterstrichen getrennt. Beispiel: Zu dem Freifeld “Vinyl-Durchmesser” muss ein Attribut mit dem Code vinyl_durchmesser in Magento existieren.
  • Magento ignoriert automatisch unbekannte Attribute ohne dabei einen Fehler während des Produktimports zu melden.

• Meine SKU in Magento ist falsch. Ich verwende für diesen Vertriebskanal eigene Fremdnummern.
  • Prüfen Sie, ob Fremdnummern für die Schnittstelle in Xentral aktiviert sind und alle Artikel aus der Artikelfilterliste eine Fremdnummer mit der konfigurierten Bezeichnung enthalten.

• Bilder verbleiben nach dem Löschen in Xentral weiterhin in Magento.
  • Automatisches Löschen von Medien im Verkaufskanal wird derzeit nicht unterstützt.

• Das synchronisieren der Medien/Bilder dauert sehr lange.
  • Aus technischen Gründen müssen immer alle Mediendaten vollständig übertragen werden, auch wenn sich diese bereits im Shop befindet.

• Wie wird mit Stücklisten umgegangen?
  • Eine Abbildung auf Magento Bundled Products wird derzeit nicht unterstützt. Einzelne mit dem Shop synchronisierte Produkte können weiterhin Bestandteil von JIT-Stücklisten in Xentral sein.

Aufträge

• Wie werden meine Aufträge mit einer Packstation in der Versandadresse importiert?
  • Magento sowieso Xentral stellen im Standard keine besondere Unterstützung von DHL Packstationen bereit. Die Schnittstelle erkennt Packstationen durch das Schlüsselwort “Packstation” in Adresszeile 1 oder 2. Diese werden wie gewohnt als Versandadresse im Xentral-Auftrag übernommen.

• Warum erscheint die Ust.-ID nicht im Xentral-Auftrag?
  • Die Schnittstelle importiert die Umsatzsteuernummer nur nach Xentral sofern diese von Magento als gültig gekennzeichnet wurde.

• Meine Teillieferung aus dem Xentral Versandzentrum wurde nicht korrekt an Magento übertragen.
  • Teillieferungen aus dem Versandzentrum werden von dieser Schnittstelle (ebenso wie den anderen Xentral Connect Schnittstellen) derzeit technisch nicht unterstützt.
  • Um Teillieferungen an den Shop zu exportieren, teilen Sie die Aufträge im Vorfeld auf. Mehrere Teilaufträge in Xentral mit der selben Internet-Referenz (hier die Magento order number) werden als einzelne Shipments exportiert.

• Meine importierten Aufträge werden nicht für den Autoversand freigegeben, trotz erfolgter Bezahlung im Shop.
  • Zahlungsarten für den Autoversand können in der Schnittstellenkonfiguration (SCMA) unter Workflows → Aufträge festgelegt werden. Für alle weiteren Zahlarten muss eine manuelle Freigabe in Xentral erfolgen.

• Wie werden Kunden in Xentral im Zuge des Auftragsimports angelegt?
  • Die Strategie für die Kundenzuordnung in Xentral ist ebenfalls in der Konfiguration unter Workflows → Aufträge definiert.
  • Im Standard findet zuerst ein Abgleich der E-Mail-Adresse, dann der Adresszeilen statt, um Kunden zuzuordnen oder neu anzulegen.

• Die Tracking-Informationen werden nicht vollständig an den Shop übertragen.
  • Um Tracking-Informationen wie einen Link zur Sendungsverfolgung aus Xentral zu exportieren, ist ein Mapping der Versanddienstleister notwendig. Achten Sie darauf, dass die Versandart aus Xentral auf den verwendeten Versanddienstleister-Code für Magento gemappt ist. Dieser Code kann von dem Code der Versandart abweichen!

• Warum wird eine ältere Bestellung nicht exportiert?
  • Bestellungen, die älter als 5 Tage sind werden nicht mehr automatisch an Xentral übertragen. Grund hierfür ist die Fehleranfällig, da versehentliche sehr alte Bestellungen ungewollt aus dem Shop übertragen werden könnten. Soll eine Bestellung trotzdem in Xentral importiert werden, muss der Prozess im Journal manuell angestoßen werden: