Shopware Schnittstelle - Installation & Einrichtung

Mit der Shopware Schnittstelle können Sie Xentral mit Shopware verbinden.
Die Shopware Schnittstelle gibt es in unserem Shop.


Features der Schnittstelle

  • Aufträge aus Shopware abholen
  • Auftragsstatus bei Versand umstellen inkl. Meldung Trackingnummer
  • Artikel einzeln von Xentral nach Shopware oder von Shopware nach Xentral übertragen
  • Meldung aktueller Lagerzahlen bei Bestandsänderungen
Die Rechnung und oder Lieferschein kann durch Xentral mit eigenen Nummernkreisen erstellt werden. Die Belege werden im Versandprozess automatisch erstellt und versendet bzw. am Versanddrucker ausgedruckt.

Installation in Xentral

Ab Version 17.3 wurde die Anbindung von Shopware erheblich vereinfacht.

API Benutzer in Shopware erstellen

In Shopware muss man einen API-Benutzer anlegen unter Einstellung => Benutzereinstellung => Benutzer hinzufügen. Beispieldaten:
:entwickler:shopware_inline_shopware_apiuser.png
Hinweis: Wichtig ist, dass der API-Zugang aktiviert ist. Der Benutzername kann frei gewählt werden.

Shopschnittstelle in Xentral anlegen

1. Shopschnittstelle anlegen Unter Administration => Einstellungen => Online-Shops => NEU kann man nach Shopware suchen:
:entwickler:shopware_inline_neu.png
2. Shopware Daten eingeben Vergeben Sie einen Shop-Namen und stellen Sie fürs Erste die Einstellungen wie im Screenshot ein.
Danach tragen Sie Ihre Shopware Daten in die beschriebenen Felder ein.
:entwickler:shopware_inline_daten.png 3. Verbindung prüfen Am Schluss überprüfen Sie mit einem Klick auf "Verbindung prüfen" ob es geklappt hat:
:entwickler:shopware_inline_success.png
Sollte es zu einem Fehler kommen überprüfen Sie bitte Folgendes:
  • Die Daten aus Shopware wurden 1:1 so in Xentral hinterlegt
  • Die URL wurde richtig mit /api am Schluss angegeben
4. Weitere Einstellungen vornehmen Wie Sie anderen Einstellungen vornehmen, erfahren Sie in diesem Helpdeskeintrag.

Installation über Shopware (Standardplugin ab Shopware 5)

Die Xentral Shopschnittstelle "Shopware" kann direkt im Shopware Shop Backend als Plugin installiert werden.
Dies bietet sich an, wenn keine Sondereinstellungen nötig sind (z.B. andere Statusumstellung, spezielle Shopware-Sonder-Plugins etc.).
Um das Plugin zu installieren sind folgende Schritte notwendig:
  • 1. Shopware Backend: Xentral Plugin suchen und herunterladen
  • 2. Daten des Shopware Benutzeraccounts eingeben (oder wenn noch kein Account vorhanden: neuen Account bei Shopware erstellen)
  • 3. Shopware: Benutzeraccount und Shop miteinander über einen Key verbinden

A. Xentral Plugin installieren

1. Xentral Plugin suchen und herunterladen
  • Shopware Backend → Einstellungen → Plugin Manager → Suchfeld: "wawision" eingeben → "enter"
:wawision:wawision_shopware_plugin.png?direct
2. Daten des Shopware Benutzeraccounts eingeben
  • Xentral-zu-Shopware Importer → "jetzt herunterladen"
:wawision:wawision_shopware_plugin_001.png?direct Hinweis: Die Installtion des Plugins setzt einen Shopware-Benutzeraccount voraus:
  • geben Sie die Daten Ihres bestehenden Shopware Accounts an
  • oder (sofern Sie einen bestehenden Account haben) → geben Sie Ihre Daten direkt ein
3. Registrierung bei Shopware / Account
  • Registrierung bei Shopware (Account anlegen) oder Eigabe der bestehenden Benutzerdaten
:wawision:wawision_shopware_plugin_002.png?direct&300 Hinweis:Nach der Registrierung bei Shopware (Anlegen eines Shopware Accounts), muss der Shop mit dem shopware Account verknüpft werden. Dies können Sie direkt in Ihrem Shopware Account unter "Shops → Shop-Verwaltung → Neuen Shop registrieren" vornehmen. Hierzu muss dann eine .html Datei auf dem Server im Webspace des Shopware-Shops vorgenommen werden (Info von Shopware):
"Zur Autorisierung erstellen Sie bitte eine HTML-Datei (Textdatei mit Endung .html) in Ihrem Shop-Hauptverzeichnis mit folgender Bezeichnung:
sw-domain-hash.html
Die Datei muss außerdem den folgenden Inhalt haben:
IHRKEYDENSIEVONSHOPWAREERHALTEN"
Folgende Fehlermeldung kam bei Shopware 5:
Error
Auf dem SBP-Server ist ein Fehler aufgetreten.
Error code: OrdersException-2
Dies ließ sich dann durch die Verknüpfung zwischen Shop und dem Shopware Account lösen und das Xentral Plugin konnte installiert werden Weitere Informationen sind auf der Shopware Seite zu finden: http://community.shopware.com/Shopware-Account-Shopware-ID_detail_89.html

