Das Plugin IntoSymbioConnector stellt eine Schnittstelle zwischen

SYMBIOCOMMERCE und Shopware (=> Version 6.5) bereit. Der Connector deckt die folgenden Bereiche ab:

Kategorien

Initial Anlage, neue Kategorien, Änderungen (inhaltlich und Baumstruktur),

Deaktivierung

Produkte

• Initial Anlage, neue Artikel, Änderungen,

• Deaktivierung

• Einzel- und Variantenartikel

• Einschliesslich Produkt-Media-Dateien

Lagerbestand

Aktualisierung des Lagerbestands aus

SYMBIOCOMMERCE

Kunden

Übertragung neu angelegter Kunden inklusive Adressbuch

Bestellungen

Übertragung neuer Bestellungen

Versandinformationen

Import der Versandinformationen per CSV-Datei und automatische Bestimmung des Bestellstatus (teilweise oder vollständig ausgeliefert) in Shopware.

Im Folgenden zeigen wir, wie Sie das Plugin anwenden können. Anschliessend geben wir Ihnen auch Tipps für die Behebung häufig auftauchender Fehler.

Damit Sie unser Plugin korrekt anwenden können, wird ein Shopware konformes aufgesetztes gehostetes Shopware-System vorausgesetzt.

Wir empfehlen Ihnen dafür ein Managed Shopware Hosting bei einem zertifizierten Shopware Hoster:

https://www.shopware.com/de/partner/hosting/
Zudem benötigen Sie eine Shopware Agentur, die Ihnen bei Problemen weiterhelfen kann. Für die Nutzung der Shopware-Software beachten Sie die Systemvoraussetzungen.

 https://developer.shopware.com/docs/guides/installation/requirements.html

Auf der Konsole des Hosting Servers müssen die sogenannten "CLI" Befehle ohne root-Berechtigungen ausführbar sein.

https://docs.shopware.com/de/shopware-6-de/tutorials-und-faq/shopware-cli

Wir empfehlen Ihnen, die Installation des IntoSymbioConnector-Plugins zuerst auf einer Shopware-Testumgebung durchzuführen. Die Testumgebung sollte entsprechend ihrem Live-Shop konfiguriert sein. So können Sie in aller Ruhe die Funktionalität und Bestellungen ausprobieren.

So gehen Sie vor:

1. Das Plugin wird über die Shopware-Admin (Erweiterungen -> Meine Erweiterungen) installiert.

2. Über die Funktion "Erweiterung hochladen" laden Sie die gelieferte zip-Datei hoch.

3. Anschliessend installieren und aktivieren Sie das Plugin.

Nach der erfolgreichen Installation können Sie mit der Konfiguration beginnen. In zwei Schritten nehmen Sie folgende Einstellungen vor (alle Felder sind obligatorisch):

Zugangsdaten für das Symbio-API

1. Symbio-API URL: Die URL für das produktive SYMBIOCOMMERCE-System (oder das Staging System) haben Sie von Symbionet erhalten.

2. Client-id: Den Namen des Clients haben Sie von Symbionet erhalten.

3. Username: Ein gültiger Nutzer des SYMBIOCOMMERCE-Accounts des Shopbetreibers.

   1. Legen Sie auf SYMBIOCOMMERCE in der Nutzerverwaltung Ihres Geschäftskontos einen neuen, separaten Nutzer an, der nur im Zusammenhang mit dem SYMBIO Connector verwendet wird. So verhindern Sie, dass das Passwort ungewollt verändert wird und dadurch dann die Verbindung zu SYMBIOCOMMERCE fehlschlägt.

   2. Weisen Sie dem Nutzer die Administratorrechte zu.

• Client-Secret: Das Client-Secret des Clients haben Sie von Symbionet erhalten.

• Die Id des Sales-Group-Channels: Für den SYMBIO Shop tragen Sie “3” ein. Ab Version 5.3.2 ist dieser Parameter nicht mehr nötig.

• Land (ISO-2): Der zweistellige ISO-Code des Landes, in dem Sie die Verkaufsgruppe anbieten wollen.

• Währung (ISO-3): Der dreistellige ISO-Code der Währung, die Sie für die Verkaufsgruppe nutzen.

Symbio-Konfiguration:

