Shopware Schnittstelle - Installation & Einrichtung

Mit dieser Schnittstelle können Sie Xentral mit Shopware verbinden, um Bestellungen von dort in Xentral zu importieren und Ihre im Shop verkauften Artikel in Xentral zu verwalten. Die Anbindung geschieht über eine API-Schnittstelle (Shopimporter).


Features der Schnittstelle

  • Aufträge aus Shopware importieren
  • Auftragsstatus bei Versand umstellen inkl. Meldung der Trackingnummer an Shopware
  • Artikel von Xentral nach Shopware exportieren oder von Shopware nach Xentral importieren
  • Artikeleigenschaften und -freifelder von Xentral zu Shopware epxortieren
  • Artikelbilder von Xentral nach Shopware exportieren
  • Synchronisation aktueller Lagerzahlen bei Bestandsänderungen
  • Crossselling

Anbindung zu Xentral

API Benutzer in Shopware erstellen

Zunächst muss in Shopware unter Einstellung → Benutzerverwaltung → Benutzer hinzufügen ein API-Benutzer angelegt werden. Dieser Benutzer wird speziell für die Xentral-Schnittstelle verwendet. Der API-Zugang muss auf aktiviert sein. Der Benutzername kann frei gewählt werden. :entwickler:shopware_api_benutzer_anlegen.png?nolink

Shopschnittstelle in Xentral anlegen

Unter Administration → Einstellungen → Online-Shops → NEU kann ein neuer Shop angelegt und das Modul Shopware ausgewählt werden. :entwickler:shopware_modul_auswaehlen.png?nolink Nachdem Sie Shopware ausgewählt haben, können Sie im nächsten Schritt die nötigen Daten für die Verbindung der beiden Systeme eintragen. Den API-Key haben Sie im Shopware-Backend beim Anlegen des Benutzers für die Schnittstelle erhalten.
  • API User: Benutzername des Benutzers in Shopware, der für die Schnittstelle angelegt wurde
  • API Key: Generierter API-Key aus der Benutzerverwaltung von Shopware
  • API URL: Shop-URL + /api, z.B. http://www.meinshop.de/api/
:entwickler:shopware_zugangsdaten_eintragen.png?nolink Sobald die Daten eingetragen wurden, können Sie die Verbindung zwischen beiden System über den Button Verbindung prüfen testen. Bei einer erfolgreichen Verbindung erhalten Sie die Meldung 'Verbindung: success' oder, falls die Schnittstelle Subshops erkennt, eine Auflistung der erkannten 'Subshops' und deren Subshop-IDs. :entwickler:shopware_verbindung_pruefen.png?nolink Praxistipp: Die API-URL können Sie direkt im Browser aufrufen und dort die Zugangsdaten eingeben. Als Ergebnis sollte folgende Rückmeldung erscheinen: success:false
message:Resource not found
Sollte die Verbindung fehlschlagen, kann ab Version 20.1 auch eine Authentifizierung über Digest durchgeführt werden. :entwickler:shopware_authentifizierung_ueber_digest.png?nolink

Aufträge zu Xentral importieren

Das Importieren von Bestellungen aus Online Shops wird in diesem Artikel beschrieben.

Alte Aufträge zu Xentral importieren

Die Shopware-Schnittstelle ermöglicht auch einen Import alter Aufträge vom Shop zu Xentral. Vor dem Import der Aufträge prüft Xentral ob es schon Aufträge mit dieser Shop-Bestellnummer gibt und holt diese Aufträge gegebenenfalls nicht nochmal ab. In der Shopschnittstelle in Xentral gibt es hierfür den Button Alte Aufträge importieren. :entwickler:shopware_alte_auftraege_importieren.png?nolink Sobald Sie auf diesen Button geklickt haben, können Sie im Dialogfenster anhand der Shopware-Bestellnummern angeben, welche alten Aufträge abgeholt werden sollen. :entwickler:shopware_alte_auftraege_dialogfenster.png?nolink
  • Nummer von → Älteste Belegnummer im Shop von der die Aufträge abgeholt werden sollen. Wenn leer gelassen, dann wird ab dem ältesten Auftrag abgeholt.
  • Nummer bis → Letzte Belegnummer im Shop bis zu der die Aufträge abgeholt werden sollen. Wenn leer gelassen, dann wird bis zum neuesten Auftrag abgeholt.
  • Auftrag abschließen → Der importierte Auftrag wird auf Status "abgeschlossen" gesetzt.
  • Stornierte Aufträge auch abholen → Holt auch die Aufträge ab, die im Shop den Status 'storniert' haben.