Installation auf dem Server (nur für Open Source Nutzer)

Hinweis: Für die Installation benötigen Sie einen Shopwareimporter => Diesen können Sie auf unserer Website herunterladen: https://xentral.biz/downloads. Diese Variante der Installation eignet sich nur für Nutzer Open Source Version von Xentral.

1. Anlegen eines neuen Shops in Xentral

Administration → Einstellungen → Online-Shops → Neu → Extern Shop benennen, Projekt angeben und die für Sie zutreffenden Optionen anhaken.:entwickler:shopschnittstelle_installieren_shopwawi.png?direct Hinweis: Mehr Informationen zu den Einstellungen finden Sie hier: Online-Shop-Anbindung: Einstellungen Die Zugangsdaten eintragen:
:entwickler:shopschnittstelle_installieren_zugangsdaten.png?direct
URL: Der Pfad zu unserem Shopware Importer - diesen tragen wir erst später ein, wenn wir den shopimporter auf den Server übertragen haben.
Importkey: Erstellen Sie mit Hilfe eines Passwortgenerators ein 32-stelliges Passwort und tragen es hier ein.
ImportToken: Erstellen Sie hier ein 6-stelliges Passwort
Demo Modus: Zum Testen am Anfang empfiehlt es sich unbedingt diese Option zu aktivieren, sodass der Status des importierten Auftrags nicht verändert wird.

2. Bearbeiten der user.inc.php Datei

Entpacken Sie den von uns erhaltenen Shopware Importer und benennen Sie den Ordner in shopwareimporter um. Danach öffnen Sie den 'shopwareimporter' Ordner und gehen in den Unterordner 'conf'.
Benennen Sie die 'user.inc.php.tpl' Datei um in 'user.inc.php'.
Öffnen Sie diese 'user.inc.php' Datei in einem Texteditor, tragen Sie Ihre Daten ein und speichern Sie die Änderungen.
ImportKey: Das 32-stellige Passwort, das Sie in Xentral erstellt haben.
ImportToken: Das 6-stellige Passwort, das Sie in Xentral erstellt haben.
ImportShopwareKey: Direkt in Shopware unter Benutzerverwaltung erstellte API Key
ImportShopwareApiUrl: Dies ist ihre Shop-Adresse + '/api' angehängt. Bsp: http://shop.firma.de/api
ImportShopwareApiUser: Hier tragen Sie Ihren Shopware Benutzer ein => Dieser Benutzer darf nicht gelöscht werden.
Hier ist die Datei mit Beispieldaten gefüllt:
:entwickler:shopschnittstelle_installer_userinc.png?direct

3. Kopieren des 'shopwareimporter' Ordners auf Ihren Server

Kopieren Sie danach den 'shopwareimporter' in den 'www' Ordner im Xentrals-Ordner.
Somit ist der 'shopwareimporter' Ordner ein Unterordner des 'www' Ordners.
1. Option: Mit einem FTP Programm übertragen
Öffnen Sie Ihr FTP Programm und geben Sie die dort Zugangsdaten zu Ihrem Server ein. Schieben Sie den 'shopwareimporter' in den www Ordner von Xentral.
2. Option: Mit SSH übertragen
Hinweis: Die folgenden Code-Snippets sind gefüllt mit Beispieldaten => Gleichen Sie diese an Ihre Daten und Ihre Serverstruktur an. Kopieren Sie den 'shopwareimporter' in den 'www' Ordner auf Ihrem Server.
scp -r shopwareimporter benutzer@IhreServerAdresse:html/wawision/www
Verbinden Sie sich mit SSH auf Ihrem Server:
ssh benutzer@IhreServerAdresse
Checken Sie ob der Ordner den richtigen Benutzer:Benutzergruppe des 'www' Ordners hat:
ls -lh
Falls nicht, müssen Sie hier die Rechte angleichen:
sudo chown -R www-data:www-data shopwareimporter/

Schritt 4: Verbindung von Xentral zum Shop-Importer

Danach können Sie in Xentral in den Online-Shop-Optionen unter URL den Pfad zum 'shopwareimporter' angeben.
Zur Überprüfung geben Sie den Pfad in den Browser ein => Es sollte eine komplett leere Seite angezeigt werden.
Dieser könnte so für unser Beispiel aussehen "http://www.firma.de/www/shopwareimporter":
:entwickler:shopschnittstelle_installieren_zugangsdaten.png?direct
Unter Administration => Einstellungen => Online-Shops => Ihr Shop => Export klicken Sie auf 'Verbindung prüfen'.
Wenn alles geklappt hat, sollte 'Verbindung: success' erscheinen.

Schritt 5: Einstellungen des Shops in Xentral anpassen

Alle Informationen zu den Shop-Einstellungen finden Sie hier: Online-Shop-Anbindung: Einstellungen

Schritt 6: Testen des Shop-Imports im Demo-Modus