1. Hauptkategorie für Symbio-Kategoriebaum: Wählen Sie eine Kategorie aus der Auswahlliste. Welche genau, hängt vom Setup Ihres Shops bzw. der verwendeten Verkaufskanäle ab.

   In der PlugInConfig treffen Sie auch eine Auswahl, welche bestehende Kategorie als Root dienen soll. Beim Aufruf der Kategorien über den Endpunkt /services/product/api/external/v1/categories wird die ganze Struktur aus SYMBIOCOMMERCE geliefert. In der Select-Box können Sie die entsprechende Kategorie auswählen.

2. Medien-Ordner für Produktbilder: Wählen Sie einen Medienordner aus, in dem die aus SYMBIOCOMMERCE importierten Produktbilder abgelegt werden.

3. Produkt-Sichtbarkeit - Sales-Channel: Wählen Sie einen Verkaufskanal aus, dem die SYMBIOCOMMERCE-Produkte zugeordnet werden.

4. Standard-Steuersatz: Wählen Sie für Ihre Produkte den gesetzlichen Steuersatz aus. Dieser wird den Produkten beim Import zugeordnet.

5. Liste der Bestell- und Zahlungsstatuscodes zur Übertragung: Wählen Sie einen oder mehrere Statuscodes aus, bei deren Auftreten die Übertragung einer Bestellung zu SYMBIOCOMMERCE ausgelöst wird.

6. ERP Wert - Versandkosten:
   In spezifischen Fällen können Sie dieses Feld benutzen, um einen Wert für die Versandkosten einzutragen.

   Über die SYMPIOCOMMERCE Bestell-API wird der Wert beim Auslesen der Bestellung mitgeliefert, um ins ERP-System übertragen zu werden.

Bestellexport

1. Datum, ab wann die Bestellungen übertragen werden sollen.

2. Verzögerung der Bestellübertragung in Minuten erfassen

Produkt-Synchronisation

1. Preise überschreiben: Wenn die Produkt-Synchronisation von SYMBIOCOMMERCE auf Shopware durchgeführt wird und der Radio-Button aktiviert ist, werden die Preise im Shop überschrieben.

2. Medien aktualisieren: Bei der Produkt-Synchronisation werden die Medien (Bilder, Videos, PDFs) auf den aktuellen Stand der Daten von SYMBIOCOMMERCE im Shop gesetzt. Dabei können in Shopware hinzugefügte Medien überschrieben werden, falls es Differenzen zu SYMBIOCOMMERCE Medien gibt.
   

Storefront Einstellungen

1. Verfügbarkeiten überprüfen: Ist diese Funktion aktiv, wird beim Hinzufügen eines Artikels in den Warenkorb seine Verfügbarkeit überprüft. So können jene Artikel, die in der Zwischenzeit nicht mehr verfügbar sind, nicht in den Warenkorb gelegt werden.

2. Download-Tab anzeigen: Ist der Radio-Button aktiv und sind dem Produkt/Artikel PDF-Dateien zugewiesen, werden die PDF-Dateien in der Detailübersicht des Produkts unter dem Reiter “Downloads” angezeigt. Sie können mittels Klick heruntergeladen werden.

Die einzelnen Import- und Export-Funktionen der Schnittstelle werden über Scheduled-Tasks gesteuert. Die Ausführungsintervalle sind in dieser Tabelle zusammengefasst:

Eine Änderung der Intervalle oder eine Deaktivierung der Tasks ist zur Zeit nur über die Bearbeitung der Tabelle scheduled_task in der Shopware-Datenbank möglich.

Synchronisation Sperre

Zwischen 16:00 und 04:00 Uhr (UTC) werden Synchronisationen gesperrt.

CLI-Command werden auf dem Terminal des Shopware-Hosting-Servers ausgeführt.

into:products:sync [-m|--mode [stack|update|check]] [-id|--productId [PRODUCTID]]

Eine aus SYMBIOCOMMERCE übernommene Kategorie erkennen Sie in der Administration an den in der Karte Symbio-Daten angezeigten Feldern.

In der Karte Symbio-Daten finden sie die Felder:

• Symbio-CategoryId finden Sie die zugehörige CategoryId aus SYMBIOCOMMERCE.

• Erzeugt zeigt den Zeitstempel der ersten Übertragung.

