Mit dieser Schnittstelle kannst du xentral mit Shopware 5 verbinden, um Bestellungen von dort zu Xentral zu importieren und deine im Shop verkauften Artikel in Xentral zu verwalten. Die Anbindung geschieht über eine API-Schnittstelle (Shopimporter).
Anmerkung
Xentral ist mit allen Shopware Versionen kleiner als 6.5 kompatibel.
-
Aufträge aus Shopware abholen
-
Auftragsstatus bei Versand umstellen inkl. Meldung der Trackingnummer an Shopware
-
Artikel von Xentral nach Shopware oder von Shopware nach xentral übertragen
-
Meldung aktueller Lagerzahlen bei Bestandsänderungen
Rechnungen und Lieferscheine kannst du in Xentral mit eigenem Nummernkreis erstellen. Die Belege werden im Versandprozess automatisch erstellt und versendet bzw. am Versanddrucker ausgedruckt.
Im Folgenden wird gezeigt, wie du deinen Shopware 5 Shop an Xentral anbinden kannst.
Zunächst musst du in Shopware unter Einstellung → Benutzerverwaltung → Benutzer hinzufügen einen API-Benutzer anlegen. Dieser Benutzer wird speziell für die Xentral-Schnittstelle verwendet. Den API-Zugang musst du auf "aktiviert" stellen. Den Benutzername kannst du frei wählen.
Unter Administration → Shop Schnittstelle → Übersicht → NEU kannst du einen neuen Shop anlegen und das Modul Shopware 5 auswählen.
Nachdem du Shopware 5 ausgewählt hast, kannst du im nächsten Schritt die nötigen Daten für die Verbindung der beiden Systeme eintragen. Den API-Key hast du 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/
Sobald du die Daten eingetragen hast, kannst du die Verbindung zwischen beiden System über die Schaltfläche Verbindung prüfen testen. Bei einer erfolgreichen Verbindung erscheint die Meldung 'Verbindung: success' oder, falls die Schnittstelle Subshops erkennt, eine Auflistung der erkannten 'Subshops' und deren Subshop-IDs.
Anmerkung
Die API-URL kannst du direkt im Browser aufrufen und dort die Zugangsdaten eingegeben. Als Ergebnis sollte folgende Rückmeldung erscheinen: success: false message:Resource not found
Sollte die Verbindung fehlschlagen, kannst du auch eine Authentifizierung über Digest durchführen.
Um schnellstmöglich loszulegen sind nur ein paar Einstellungen und Aktionen erforderlich. Was für einen Quickstart mit Auftragsimport, Lagerzahlenabgleich und Rückmeldung von Trackingnummern notwendig ist erfährst du hier.
In diesem Abschnitt werden dir die möglichen Einstellungen in der Shop-Schnittstelle erklärt.
Wenn du die Einstellungen der Shopware 5 Schnittstelle öffnest, landest du zunächst im Tab Details → Schnittstelle.
Einstellungen:
-
Bezeichnung → Name frei wählbar für den Shop (wird z.B. im Artikel und im Import-Menü angezeigt)
-
Aktiv → Haken setzen, damit die Schnittstelle aktiv ist. Nicht mehr benötigte Schnittstellen kannst du auf inaktiv setzen
-
Projekt → Verknüpfung des Shops auf ein Projekt. Im Projekt kannst du die Logistikeinstellungen vornehmen
-
Abholmodus → Bei Shopware 5 kannst du hier nach einem bestimmten Status oder ab einer Nummer abholen (gilt für alle Importer), die Abholung nach Nummer ist eine entsprechende Importmethode nur für Tests. Für den Live-Betrieb muss auf den Import nach Status umgestellt werden.
-
Import-Modus → Legt fest, ob die Aufträge aus dem Shop manuell (per Knopfdruck) oder automatisch importiert werden sollen
-
Demo (zum Testen) → Der Auftragsstatus im Shop nicht umgestellt, keine Artikel oder Lagerzahlen übertragen
-
Manuell (mit Importzentrale) → Die Aufträge werden erst abgeholt, wenn der Button Aufträge abholen geklickt wird
-
Automatisch (per Prozessstarter) → Die Aufträge werden regelmäßig automatisch vom Shop abgeholt. Hierfür wird der Prozessstarter Shopimporter benötigt
-
-
Nur 1 Auftrag pro Anfrage → Es wird nur 1 Auftrag pro Anfrage vom Shop übertragen
-
Aufträge in Zwischentabelle → Beim Abholen der Aufträge werden die Aufträge nicht direkt angelegt, sondern erstmal zum Durchschauen in einer Zwischentabelle gespeichert. Hier kannst du entscheiden, welche Aufträge angelegt und welche erst später importiert werden sollen
-
Anzahl abholen begrenzen → Möglichkeit, um eingehende Aufträge auf einmal zu begrenzen. Steht nichts (0) drin gilt die Default-Begrenzung von 100
-
Protokollierung im Logfile → Durch Setzen des Hakens aktivierst du den Logfile und die Informationen werden in diesem protokolliert
-
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/
-
Storniert Status ID → Standardmäßig ist hier die 4 eingetragen. Der einfachste Weg, um die ID zu finden ist es einen Datenexport einer stornierten Bestellung vorzunehmen
-
ID Standard Preisgruppe → Standardmäßig ist hier die 1 eingetragen. Um die ID zu bekommen musst du einen Artikel aus der Standard Preisgruppe ausgeben
-
Begrenzen auf Subshop → Hiermit hast du die Möglichkeit die Schnittstelle nur für einen Subshop einzurichten, indem die die jeweilige Subshop ID in das Feld einträgst. Die IDs werden die angezeigt wenn du auf Verbindung prüfen klickst
-
Benutzergruppen aus Shop übernehmen → In Shopware angelegte Kundengruppen werden übernommen, wozu ein Kundengruppenmapping vorhanden sein muss. In Kombination mit dem nächsten folgender nachfolgenden Option Neue Benutzergruppen anlegen können in xentral auch neue Kundengruppen anlegt werden
-
Neue Benutzergruppen anlegen → Durch das Kundengruppenmapping werden neue Adressen aus dem Shop automatisch der entsprechenden Gruppe zugeordnet. Durch Setzen des Hakens wird eine neue Kundengruppe in xentral angelegt, falls keine Übereinstimmung gefunden werden konnte. Ohne den Haken werden die Benutzer ohne Übereinstimmung der Standard Benutzergruppe in xentral zugeordnet
-
Gutscheine als Lagerartikel anlegen → Bestellte Gutscheine werden als Lagerartikel angelegt (wichtig, falls diese physisch verschickt werden z.B. als Gutscheinkarte)
-
Wurzelkategoriename → Die Kategorien werden von xentral in diese Wurzelkategorie exportiert
-
Order ID statt Bestellnummer verwenden → Diese Option kann hilfreich sein, wenn du die Aufträge weder nach Status noch nach Bestellnummer importieren kannst. Ein Grund dafür könnte sein, dass die Bestellnummer von numerisch auf alphanumerisch wechselt. Die Order ID ist eine interne Datenbank ID von Shopware 5
-
Unbezahlte Bestellungen abholen → Haken setzen, damit auch unbezahlte Bestellungen von Shopware abgeholt werden
-
Authentifizierung über Digest → Haken setzen, um eine Authentifizierung über Digest durchzuführen (falls die Verbindung zum Shop fehlschlägt)
Aktion
-
Verbindung prüfen → Prüft die Verbindung zwischen beiden Systemen
-
Aufträge abholen → Holt die Aufträge aus deinem Shop ab
-
Shopimport Zwischentabelle → Springt zur Zwischentabelle der Aufträge vom Shop. Die Zwischentabelle wird nur im manuellen Importmodus befüllt und wenn die Option 'Aufträge in Zwischentabelle' aktiviert ist. In der Zwischentabelle wählst du in der linken Spalte zwischen "Import", "Müll" und "Später" aus.
-
Import: Auftrag wird direkt importiert
-
Müll: Auftrag landet im Müll und kann kein zweites Mal importiert werden
-
Später: Auftrag kann zu einem späteren Zeitpunkt importiert werden
-
-
Artikelbaum übertragen → Überträgt den Artikelbaum von Xentral nach zum Shopware 5 Shop
-
Artikelliste abholen → Importiert Artikel aus deinem Shopware 5 Shop zu Xentral. Shopartikel, die bereits in Xentral vorhanden waren, werden aktualisiert, fehlende Artikel werden angelegt. Die Artikel werden nach dem Ausführen der Aktion nach und nach vom Prozessstarter Artikelimport abgeholt.
-
Alte Aufträge importieren → Alte Aufträge werden in die Zwischentabelle geladen, wo du wieder entscheiden kannst ob die Aufträge importiert werden sollen
Informationen zu diesem Tab findest du hier.
Informationen zu diesem Tab findest du hier.
Informationen zu diesem Tab findest du hier.
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 kannst du spezielle Felder anzusprechen, für die es kein Gegenstück in Xentral gibt oder die durch ein Plugin hinzugefügt wurden.
Das Freifeldermapping der Shopware-Schnittstelle funktioniert in diesem Umfang nur in eine Richtung, nämlich für den Export von Xentral zu Shopware. Beim Import von Freifeldern von Shopware zu Xentral wird nur auf Felder die mit "attr" anfangen Rücksicht genommen.
Schema
Beispiele: Eigenschaften mit der Bezeichnung "mainArticle_filterGroup" können das Eigenschaften-Set bei Shopware ansprechen. In Shopware musst du für einen Artikel ein Eigenschaftenset anlegen, um auch Eigenschaften auswählen zu können. In Xentral wird das Eigenschaftenset dann hinterlegt und beim Export nach Shopware übergeben. Bei Varianten-/Matrixartikeln musst du das Eigenschaften Set im Hauptartikel in Xentral anlegen. Hinterlegst du eine Eigenschaft mit der Bezeichnung "mainArticle_notification" und einem Wert von "1" bei einem Artikel sorgt das dafür, dass das Feld für E-Mail-Benachrichtigung für den Artikel in Shopware aktiviert wird:
Folgendes Mapping der Freifelder in den Importer-Einstellungen 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-Mail-Benachrichtigung übertragen werden:
Mögliche Felder unter mainArticle
-
taxId - ID der Steuergruppe
-
priceGroupId - ID der Preisgruppe
-
filterGroup - Spezialfeld. Du kannst statt der Filtergruppenid auch die Bezeichnung der Filtergruppe angeben. 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-Mail-Benachrichtigung 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
Anmerkung
Wenn du ein direktes Mapping für ein Feld verwendest, 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.
Falls du in Shopware 5 verschiedene Subshops hast, können diese im Tab Subshop gemappt werden. 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:
Anmerkung
Das Subshop-Mapping funktioniert nur, wenn du die Subshops in Shopware auch als Subshops eingestellt hast und nicht als Sprachshops!
Informationen zu Subshops findest du hier.
Informationen zu diesem Tab findest du hier.
Anmerkung
Gruppenpreise bei Varianten-Artikeln sind in Shopware 5 nur mit dem Matrixprodukt möglich. In Shopware 5 können keine Staffelpreise übertragen werden, da keine "Gültigkeit bis" gesetzt werden kann.
Das Importieren von mehreren Gruppenpreisen von Xentral nach Shopware 5 ist über das Preisgruppen Mapping möglich. Staffelpreise übertragen muss in den Einstellungen aktiviert sein, damit Gruppenpreise übertragen werden. Wichtig ist hier das korrekte Kundengruppen Mapping und, dass die Kürzel im Shop und in Xentral identisch sind. Die Rolle Artikel musst du zwingend angeben. In der Shopware-Schnittstelle in Xentral (Administration → Shop Schnittstelle → *Shopware auswählen* → Details → Gruppenmapping) sieht die Konfiguration folgendermaßen aus:
Die Gruppen legst du im Modul Gruppen (Administration → Einstellungen → Buchhaltung → Gruppen) fest und diese sehen wie folgt aus:
In Shopware selbst stellst du es dann so ein:
Über die Verwendung von Smarty erfährst du mehr in diesem Helpdesk Artikel: Smarty im Shopimporter.
Informationen zu diesem Tab findest du hier.
Es ist möglich, Artikel von Shopware 5 nach Xentral zu importieren.
Anmerkung
Der Import von Metafeldern kann derzeit nur von Xentral nach SW5 genutzt werden. Dazu musst du die Metafelder in Xentral pflegen oder du kannst nur die Lagerzahlensynchronisierung nutzen.
Beim Artikelimport gibt es verschiedene Funktionen, die bei der Übertragung gezogen werden.
Diese Funktionen sind für Haupt- und Variantenartikel verfügbar:
-
Artikelbezeichnung
-
Artikelnummer, falls eingestellt
-
Standard VK-Preis
-
Pseudopreise
-
Aktiv/Inaktiv
-
Lieferzeit
-
Gewicht
-
EAN
-
Freifeld, falls Mapping eingestellt
Anmerkung
Es werden keine Fremdnummern im Artikel benötigt, wenn die Artikelnummern / SKUs identisch zu den Artikelnummern in Shopware sind.
Diese Funktionen sind nur für Hauptartikel verfügbar:
-
Staffelpreise
-
Kurztext
-
Beschreibung
-
Restmenge/Abverkauf
-
Umsatzsteuer
-
Hersteller
-
Herstellernummer
-
Eigenschaften
-
Crossselling
-
Kategorien, inklusive Artikelbaum
-
Bilder
-
Varianten
Beim Import, unabhängig von den Einstellungen und davon, ob der Artikel bereits existiert, werden folgende Funktionen immer importiert:
-
EAN
-
Aktiv/Inaktiv
-
Staffelpreise
-
Pseudopreise
Die restlichen Daten werden nur bei neuangelegten Artikeln importiert. Alternativ findet die Übertragung nur statt, wenn du in den Einstellungen des Importers festgelegt hast, dass bereits existierende Artikel überschrieben werden sollen.
Der Artikelimport aus Shopware 5 ist nur als Grundlage für eine Artikelbasis zu sehen. Je nach Bedarf musst du den Artikelimport entsprechend über die Import-/Exportzentrale anreichern.
Um Artikel initial aus Shopware 5 abzuholen, öffnest du das Modul Shopware 5 und führst die Aktion Artikelliste abholen aus:
Für den Import der Artikel benötigst du folgenden Prozessstarter: Artikelimport/getarticles. Möglicherweise musst du diesen noch im Prozessstarter-Modul aktivieren.
Wie du Artikel von Xentral zu Shopware 5 exportierst, erfährst du hier.
Wie du die Lagerzahlen synchronisieren kannst, erfährst du hier.
Das Importieren von Bestellungen aus Onlineshops wird in diesem Artikel beschrieben.
Die Shopware-Schnittstelle ermöglicht dir 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 noch einmal ab. In der Shop-Schnittstelle in Xentral nutzt du hierfür die Schaltfläche Alte Aufträge importieren.
Sobald du auf die Schaltfläche geklickt hast, kannst du im Dialogfenster anhand der Shopware-Bestellnummern angeben, welche alten Aufträge abgeholt werden sollen.
-
Nummer von → Älteste Belegnummer im Shop, von der die Aufträge abgeholt werden sollen. Wenn du das Feld leer lässt wird ab dem ältesten Auftrag abgeholt
-
Nummer bis → Letzte Belegnummer im Shop, bis zu der die Aufträge abgeholt werden sollen. Wenn du das Feld leer lässt 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 die Schaltfläche Abholen stößt du den Import an. Der Import erfolgt dann nach und nach im Hintergrund. Dafür benötigst du den Prozessstarter shopimport_auftragarchiv. Der Import kann je nach Menge der Aufträge eine längere Zeit in Anspruch nehmen.
Shopware erlaubt den Import von bis zu 1000 Aufträgen auf einmal. Je nach Auftragsmenge ist es daher nicht möglich, Aufträge mehrerer vergangener Jahre zu importieren. Idealerweise importierst du nur unbedingt benötigte Altaufträge.
Vom Shop kannst du auch gezielt einzelne Aufträge direkt nach der Auftragsnummer in Shopware abholen.
Hierzu musst du folgendes einstellen:
-
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
Der Shopstatus und in manchen Fällen auch der Zahlstatus des Auftrags müssen 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" kannst du gezielt einen bestimmten Auftrag abholen. Anderweitig wäre nur die Abholung des ältesten, offenen Auftrags möglich. Beachte außerdem, 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.
Der Zahlungsstatus der Aufträge kann direkt an den Shop zurückgemeldet werden. 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ückgemeldet werden kann, benötigst du den Prozessstarter shop_rueckmeldungen.
Die Shopware-Schnittstelle erlaubt dir den Export von Artikelbildern von Xentral zum Shop. Voraussetzung ist, dass die Bilder in Xentral im Artikelstamm unter Dateien mit dem Stichwort "Standard Artikelbild (Shopbild)" angelegt wurden. Nur Bilder mit diesem Stichwort werden an den Shop exportiert. Informationen über den Export von Artikelbildern findest du in diesem Artikel.
Die Versandkosten werden automatisch nach Xentral importiert. In Shopware kannst du die Versandkosten ab einem bestimmten Einkaufsbetrag auf portofrei setzen lassen. Die Aufträge mit Portokosten werden ganz normal mit einem Portoartikel und dessen Preis zu Xentral importiert. Portofreie Bestellungen werden mit dem Portoartikel importiert, jedoch ist dieser mit 0,00 EUR aufgeführt, sodass die Bestellung für den Kunden portofrei ist.
Wenn ein Subshopmapping existiert und eine Übersetzung der Freifelder für die entsprechende Sprache existiert, wird die Übersetzung an Shopware exportiert.
Ab Version 19.4 kann Xentral Gutscheine aus Shopware verarbeiten. Hierzu musst du den Gutschein mit Artikelnummer in Shopware anlegen. Beim Import wird dieser dann auf die Artikelnummer in xentral gemapped. Voraussetzung hierfür ist, dass in Xentral ein Artikel mit dieser Nummer existiert oder die Nummer als Fremdnummer besitzt.
Alternativ, wenn du in der Shop-Schnittstelle die Option "Fehlende Artikel anlegen" gewählt hast, wird ein fehlender Artikel automatisch angelegt.
Die Option Gutscheine übertragen muss aktiviert sein.
Wird dem Namen einer Eigenschaft in xentral articleAttribute_ vorangestellt, so kannst du diese direkt als Attribute in Shopware exportieren.
Beispiel: Die Eigenschaft Preishistorie wird nun als "articleAttribute_Preishistorie" angelegt (statt einfach nur "Preishistorie").
In der Freitextfeld-Verwaltung von Shopware wird das Feld mit dem dazu passenden Namen in der Tabelle articles_attributes angelegt.
Der Wert der Eigenschaft wird beim Artikelexport von Xentral zu Shopware dann in das vorgesehene Feld übertragen.
In Verbindung mit der App "Crossselling" ist es dir möglich, Crossselling-Verknüpfungen zwischen zwei Artikeln in Xentral zu pflegen und zu Shopware zu übertragen. In der Crossselling App kannst du Artikel hierzu bidirektional verknüpfen.
Wenn du die Einstellungen so speicherst, werden die Artikel in Shopware 5 dem jeweils anderen als Zubehörartikel zugewiesen.
Beachte, dass das Crossselling Rücksicht auf Fremdnummern nimmt. Das bedeutet, wenn du für den Shop eine entsprechende Fremdnummer einstellst, wird versucht diese zu verwenden.
Das Kundengruppen Mapping 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. Du kannst Kundengruppen aus dem Shop übernehmen. Dazu muss das Kürzel (die Kennziffer) genau übereinstimmen. Wenn du die Option im Importer aktiviert hast und es eine Übereinstimmung gibt, wird die Adresse der Gruppe zugewiesen. Zusätzlich kannst du in den Importereinstellungen den Haken "Neue Benutzergruppen anlegen" aktivieren. Dann wird eine neue Kundengruppe in Xentral angelegt, falls keine Übereinstimmung gefunden werden konnte.
Beachte, dass das Gruppenmapping in Kundengruppen für Shopware aktuell nicht für die automatische Zuordnung von Gruppen greift.