Übersicht:

• Shopware API
• Kategorisierung
  • Masterkategorie
  • Hauptkategorie hinterlegen
• Bilderverwaltung
• Einstellungen in der Schnittstelle
• Hinweise: Shopware 4.2
  • Artikelbilder
• Verwendung des Attribut-Mappings in Shopware 4
• ​Hinweise zum Update von Shopware < 4.2 auf Shopware 4.2 - 4.3.4
• Bilder-URL Dienst

 

 

 

Shopware 4

Die Shopware-Schnittstelle für Version 4 unterliegt besonderen Bedingungen und sollte deshalb nicht eigenständig eingerichtet werden. Wenn Sie eine Schnittstelle zum Online-Shop System Shopware benötigen, melden Sie sich bitte beim Support. Dieser wird dann die benötigten Daten bei Ihnen erfragen und die Schnittstelle für Sie einrichten.

Benötigte Informationen:

• Shopware-API-Schlüssel
• Shopware-API-Benutzer
• Shop URL

 

Wichtig: Bitte löschen Sie keine Produkte im Shopware-Backend, da es sonst zu Problemen bei der Neuübertragung kommen kann!

 

Kurzübersicht der Funktionen der Shopware 4 und Shopware 5 SchnittstelleShopware 4 

Unterstützte Versionen:
Shopware 4.0 - Shopware 5
Unterstützung von API v2 und der Vorgängerversion vor Shopware 4.2

Informationen die die Schnittstelle von cludes -> Shopware übermittelt:

- Anlage und Aktualisierung konfigurierter Kategoriestrukturen werden in Shopware vorgenommen
- Anlage und Aktualisierung von Hauptartikeln sowie Artikeln mit Varianten 
  - Übertragen werden alle üblichen Produktinformationen die in cludes und Shopware zu finden sind. (Beschreibung, Name, Bilder, Preisangaben, Grundpreisinformationen, Kategoriezuordnungen uvm.)
- Übertragung der in cludes angelegten Kategoriezuordnung zu den jeweiligen Artikeln
- Abgleich der Produktbilder über zentrale Medienverwaltung von Shopware 
- Abgleich der Artikelbestände zu Shopware 
- Shopware Freitextfelder können über Sonderkonfigurationen zugeordnet und übermittelt werden
- Aktualisierung des Bestellstatus in Shopware bei Bearbeitung einer Bestellung in cludes
- Verwendung eigener Bildnamen für die Übertragung zu Shopware zur SEO Optimierung

Informationen die die Schnittstelle von Shopware -> cludes übermittelt:
- Import von Bestell- und Kundendaten. 
  - Wiedererkennung bereits angelegter Kunden

 

Shopware API

Um die Schnittstelle anzulegen benötigt der Support die Shopware-API und den Shopware-API-Benutzer. Diese finden Sie in Shopware unter Einstellungen -> Benutzerverwaltung. Dort wählen Sie bitte den Benutzer aus, der für den Apizugang hinterlegt wurde.

Falls es noch keinen gibt können Sie auch einen neuen erstellen, dieser muss folgende Vorraussetzungen erfüllen:

• Haken bei "Api Zugang" - "Aktiviert"
• Mitglied der Rolle: locale_admins

 

Der Shopware-API-Schlüssel befindet sich im Feld "API-Schlüssel" und der Shopware-API-Benutzer entspricht dem Feld "Stammdaten" - "Name".

 

 

 

 

Kategorisierung

Die Kategorien werden in Ihrem Shop so angezeigt, wie Sie diese in cludes angelegt haben. Damit diese auch Übertragen werden müssen in der Shopware-Schnittstelle einige Konfigurationen vorgenommen werden.

 

 

Folgende Einstellungen müssen gesetzt werden:

• System-ID der cludes Masterkategorie in Shopware: Die ID der Masterkategorie aus Shopware.
• Kategorien zuweisen: Alle Kategorien, die im Shop angezeigt werden sollen, müssen zugewiesen werden. Markieren Sie dazu alle Kategorien mit STRG in der rechten Spalte, anschließend wählen Sie den Button "modifizieren".
• Kategorien übertragen: Um Kategorien zu übertragen muss dieser Haken gesetzt werden.

 

 

Masterkategorie

Die Masterkategorie finden Sie im Backend von Shopware. Öffnen Sie dazu Artikel -> Kategorien. Standartgemäß existieren in Shopware die Masterkategorien "Deutsch" und "Englisch", um entweder den Shop als deutschen oder als englischen Shop zu führen. Je nachdem ob Deutsch oder Englisch muss die entsprechende Masterkategorie-ID in cludes hinterlegt werden.

 

 

Wählen Sie hier bitte die gewünschte Masterkategorie aus - Deutsch oder Englisch.

 

 

Unter "Allgemeine Einstellungen - Kategorie:" finden Sie nun die ID der Masterkategorie. Diese tragen Sie in cludes in der Shopware-Schnittstelle ins Feld "System ID der cludes Masterkategorie in Shopware" ein.

 

 

Hauptkategorie hinterlegen

in Shopware muss außerdem die Hauptkategorie aus cludes hinterlegt werden, unter welcher sich der ganze Kategoriebaum für Shopware befindet. Dazu öffnen Sie in Shopware Einstellungen -> Grundeinstellungen -> Shopeinstellungen -> Shops -> Ihr Shop.

Im Dropdownmenü des Feldes "Kategorie" sehen Sie nun eine Übersicht aller von cludes nach Shopware übertragenen Kategorien. Dort wählen Sie nun die Hauptkategorie aus.

 

 

 

 

Bilderverwaltung

Bevor die ersten Produkte mit Bildern in den Shop geladen werden, sollten Sie für die Bilder noch einige Einstellungen in Shopware vornehmen. Öffnen Sie dazu in Shopware Inhalte -> Medienverwaltung -> Bearbeiten-Zahnrad neben Ordner "Artikel".

In diesen Ordner werden alle Produktbilder geladen, welche von cludes übertragen werden. Legen Sie hier bitte im Feld "Thumbnail-Größe" die Größe für die Thumbnail-Bilder fest. Diese Größe muss deshalb eingetragen werden, damit nicht bei jeder Schnittstellenausführung alle Produktbilder, von bereits übertragenen Produkten, nochmal übertragen werden - was zu extremer Auslastung der Schnittstelle führen würde. So wird im Endeffekt von cludes eine interne Datei angelegt, in welcher steht, welche Bilder bereits übertragen wurden, damit das nicht immer wieder aufs Neue geschieht.

 

 

 

 

Einstellungen in der Schnittstelle

In der Schnittstellenkonfiguration in cludes gibt es einige Felder, die Sie zusätzlich setzen können.

 

 

• Artikel-ID als ordernumber: Haken setzen, um in der Bestellung die Artikel-ID als Artikelnummer anzuzeigen, anstatt der Produktnummer.
• Überschrift als Produktname: Übernimmt als Produktnamen die Angaben aus dem Feld "Zweitüberschrift" und überträgt diesen auch so zu Shopware.
• Ab welcher Kategorie soll die Struktur erzeugt werden: Geben Sie hier die ID der Kategorie in cludes an, ab welcher der Kategoriebaum beginnt, der auch nach Shopware übertragen werden soll. Die ID finden Sie innerhalb der Kategoriekonfiguration in cludes ganz oben.

 

Verwendung des Attribut-Mappings in Shopware 4

Mehr Informationen zur Attribute-Mapping Funktion für Shopware 4 finden Sie hier.

Sind noch keine Mappings für Attribute hinterlegt, so müssen diese erst erstellt werden, bevor sie von der Schnittstelle genutzt werden können.

Ist dies erledigt kann man die Attribute für die Übertragung zu Shopware vorbereiten. Zuerst muss eine Konfiguration für die Attribute im Shopware Backend hinterlegt werden, welche dann auch gleichermaßen für die Schnittstelle hinterlegt wird.