• Aktualisiert zeigt den Zeitstempel der letzten Aktualisierung.

• Prüfsumme enthält die Prüfsumme der zuletzt an SYMBIOCOMMERCE übermittelten Daten.

Auf SYMBIO Commerce hinzugefügte Artikel werden in Shopware hinzugefügt. Das Produkt bleibt aktiviert.

Einen aus SYMBIOCOMMERCE übernommenen Artikel (in Shopware als Produkt bezeichnet) erkennen Sie in der Administration an den in der Karte Symbio-Daten angezeigten Feldern und dienen der Identifikation der Produkte und Varianten.

In der Karte Symbio-Daten finden Sie die Felder:

• SymbioProductId zeigt die ProductId aus SYMBIOCOMMERCE - ist bei Varianten leer.

• SymbioArticleId zeigt die ArticleId aus SYMBIOCOMMERCE - ist bei Produkten leer.

• SymbioArticleSKU zeigt die SKU des Artikels aus SYMBIOCOMMERCE - ist bei Produkten leer.
  

Handelt es sich um ein Einzelprodukt (d.h. das Produkt hat keine Varianten), sind alle diese drei Felder gefüllt. Wenn es sich um die Kopfdarstellung eines Variantenprodukts handelt, ist nur das Feld SymbioProductId gefüllt.

Handelt es sich um eine Produktvariante, sind dagegen nur die Felder SymbioArticleId und SymbioArticleSKU gefüllt.

• Erzeugt zeigt den Zeitstempel der ersten Übertragung.

• Aktualisiert zeigt den Zeitstempel der letzten Aktualisierung.

• Prüfsumme enthält die Prüfsumme der zuletzt an SYMBIOCOMMERCE übermittelten Daten.

Die Produktabbildungen werden aus SYMBIOCOMMERCE ebenfalls automatisch zu Shopware übertragen.

Aktualisierung der Medien:

• Auf SYMBIO Commerce gelöschte Producktbilder werden auf Shopware gelöscht.

• Auf SYMBIO Commerce hinzugefügte Produktbilder werden auf Shopware hinzugefügt.

• Auf SYMBIO Commerce hinzugefügte Artikelbilder werden auf Shopware übernommen.

• Auf SYMBIO Commerce gelöschte Artikelbilder werden auf Shopware gelöscht.

• Wird auf SYMBIO Commerce ein Bild mit einem anderen überschrieben, wird dies nicht übernommen, weil die Medien-Id gleich bleibt.

• Auf Shopware gelöschte Bilder werden wieder neu angelegt.

Die Produktabbildungen sind an den Feldern in der Karte SYMBIO-Daten erkennbar.

In der Karte Symbio-Daten finden Sie die Felder:

• SymbioMediaId identifiziert die Produktabbildung in SYMBIOCOMMERCE.

• Erzeugt zeigt den Zeitstempel der ersten Übertragung.

• Aktualisiert zeigt den Zeitstempel der letzten Aktualisierung.

• Prüfsumme enthält die Prüfsumme der zuletzt an SYMBIOCOMMERCE übermittelten Daten.

Die Infos werden nun übernommen und steuern die Verfügbarkeiten im Shop.

Kundendaten und Adressen werden nach ihrer Erfassung oder Aktualisierung in Shopware an SYMBIOCOMMERCE übertragen. Eine erfolgreiche Übertragung erkennen Sie in der Administration an den in der Karte Symbio-Daten angezeigten Feldern.

Empfänger, die noch nicht in SYMBIOCOMMERCE existieren, werden vor einer Übertragung einer Bestellung mit Symbio-Artikeln angelegt. Eine Prüfung anhand der SymbioID stellt sicher, dass kein Empfänger doppelt angelegt wird.

In der Karte Symbio-Daten finden Sie folgende Felder:

In Shopware getätigte Bestellungen werden dem konfigurierten Intervall entsprechend (Scheduled Task) an SYMBIOCOMMERCE übertragen. Eine erfolgreich übertragene Bestellung erkennen Sie an den Feldern in der Karte Symbio-Daten.

In der Karte Symbio-Daten finden Sie die Felder:

SymbioOrderId identifiziert die Bestellung im SYMBIOCOMMERCE.