Über den Button Abholen wird der Import angestoßen. Der Import erfolgt dann nach und nach im Hintergrund. Dafür benötigen Sie den Prozessstarter Shopimport Alte Aufträge. Der Import kann je nach Menge der Aufträge eine längere Zeit in Anspruch nehmen. Wichtig: Bitte legen Sie vor dem Import alter Aufträge unter Administration → Backup einen Datenbank-Snapshot an, damit Sie gegebenenfalls nach dem Import wieder auf den alten Datenbestand zurückspringen können.

Demo- und Testfunktionen

Testlauf: Einzelne Aufträge von Shopware abholen

Vom Shop können auch gezielt einzelne Aufträge direkt nach der Auftragsnummer in Shopware abgeholt werden. Hierzu muss folgendes eingestellt werden: :entwickler:shopware_einzelner_auftrag_importieren.png?nolink
  • Abholmodus: Ab Nummer (Status)
  • ab Nummer: Bestellnummer (bei Bestellnummern die Buchstaben in der Zeichenfolge enthalten die ID der Bestellung) eingeben
  • Nur 1 Auftrag pro Anfrage: Haken setzen
Praxistipps: Der Shopstatus und in manchen Fällen auch der Zahlstatus des Auftrags muss in Shopware offen sein, damit der Auftrag zu Xentral importiert werden kann. Falls Einstellungen in der Shopschnittstelle das Abholen verhindern, ist es mitunter schneller direkt über die Shopware-Stapelverarbeitung Aufträge umzustellen (Bestellstatus → "offen"). Diese Aufträge werden dann beim Import abgeholt und der Status wird durch die Schnittstelle in Shopware von "offen" auf "in Bearbeitung" umgestellt. Im Abholmodus "ab Nummer" kann gezielt ein bestimmter Auftrag abgeholt werden. Anderweitig wäre nur die Abholung des ältesten, offenen Auftrags möglich. Zusätzlich ist zu beachten, dass bei einem Shop, in dem die Bestellnummern nicht aus alphanumerischen Zeichen bestehen, die Abholung ab Nummer automatisch auf die ID des Datensatzes der Bestellung umgestellt wird bzw. umgestellt werden muss.

Sonderfunktionen

Subshops

Falls Sie in Shopware verschiedene Subshops haben, können Sie diese im Tab Subshop mappen. Subshops werden z.B. für die Trennung nach Sprache oder Domain (z.B. meinshop.de und meinshop.com) verwendet. So könnte ein Mapping beispielsweise aussehen: :entwickler:subshops_shopware.png?nolink Wichtig: Bitte beachten Sie, dass das Subshop-Mapping nur klappt, wenn die Subshops in Shopware auch als Subshops eingestellt sind und nicht als Sprachshops!

Zahlungsstatus zurückmelden

Der Zahlungsstatus der Aufträge direkt an den Shop zurückzumelden. Dazu muss eine von diesen Anforderungen erfüllt sein:
  • Die verknüpfte Rechnung zum Auftrag wurde auf manuell bezahlt gesetzt.
  • Die verknüpfte Rechnung zum Auftrag wurde durch einen Zahlungseingang komplett beglichen.
Damit der Zahlungsstatus zurück gemeldet werden kann, braucht man den Prozessstarter Shop Rückmeldungen.

Artikelbilder exportieren

Die Shopware-Schnittstelle erlaubt den Export von Artikelbildern von Xentral zum Shop, wenn die Bilder in Xentral im Artikelstamm unter Dateien mit dem Stichwort Standard Artikelbild (Shopbild) angelegt wurden. Nur Bilder mit diesem Stichwort wrden an den Shop exportiert. Informationen über den Export von Artikelbildern finden Sie in diesem Artikel. Wichtig: Die Shopware-API akzeptiert unter Umständen keine Dateinamen mit Sonderzeichen oder Punkten (.), daher muss ggf. der Dateiname der Bilder angepasst werden, damit der Export funktioniert.