Es ist wichtig, dass der Shop-Import ausgiebig getestet wird bevor Xentral alle Aufträge des Shops importieren soll. Laden Sie sich deswegen im Demo-Modus jeweils 1 Auftrag vom Shop nach Xentral und schauen bei diesem, ob alles passt.
Probieren Sie hier alle möglichen Varianten, inklusive Gutscheine, Rabatte, etc. aus.
Erst wenn alle Aufträge richtig nach Xentral übertragen werden, macht es Sinn den Demo-Modus wieder zu deaktivieren und größere Mengen an Aufträgen auf einmal zu importieren.

Aufträge zu Xentral übertragen

Das Importieren von Bestellungen aus Online Shops ist hier beschrieben

Alte Aufträge zu Xentral übertragen

Ab Version 18.3 ist es möglich auch alte Aufträge vom Shop nach Xentral zu übertragen.
Wichtig dabei: Vor dem Import der Aufträge prüft Xentral ob es schon Aufträge mit dieser Shop-Bestellnummer gibt und holt diese Aufträge nicht nochmal ab.
Prozessstarter anlegen
Sie benötigen dafür einen Prozessstarter mit dem Parameter shopimport_auftragarchiv: :entwickler:shopware_alte_auftraege.png
Alte Aufträge reinladen
In der Shopschnittstelle in Xentral gibt es einen Button "Alte Aufträge importieren" :entwickler:shopware_alte_autraege_button.png :entwickler:shopware_alte_autraege_popup_neu.png Nummer von => Älteste Belegnummer im Shop von der die Aufträge abgeholt werden sollen (inkl). Wenn leer gelassen, dann wird ab dem ältesten abgeholt.
Nummer bis => Letzte Belegnummer im Shop bis zu der die Aufträge abgeholt werden sollen (inkl). Wenn leer gelassen, dann wird bis zum neuesten 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 storniert sind.
Mit einem Klick auf den "Abholen" Button wird durch den Prozessstarter im Hintergrund die Aufträge reingeholt. Das kann je nach Menge und wann der Prozessstarter eingestellt ist, eine Zeit lang dauern. Hinweis: Bitte führen Sie unter Administration => Backup ein DB-Snapshot durch, damit Sie im Zweifel nach dem Import wieder auf den alten Datenbestand zurückspielen können.

Zahlungsstatus zurückmelden

Ab Version 18.2 wird der Zahlungsstatus direkt an den Shop zurückgemeldet. 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 es noch einen Prozessstarter unter Administration => Einstellungen => Prozessstarter :entwickler:shopware_zahlungsstatus_zurueckmelden_prozess.png

Bilderreihenfolge für Export ändern

Ab Version 18.3 ist es möglich für Shopware die Bilder-Reihenfolge für den den Export nach Shopware anzugegeben. :entwickler:shopware_bilder_reihenfolge_aendern.png Wichtig dabei ist, dass alle Artikelbilder für den Shop den Typ Standardartikelbild haben: :entwickler:shopware_bilder_reihenfolge_aendern_standardartikel.png Nach einem Export wird in Shopware die Reihenfolge dementsprechend angezeigt.
Das erste Bild dient als Vorschabild in Shopware.
:entwickler:shopware_bilder_reihenfolge_aendern_shopware.png

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 ab der Version 18.4 möglich über "direktes Mapping" spezifische Daten beim Artikelexport zu übertragen. Dazu werden beim Mapping der Freifelder, bzw. beim Namen der Eigenschaften die Textbausteine "mainArticle_", bzw. "mainDetail_" vorangestellt. Daten sie ü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. Schema: :entwickler:screenshot_at_2018-10-24_11_36_56.png Beispiele: 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. ----

Demo- und Testfunktionen

Testlauf: einzelne Aufträge von Shopware abholen

Vom Shop können auch gezielt einzelne Aufträge direkt nach Auftragsnummer (in Shopware) abgeholt werden.Hierzu muss folgendes eingestellt werden: :entwickler:shopware_einzelimport_einstellungen_174.png
  • 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
Info/Praxistipp: evtl. muss vorher der Zahlstatus des Auftrags und der Shopstatus (dieser auf jeden Fall) in Shopware auf "offen" gesetzt werden. Sollten Einstellungen in der Shopschnittstelle das Abholen verhindern, ist es z.T schneller direkt über die Shopware Stapelverarbeitung Aufträge umzustellen (Bestellstatus → "offen") → diese Aufträge werden dann abgeholt beim Import, der Status wird in Shopware von "offen" auf "in Bearbeitung" umgestellt. Im einzelsync ist nur die Abholung des ältesten offenen Auftrags aus Shopware möglich (allerdings werden z.B. im Demomodus keine Status umgestellt). Zusätzlich ist zu beachten, dass bei bei einem Shop in dem die Bestellnummern nicht nur aus Zahlen, sondern aus alphanumerischen Zeichen bestehen, die Abholung ab Nummer automatisch auf die ID des Datensatzes der Bestellung umgestellt wird.

FAQs

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

Made with ❤ at zwetschke.de