Im Shopware Backend gehen Sie dazu in Einstellungen -> Grundeinstellungen -> Artikel -> Artikel-Freitextfelder.

 

 

Dort können Sie Bezeichnungen und Namen für die Attribute eingeben. Wollen Sie beispielsweise das Attribut “Sichtdurchlässigkeit” als zweites Freitext Attribut, dann geben Sie als Namen “attr2” an, als Feldtypen “Textfeld” und als Feldbezeichnung den gewünschten Wert “Sichtdurchlässigkeit”. Nach erfolgreicher Anlage wird im Backend des Shops in der Artikelmaske ein entsprechendes Feld angezeigt. Nun kann das Feld über die API mit entsprechenden Werten befüllt werden.

Damit die Schnittstelle nun weiß welche Attributwerte in welches Feld gehören muss die Konfiguration in der Shopware 4 Schnittstelle im Backend von cludes angepasst werden.

In der Box für “Attributspezifische Einstellungen” kann man die Attributmappings für die Schnittstelle sichtbar machen.

 

 

Dort sind die möglichen Freitext Attribute 1-20 aufgelistet. Geben Sie im entsprechenden Feld für “attr2” dann den Alias-Namen des Attributes für die Schnittstelle an, hier “Sichtdurchlässigkeit”.

Sind alle Mappings eingetragen aktiviert man die Verwendung des Mappings mit dem Haken “Attributmapping verwenden”. Anschließend werden für alle Artikel die bspw. ein entsprechendes Amazon Attribut mit einem Wert zu einem Mapping für die Schnittstelle haben in die jeweiligen Freitextfelder des Shops geschrieben.

 

 

 

Hinweise: Shopware 4.2

Es folgen einige Hinweise bezüglich der Shopware 4.2-Schnittstelle. Bitte beachten Sie, dass es sich bei dieser Schnittstelle noch um eine Beta-Version handelt.

 

Artikelbilder

Normale Artikelbilder werden im replace-Modus übertragen. Das bedeutet, dass alle Bildzuordnungen die in Shopware vorhanden sind, mit denen ersetzt werden, die von cludes übermittelt werden. Bei HMU-Artikel in Shopware führt das dazu, dass sämtliche Bilder die den Varianten des Artikels zugeordnet sind, entfernt werden.

Der Grund dafür ist, dass die Bilder im Prinzip dem Hauptartikel zugeordnet werden und über eine Sonderkonfiguration im Shop dann bei der Auswahl der jeweiligen Variante angezeigt werden.

Damit nicht entweder ständig die Variantenbilder entfernt werden oder die HMU-Bilder vielfach angezeigt werden, gilt für diese eine Beonderheit: Wenn ein HMU-Artikel angelegt wird, werden die Bilder ganz normal erst für ihn und dann für seine Varianten zugeordnet.

Wenn die Bilder für den HMU einmal hochgeladen wurden, werden sie nicht nochmal hochgeladen. Wenn Sie also ein neues Bild dem HMU-Artikel zugeordnet haben, dann muss der Artikel unter "Anbindung" für die Shopware 4.2-Schnittelle auf den Status "neu" gesetzt werden. Das aktualisiert dann auch die Unterartikel.

Das führt dann wieder zu der Reihenfolge, dass für den Artikel erstmal alle Bilder entfernt werden, dann wird das HMU-Bild hochgeladen und anschließend die Variantenbilder. Danach werden diiese wieder nicht mehr entpackt, bis der Status auf "neu" gesetzt wird.

 

 

Hinweise zum Update von Shopware < 4.2 auf Shopware 4.2 - 4.3.4

Im folgenden sind zwei Varianten der Tätigkeiten beschrieben die für ein oben beschriebenes Update vorgenommen werden müssen. Die erste Variante zeigt die nötigen Schritte bei einer Aktualisierung manuell durch den Nutzer selbst.

 

Genereller Hinweis:

