Das Plugin IntoSymbioConnector stellt eine Schnittstelle zwischen SYMBIOCOMMERCE und Shopware 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.

• 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.

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. Einige Statuscodes sind mehrfach vorhanden, stehen aber nicht für dasselbe. Wählen Sie am besten alle von diesen aus.

Bestellexport

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

2. Verzögerung der Bestellübertragung

Kategorien

In der PlugInConfig treffen Sie auch eine Auswahl, welche bestehende Category 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 SelectBox können Sie dann die entsprechende Kategorie auswählen.

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.

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.

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 und 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.

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:

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.