SymbioOrderStatus zeigt den von SYMBIOCOMMERCE vergebenen Order-Status an. Dieser sollte in der Regel "APPROVED" sein, wird hier ein anderer Wert gezeigt, so sollte die ordnungsgemässe Verarbeitung der Bestellung in SYMBIOCOMMERCE überprüft werden.

SymbioZeitstempel gibt den Zeitpunkt der Übertragung an SYMBIOCOMMERCE an.

Button 'Auftrag zurücksetzen'

Falls eine Bestellung nicht erfolgreich übertragen wurde, haben Sie die Möglichkeit, die Übertragung zu zurückzusetzen, indem Sie auf den Button 'Auftrag zurücksetzen' klicken. Dadurch wird sichergestellt, dass die Bestellung beim nächsten Übertragungsintervall erneut übermittelt wird.

Im Falle, dass die Bestellung zwar in SYMBIOCOMMERCE erstellt wurde, jedoch die Rückmeldung an den SYMBIO Shop unterbrochen wurde, entsteht bei einer erneuten erfolgreichen Übertragung keine doppelte Bestellung.

Verarbeitung zusammengesetzter Bestellungen
Eine Bestellung bei Ihrem Shop kann Artikel aus SYMBIOCOMMERCE und anderen Quellen enthalten. Grundsätzlich weist SYMBIOCOMMERCE alle Bestellungen mit unbekannten Artikeln zurück. Deshalb ist in der Administration eine Separation eingerichtet.

In der OrderDetailView (Shopadministration) sehen Sie in der Übersicht der Bestellpositionen eine entsprechende Spalte, welche Artikel in der Bestellung aus SYMBIOCOMMERCE sind (erkennbar am “✅ -Häkchen”-Icon).

Es gibt drei Möglichkeiten, wie die Bestellungen zusammengesetzt sein können:

1. Die Bestellung enthält nur Artikel aus SYMBIOCOMMERCE.

   1. Alle Artikel werden nach SYMBIOCOMMERCE übertragen.

   2. Alle Artikel erhalten ein ✅.

   3. In der Karte Symbio-Daten steht im Feld Symbio-Order-Status “APPROVED”

2. Die Bestellung enthält keine Artikel aus SYMBIOCOMMERCE.

   1. Keine Artikel werden übertragen.

   2. Die Artikel werden nicht markiert.

   3. In der Karte Symbio-Daten steht im Feld Symbio-Order-Status “NO_SYMBIO_ORDER”
      

3. Die Bestellung ist gemischt und enthält neben Artikeln aus SYMBIOCOMMERCE auch Artikel aus anderen Quellen.

   1. SYMBIOCOMMERCE-Artikel werden übertragen und erhalten ein ✅.

   2. Die Artikel, die nicht aus SYMBIOCOMMERCE stammen, werden nicht übertragen und erhalten ein ❌ .

   3. In der Karte Symbio-Daten steht im Feld Symbio-Order-Status “APPROVED”

Der Import der Versandmeldungen aus dem Kunden ERP erfolgt per CSV-Import. Dabei werden zu jeder Bestellung die übermittelten Trackingcodes und die zugehörigen Lieferpositionen und -mengen importiert. Der Bestellstatus wird entsprechend angepasst auf "teilweise ausgeliefert" bzw. "vollständig ausgeliefert". Die übermittelten Tracking-URLs werden in der Bestellung abgelegt und damit auch dem Kunden in seiner Bestellübersicht angezeigt.

Datentrennzeichen: ; (Semikolon)

Die zu verarbeitenden CSV-Dateien sind ohne Header und enthalten je Packstück eine Zeile mit den folgenden Feldern:

Unter dem Menu - Kategorien - Symbio Dashboard finden Sie das SYMBIO Connector Dashboard.

Check for Updates only

Es überprüft SYMBIO Commerce nach geänderten Daten seit der letzten Datenaktualisierung.

Nach erfolgreicher Ausführung und Browser refresh, wird eine CSV zum Download angeboten.

Es werden die Produkte aufgelistet, in denen auf SYMBIOCOMMERCE Daten geändert wurden.

Das CSV kann über die drei Punkte heruntergeladen werden. Über die Spalte Aktualisiere [0|1] können Sie steuern, welche Produkte aktualisiert werden sollen.

0 = nicht aktualisieren

1 = aktialisieren