Versandkostenmapping von Shopware

Die Versandkosten werden automatisch nach Xentral mit importiert.
In Shopware können die Versandkosten ab einem bestimmten Einkaufsbetrag auf portofrei gesetzt werden.
Nach Xentral werden die Aufträge mit Portokosten ganz normal mit einem Portoartikel und dessen Preis importiert.
Portofreie Bestellungen werden mit dem Portoartikel importiert, jedoch ist dieser mit 0,00 EUR aufgeführt, somit ist die Bestellung für den Kunden portofrei.
:entwickler:versandkostenartikel_001.png?direct

Freifeldermapping und Export anderer Felder

Für Shopware ist es möglich über ein "direktes Mapping" von Artikel-Freifeldern spezifische Daten beim Artikelexport zu übertragen. Dazu werden beim Mapping der Freifelder, bzw. beim Namen der Eigenschaften die Textbausteine "mainArticle_", bzw. "mainDetail_" vorangestellt. Daten, die übertragen werden, werden über die API direkt an die jeweilige Stelle übergeben. Dadurch ist es möglich spezielle Felder anzusprechen für die es kein Gegenstück in Xentral gibt, oder die durch ein Plugin hinzugefügt wurden. Standardmäßig werden Freifelder zu den Attributen in Shopware übertragen. Das heißt wenn kein direktes Mapping verwendet wird, wird der Name des Freifeld es aus dem Mapping als Attributsname herangezogen und der Wert in dieses übertragen. Schema: :entwickler:screenshot_at_2018-10-24_11_36_56.png Beispiele: Werden Eigenschaften mit der Bezeichnung "mainArticle_filterGroup" kann das Eigenschaften-Set bei Shopware ansprechen. In Shopware muss für einen Artikel ein Eigenschaften Set angelegt sein, um auch Eigenschaften auswählen zu können. In Xentral wird das Eigenschaften Set dann hinterlegt und beim Export nach Shopware übergeben. Bei Varianten-/Matrixartikeln muss das Eigenschaften Set im Hauptartikel in Xentral angelegt sein. Wird eine Eigenschaft mit der Bezeichnung "mainArticle_notification" und einem Wert von "1" bei einem Artikel hinterlegt sorgt das dafür, dass das Feld für E-Mail-Benachrichtung für den Artikel in Shopware aktiviert wird: :entwickler:shopware_freifelder_export2.png Folgendes Mapping der Freifelder in den Importereinstellungen würde dafür sorgen, dass die Daten für die Grundpreisberechnung, sowie das Erscheinungsdaten, der Wert für Versandkostenfreiheit, sowie der Wert für die E-Mailbenachrichtigung übertragen wird: :entwickler:shopware_freifelder_export1.png
Mögliche Felder unter mainArticle
  • taxId - ID der Steuergruppe
  • priceGroupId - ID der Preisgruppe
  • filterGroup - Spezialfeld. Es ist möglich statt der Filtergruppenid auch die Bezeichnung der Filtergruppe anzugeben. Wenn die Bezeichnung mit der aus Shopware übereinstimmt kann so die Filtergruppenid ermittelt werden
  • filterGroupId - ID der Filtergruppe
  • configuratorSetId - ID des Konfiguratorsets
  • pseudoSales - Anzahl Pseudoverkäufe
  • priceGroupActive - Gibt an ob Preisgruppe aktiv ist
  • notification - E-Mailbenachrichtigung beim Artikel erlauben
  • availableFrom - Verfügbar von
  • availableTo - Verfügbar bis
Mögliche Felder unter mainDetail
  • additionalText - Zusatzinfo
  • stockMin - Mindestmenge
  • purchasePrice - Einkaufspreis
  • position - Position
  • minPurchase - Mindestverkaufsmenge
  • purchaseSteps - Verkaufsschritte
  • maxPurchase - Höchstverkaufsmenge
  • purchaseUnit - Verkaufseinheit
  • referenceUnit - Artikeleinheit
  • packUnit - ID Verpackungseinheit
  • shippingFree - Kostenloser Versand
  • releaseDate - Veröffentlichungsdatum