Soll ein bereits vorhandenes Shopware System der oben genannten Version aktualisiert werden, ist zu beachten, dass zur Verwaltung von Bildern und Varianten neue Ressourcen vorhanden sind. Wir empfehlen deshalb folgende Vorgehensweise bei der Aktualisierung:

• Nehmen Sie zu aller erst eine Datensicherung des Shops vor. Sichern Sie die Datenbank (bspw. mit mysqldump) und nehmen Sie auch eine Sicherung der Dateien des Shops vor. Eine Sicherung sollte unbedingt vorher durchgeführt werden!

 

Variante 1 (manuell durch den Nutzer [nicht empfohlen!]):

• Deaktivieren der Shopware-Schnittstelle vor dem Update. Stellen Sie nach der Deaktivierung zuerst sicher, dass die Schnittstelle nicht aktuell ausgeführt wird.
• Nehmen Sie das Update des Shopsystems vor.
• Wenn Sie die Bilder aus der Datenbank der zentralen Medienverwaltung von Shopware löschen möchten (sie werden nach der Aktualisierung der Schnittstelle in cludes neu übermittelt!), führen Sie folgende Schritte durch:
  • Löschen der Bilder aus der Datenbank die Teil des Artikel Albums sind:
    DELETE FROM s_media WHERE albumID = -1;
  • Löschen der Zuordnungseinträge von Artikeln zu den Medieneinträgen:
    DELETE FROM s_articles_img WHERE NOT EXISTS (SELECT * FROM s_media WHERE s_media.id = s_articles_img.media_id);

 

Möchte man auch die Dateien aus dem Medienverzeichnis löschen, so muss dies gezielt vorgenommen werden, da die Bilder dort albumunabhängig gespeichert werden. Löscht man das gesamte Verzeichnis, so könnte dies zum Verlust von Kategoriebildern und dergleichen führen.
Die Bilder liegen im Shopware Hauptverzeichnis in "/media/image/".

• Setzen Sie in der noch deaktivierten Schnittstelle in cludes den Haken bei der Option "API v2 verwenden", aktivieren Sie die Schnittstelle und klicken auf "Schnittstelle modifizieren"
• Klicken Sie anschließend in der Schnittstelle unter Sonderfunktion auf "Alle neuen und aktiven Produkte dieser Schnittstelle zur Neuübertragung markieren"

 

Die nächste Ausführung der Schnittstelle wird dann die Daten in der aktualisierten Version übertragen. Sind in dem System bereits Artikeldaten vorhanden, so sollten diese unbedingt nach der Ausführung der Schnittstelle überprüft werden. Bei der Übertragung von Varianten kann es bei der Anlage zu Problemen kommen, wenn ein Artikel bereits über aktive Varianten verfügt (bspw. Redundanz).

 

Hinweise für den Einsatz einer Shop-Kopie für das Update:

Wird eine Kopie des Shops verwendet und eine zweite Schnittstelle für das Update (diese können Sie 30 Tage für die Umstellung nutzen), so gelten die oben aufgeführten Schritte nach wie vor. Da aber eine neue Schnittstellen in cludes verwendet wird ist darauf zu achten, dass die Zuordnungseinträge zu der Schnittstelle über eine CSV-Datei zuerst von der alten Schnittstelle exportiert und anschließend für die neue importiert werden muss.

Ferner sollten in der Kopie keine Bestellungen vorhanden sein, da diese anschließend von der Schnittstelle ggf. erneut importiert werden.

Bei der Verwendung eines kopierten Systems des Shops empfehlen wir die Variante 2 für die Umstellung, da so durch die Hilfe des technischen Supports ein besser Ablauf gewährleistet werden kann.

 

Variante 2 (mit Hilfe des technischen Supports von cludes [empfohlen!]):

Bitte beachten Sie, dass Sie bei dieser Variante eine Anfrage an den Vertrieb stellen müssen.

