Einleitung
Das Plugin IntoSymbioConnector stellt eine Schnittstelle zwischen SYMBIOCOMMERCE rund
Shopware 6.5 bereit und deckt die folgenden Bereiche ab:
Kategorien
Initial Anlage, neue Kategorien, Änderungen (inhaltlich und Baumstruktur), Entfernung
Produkte
Initial Anlage, neue Artikel, Änderungen, Entfernung
Einzel- und Variantenartikel
Einschliesslich Produkt-Media-Dateien
Lagerbestand
Aktualisierung des Lagerbestands aus SYMBIOCOMMERCE
Kunden
Übertragung neu angelegter Kunden inklusive Adressbuch sowie aller folgender Änderungen
Bestellungen
Übertragung neuer Bestellungen
Versandinformationen
Import der Versandinformationen per CSV-Datei und automatische Bestimmung des Bestellstatus (teilweise oder vollständig ausgeliefert) in Shopware.
Konfiguration
Für die Konfiguration sind die folgenden Einstellungen vorzunehmen:
Symbio Zugangsdaten
Ihre Zugangsdaten für das SYMBIOCOMMERCE-API erhalten Sie von Symbionet. Alle Felder sind auszufüllen.
Symbio-API URL: Die URL für das produktive SYMBIOCOMMERCE-System wird von Symbionet vergeben.
Client-id: Name des gewünschten Clients wird von Symbionet vergeben.
Username: Ein gültiger Benutzer des Accounts für den der SYMBIOShop aufgesetzt wurde.
Legen sie auf SYMBIOCOMMERCE in der Benutzerverwaltung ihres Geschäftskontos einen dezidierten Benutzer für den SYMBIOConnector an.
Vergeben sie ihm Administratorrechte. Somit wird verhindert, dass das Passwort ungewollt verändert wird und die Verbindung zu SYMBIOCOMMERCE fehlschlägt.
Client-Secret: Das Client-Secret des Clients, wird von Symbionet vergeben.
Die id des Sales-Group-Channels: Für SYMBIOShop wird die Id 3 verwendet.
Land (ISO-2): Das Land des Kataloges, welchen wir anbinden wollen.
Währung (ISO-3): Die Währung des Kataloges, welchen wir anbinden wollen.
Symbio Konfiguration
Hauptkategorie für Symbio-Kategoriebaum: Wählen Sie eine Kategorie aus der Auswahlliste. Welche dies ist, hängt vom Setup Ihres Shops bzw. der verwendeten Verkaufskanäle ab.
Medien-Ordner für Produktbilder: Wählen Sie einen Medienordner aus, in dem die aus SYMBIOCOMMERCE importierten Produktbilder abgelegt werden.
Produkt-Sichtbarkeit - Sales-Channel: Wählen Sie einen Verkaufskanal aus, dem die SYMBIOCOMMERCE-Produkte zugeordnet werden.
Standard-Steuersatz: Wählen Sie einen Steuersatz aus, der den Produkten beim Import zugeordnet wird.
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 das Selbe. Wählen sie am Besten alle von diesen aus.
Bestellexport
Datum, ab wann die Bestellungen übertragen werden sollen.
Verzögerung der Bestellübertragung
Administration
Kategoriebaum
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.
Produkte und Artikel
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.
Media (Produktabbildungen)
Die Produktabbildungen werden bei der Übertragung der Produkte aus SYMBIOCOMMERCE ebenfalls automatisch zu Shopware übertragen. Eine erfolgreich übertragene Produktabbildung erkennen Sie an den Feldern in der Karte Symbio-Daten.
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
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.
In der Karte Symbio-Daten finden sie die Felder:
SymbioRecipientId identifiziert den Empfänger in SYMBIOCOMMERCE.
SymbioRecipientIdentification identifiziert den Kunden in SYMBIOCOMMERCE.
Erzeugt zeigen den Zeitstempel der ersten Übertragung.
Aktualisiert zeigen den Zeitstempel der letzten Aktualisierung.
Prüfsumme enthält die Prüfsumme der zuletzt an SYMBIOCOMMERCE übermittelten Daten.
Bestellungen
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.
Nachträgliche Änderungen in einer Bestellung werden nicht übertragen.
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 SymbioShop unterbrochen wurde, entsteht bei einer erneuten erfolgreichen Übertragung keine doppelte Bestellung.
Die zu verarbeitenden CSV-Dateien sind ohne Header und enthalten je Packstück eine Zeile mit den folgenden Feldern:
Beschreibung | Datentyp | Bemerkung |
ERP-Auftragsnummer | int | |
ERP-Auftragsposition | int | |
Shop-Aufragsnummer | string | Shopware Bestellnummer |
Shop-Auftragsposition | int | Position in der Shopware-Bestellung |
Menge | int | |
Carrier | string | |
Handling Unit | string | |
Tracking-URL | string |
Import CSV-Versandmeldungen
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.
Die zu importierenden CSV-Dateien sind z.B. per FTP in diesem Verzeichnis abzulegen:
<shopware root>/files/plugins/into_symbio_connector/delivery
Es werden regelmässig alle in diesem Verzeichnis abgelegten Dateien mit der Dateiendung .csv verarbeitet. Nach erfolgreicher Verarbeitung werden die Dateien in das Verzeichnis
<shopware root>/files/plugins/into_symbio_connector/archive/delivery
verschoben.
Verwendete APIs
Connector / SYMBIOCOMMERCE
GET https://{{Host}}/services/product/api/external/v1/categories
GET https://{{Host}}/services/product/api/external/v1/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}
Troubleshooting
Abgebrochene Message-Verarbeitung
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.
Bereits vorhandene Media-Dateien
Fehlermeldung:
An exception occurred while executing 'INSERT INTO
`into_symbio_connector_media_addons` (`id`, `media_id`,
`symbio_id`, `hash`, `created_at`) VALUES (' …
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.
Bereits vorhandene Produkte
Fehlermeldung:
Product with number "xxxxx" already exists.
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.
http://availabilitiesmock.prelive.svc.cluster.local:8055/api/availabilities
Bestellungen
Bestellung wird nicht übertragen
"itemErrors\":{\"1\":{\"ITEM\":{\"orderPosition\":1,\"uid\":\"Mw.TUFOVUFMX0lOUFVU.YmwtYS1h\",\"articleSalesId\":196302,\"orderQuantity\":1,\"salesPriceAbsolute\":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\",\"