Das geänderte CSV kann in die Karte Aufträge (Orders) gezogen oder hochgeladen werden.

Der Produkt Update kann über die rote Schaltfläche “Update Selected Products” ausgeführt werden.

Complete Product Update

Über die Schaltfläche Complete Product Update wird im Shopware eine Aktualisierung aller Produkte und Artikeldaten durchgeführt. Es werden alle Daten überschrieben und aktualisiert. Auch zuvor geänderte Daten werden überschrieben.

Connector / SYMBIOCOMMERCE

• GET https://{{Host}}/services/product/api/external/v1/categories

• GET https://{{Host}}/services/product/api/external/v3/selling-products/channels/{shop-channelId}

• POST https://{{Host}}/services/product/api/external/v1/resource-planning/article-availability

• POST https://{{Host}}/services/recipient/api/external/v1/addresses/

• POST https://{{Host}}/services/recipient/api/external/v1/recipients

• PUT https://{{Host}}/services/recipient/api/external/v1/recipients

• POST https://{{Host}}/services/order/api/external/v2/order-placement/submit/channel/{channelId}/countryIso/{countryIso}

Sollte es bei der Verarbeitung der Messages (z.B. Neuanlage oder Aktualisierung eines Produkts, Übertragung von Bestellungen zu SYMBIOCOMMERCE usw.) zu schwerwiegenden Fehlern kommen, werden diese Messages in die Shopware-Tabelle dead_messages verschoben. Zusätzlich wird in der Spalte exception_message die Fehlerursache beschrieben.

Dieser Fehler entsteht, wenn neue Media-Dateien aus SYMBIOCOMMERCE mehrfach eingelesen werden, bevor sie in Shopware angelegt wurden. Dieser Fehler ist unkritisch und kann ignoriert werden.

Wenn dieser Fehler häufiger auftritt, sollten die Serverressourcen für die Abarbeitung der Message-Queue vergrössert werden.

Dieser Fehler entsteht, wenn neue Produkte aus SYMBIOCOMMERCE mehrfach eingelesen werden, bevor sie in Shopware angelegt wurden. Dieser Fehler ist unkritisch und kann ignoriert werden.

Wenn dieser Fehler häufiger auftritt, sollten die Serverressourcen für die Abarbeitung der Message-Queue vergrössert werden.

Bestellung wird nicht übertragen

In die Log-Datei von Shopware wird beim Fehlschlagen einer Bestellübertragung eine Fehlermeldung geschrieben.

Darin findet sich dem API-Aufruf mitgegebene Request Body

/services/order/api/external/v2/order-placement/submit/channel/3/countryIso/DE, request body: {"additionalOrderPayload":"{\"88\":0}","billingAddressId":17332,"shippingAddressId":17395,"currency":"EUR","externalMarketplaceReference":null,"externalPaymentReference":null,"externalShopReference":"10001","orderItems":[{"orderPosition":0,"orderQuantity":2,"articleSalesId":196242,"remark":"","salesPriceAbsolute":45,"uid":"MjAz.TUFOVUFMX0lOUFVU.NzAwMDA0NDE0NDQ1NzY3"}],"recipientId":9762,"remark":null,"orderOrigin":""}

Im zurück gelieferten Response Body finden sich die Meldungen mit den Ursachen des Fehlschlags:

response contents:

"itemErrors\":{\"1\":{\"ITEM\":{\"orderPosition\":1,\"uid\":\"Mw.TUFOVUFMX0lOUFVU.YmwtYS1h\",\"articleSalesId\":196302,\"orderQuantity\":1,\"salesPriceAbs
olute\":10,\"remark\":\"\"},\"ERR_MSG\":\"Der Artikel kann nicht bestellt werden.\"}},\"headerErrors\":{\"9000\":{\"ERR_MSG\":\"Die Bestellung konnte wegen Validierungsfehlern nicht verarbeitet werden.\"}},\"id\":null,\"uuid\":null,\"ownerAccountId\":3,
\"recipientIdentification\":\"d181686a0e304788b29d3b1ed9bc2376\",\"recipientName\":\"Marty McFly\",\"

In itemErrors sind die Fehler, wenn etwas mit den Artikeln nicht stimmt

In headerErrors sind allgemeine Fehler, die nicht die Artikel betreffen.