Wenn Sie die Zugangsdaten zur Datenbank und den Zugriff per FTP an den technischen Support von cludes zusenden können die Techniker von cludes die folgenden Schritte für Sie vornehmen.

• Deaktivieren der Shopware Schnittstelle vor dem Update. Stellen Sie nach der Deaktivierung zuerst sicher, dass die Schnittstelle nicht aktuell ausgeführt wird.
• Zur Aktualisierung selbst sollte nicht das eigene Produktivsystem verwendet werden, sondern idealerweise eine Kopie des Systems. Dieses kann man temporär mit einer Subdomain ansprechen und dort das Update vornehmen.
• Hat man eine Kopie erstellt die man aktualisieren kann, so sollte man zuerst die Medienverwaltung in Shopware bereinigen. Durch die neue Ressource in der API zur Verwaltung der Bilder ändert sich in der Schnittstelle die Art der Zuordnung.

 

Die Bereinigung der Medienverwaltung kann man folgendermaßen durchführen:

• Löschen der Bilder aus der Datenbank die Teil des Artikel Albums sind:
  DELETE FROM s_media WHERE albumID = -1;
• Löschen der Zuordnungseinträge von Artikeln zu den Medieneinträgen:
  DELETE FROM s_articles_img WHERE NOT EXISTS (SELECT * FROM s_media WHERE s_media.id = s_articles_img.media_id);

 

Möchte man auch die Dateien aus dem Medienverzeichnis löschen, so muss dies gezielt vorgenommen werden, da die Bilder dort albumunabhängig gespeichert werden. Löscht man das gesamte Verzeichnis, so könnte dies zum Verlust von Kategoriebildern und dergleichen führen.
Die Bilder liegen im Shopware Hauptverzeichnis in "/media/image/"

 

Ist die Kopie vorhanden und die Medieneinträge bereinigt, so wird eine zweite Schnittstelle angelegt die an die Kopie angebunden wird. Die Zuordnungseinträge der alten Schnittstelle für Produkte und Kategorien werden vom Support (auf Wunsch) für die neue Schnittstelle übernommen. Die Bestellungen werden die bereits in cludes vorhanden sind und mit in das kopierte System übernommen wurden, werden dann auch vom Support der neuen Schnittstelle zugeordnet, sodass diese nicht neu importiert werden.

 

Nach Übernahme der Daten und den nötigen Schritten wird der Abgleich zur Kopie vorgenommen. Ist dieser komplett abgeschlossen wird das Ergebnis der Übertragung stichprobenartig von den Technikern geprüft. Sind keine offensichtlichen Dinge zu beanstanden kann der Kunde das Ergebnis ebenfalls nochmal überprüfen.

 

Wenn die Übertragung zufriedenstellend abgeschlossen wurde, dann kann die Domain auf den neuen Shop umgezogen werden. Das alte System kann dann gelöscht werden, wenn man es nicht mehr braucht.

 

 

Bilder-URL Dienst

Lesen Sie bitte zuerst die Dokumentation des Bilder-URL Dienstes: /article/help/technischer_hintergrund/bilder-url_dienst.htm

Die Medienverwaltung von Shopware speichert die Bilder mit dem Namen, der sich in der URL befindet. Mit dem oben genannten Dienst kann man über spezielle Alias URLs auf die Bilder zugreifen.

Diese URL ist auch die, die durch die aktivierte Option "Bild-Alias-URL verwenden" an den Shop übertragen wird. Dadurch wird das Bild dann mit diesem Namen in Shopware abgelegt.

Dies gilt allerdings nur für neue Bilder, existente werden nicht aktualisiert. Der Grund dafür ist, dass die Shopware API nicht die Möglichkeit bietet vorhandene Einträge in der zentralen Medienverwaltung zu verändern, also beispielsweise die Datei umzubenennen.
Für mehr Infos siehe hier.

Für Bilder, die nun direkt mit einem Alias hochgeladen werden, und gültig sind, werden nun mit der Konfiguration der Schnittstelle die Bild-Alias-Werte übertragen.