Hinweis: Sollte ein direktes Mapping für ein Feld verwendet werden das bereits beachtet wird (beispielsweise mainDetail_number für die Artikelnummer, oder mainArticle_name für den Namen) sticht der Wert aus der Eigenschaft bzw. dem Freifeld den eigentlich aus den Artikeldaten in Xentral zu übertragenden Wert. Ferner werden Eigenschaften nur dann als PropertyValues übertragen wenn der Artikel eine Filtergruppenid vorweisen kann. Ansonsten werden PropertyValues nicht übertragen. Alle möglichen Felder können direkt über die API eingesehen werden, unter: shopurl/api/articles/ArtikelIDdesArtikels.
Freifelder übersetzen
Wenn ein Subshopmapping existiert und eine Übersetzung der Freifelder für die entsprechende Sprache existiert, wird die Übersetzung an Shopware exportiert.

Eigenschaften zu Shopware übertragen

Ab Version 19.4 wurde die Möglichkeit, Xentral-Eigenschaften in die Attribute in Shopware zu übertragen, ausgebaut. Wird dem Namen einer Eigenschaft in Xentral articleAttribute_ vorangestellt, so können diese direkt als Attribute in Shopware exportiert werden. Beispiel: Die Eigenschaft Preishistorie soll wird nun als "articleAttribute_Preishistorie" angelegt (statt einfach nur "Preishistorie"). :entwickler:shopware_eigenschaften_export_1.png In der Freitextfeld-Verwaltung von Shopware wird das Feld mit dem dazu passenden Namen in der Tabelle articles_attributes angelegt. :entwickler:shopware_eigenschaften_export_2.png Der Wert der Eigenschaft wird beim Artikelexport von Xentral zu Shopware dann in das vorgesehene Feld übertragen. :entwickler:shopware_eigenschaften_export_3.png

Crossselling

In Verbindung mit der App Crossselling ist es möglich, Crossselling-Verknüpfungen zwischen zwei Artikeln in Xentral zu pflegen und zu Shopware zu übertragen. In der Crosselling App können Artikel hierzu bidirektional verknüpft werden. :entwickler:crossselling_fuer_shopware_bidirektional.png Wenn die Einstellungen so gespeichert werden, werden die Artikel in Shopware dem jeweils anderen als Zubehörartikel zugeweisen. :entwickler:shopware_crossselling_1.png :entwickler:shopware_crossselling_2.png Zu beachten ist, dass das Crossselling Rücksicht auf Fremdnummern nimmt. Das bedeutet, wenn für den Shop eine entsprechende Fremdnummer eingestellt ist, wird versucht diese zu verwenden.

Kundengruppen Mapping

Allgemeine Informationen zum Mapping von Gruppen (Kundengruppen, Preisgruppen usw.) in Shopschnittstellen finden Sie hier. Das Kundengruppening Mapping bei Shopware funktioniert in Verbindung mit der Option Neukunden automatisch zuweisen. Das heißt, wenn es ein Mapping mit aktivierter Option gibt, werden neue Adressen automatisch der entsprechenden Gruppe zugeordnet. Es ist möglich, Kundengruppen aus dem Shop zu übernehmen, dazu muss das Kürzel (die Kennziffer) genau übereinstimmen. Wenn die Option im Importer aktiviert ist und es eine Übereinstimmung gibt, wird die Adresse der Gruppe zugewiesen.Zusätzlich kann man in den Importereinstellungen den Haken Neue Benutzergruppen anlegen aktivieren. Dann wird eine neue Kundengruppe in Xentral angelegt, falls keine Übereinstimmung gefunden werden konnte. Ab Version 19.4 wird beim Auftragsimport auf das Gruppenmapping Rücksicht genommen. In dem Fall wird das Kürzel im Feld 'Gruppe im Shop' erwartet. Zusätzlich können in diesem Tab Preisgruppen für Staffelpreise zugewiesen werden, um gezielt Preisgruppen von Xentral nach Shopware zu exportieren. Bitte beachten Sie, dass das Gruppenmapping in Kundengruppen für Shopware aktuell nicht für die automatische Zuordnung von Gruppen greift (Stand: 10/2019).

FAQs

War der Artikel hilfreich?
Vielen Dank für Ihr Feedback!

Made with ❤ at zwetschke.de