Inhalt:

Allgemeines

In diesem Dokument ist die Shopware 5 Schnittstelle näher beschrieben. Bei Fragen können sie sich gerne an unseren Support wenden. Die Kontaktdetails sind auf der Seite Logistikschnittstellen zu entnehmen.

Nachfolgend erhalten sie wichtige Informationen zur Shopware Schnittstelle. Nachdem die Konfiguration der Anbindung geklärt ist, werden wir diese auf Wunsch für sie einrichten. Sie können dann Bestellungen in das Logistiksystem übergeben und erhalten Lagerbestände und Versandinformationen aus dem Logistiksystem.

Leistungsumfang

Implementierte Funktionen

Die Module Auftragsübernahme, Statusrückgabe inkl. Track&Trace sowie die Lagerbestandspflege sind implementiert.

Unterstützte Versionen

Shopware ab Version 5.0.0 wird unterstützt. Die Shopware Version 6.x wird noch nicht unterstützt.

Technische Anbindung

Die Shopware-Anbindung  ist über die Shopware API realisiert.

Voraussetzungen

Zur Anbindung benötigen wir die Shop URL, den Benutzernamen und den zugehörigen API-Key.

Außerdem benötigen wir eine Vorgabe wie die Schnittstelle auf unserer Seite zu konfigurieren ist. Hierfür bitten wir um die Beantwortung der nachfolgenden Fragen unter dem Punkt "Konfigurationsoptionen der Schnittstelle".

Optionale PDF Belegübergabe

Optional können die zum Auftrag existierenden Belege übernommen werden. Beigefügt erhalten sie zwei Plugins für ihr Shopware Setup. Diese sind nur erforderlich, wenn zugehörige PDF Dokumente übergeben werden sollen. Ist nicht geplant PDF Dokumente mitzugeben, bedarf es keiner Installation der Plugins. Die Plugins können kostenfrei aus dem Shopware Store bezogen werden.

Funktion der Plugins (Kompatibel zu Shopware 5):

Erweiterung der API um das PDF-Dokument.
Bezugsquelle: http://store.shopware.com/bauer15235570746/bestelldokumente-api.html

Automatisches erstellen der PDF Dokumente mit Cronjob, nach Bestellabschluss.
Bezugsquelle: http://store.shopware.com/bauer96565885332/automatische-dokumenterstellung-rechnung-oder/und-lieferschein.html

Konfigurationsoptionen der Schnittstelle

Übertragungseinstellungen

OptionMögliche WerteBemerkung
Aufträge übertragenja/neinAktiviert die Übernahme von Aufträgen.
Status & Sendungsdaten übertragenja/neinAktiviert die Rückgabe von Status- und Sendungsdaten.
Lagerbestände übertragenja/neinAktiviert die Übernahme von Lagerbeständen.

Dokumente

OptionMögliche WerteBemerkung
Auf PDF Dokumente warten und Auftrag erst dann übernehmenja/neinBei aktivierter Option, wird der Auftrag erst übernommen, nachdem ein PDF nach nachstehender Vorgabe erstellt wurde.
Lieferschein übertragenja/neinIst die Option "Auf PDF Dokumente warten und Auftrag erst dann übernehmen" mit "nein" belegt, hat diese Option keine Funktion.
Rechnung übertragenja/neinIst die Option "Auf PDF Dokumente warten und Auftrag erst dann übernehmen" mit "nein" belegt, hat diese Option keine Funktion.

Artikel

OptionMögliche WerteBemerkung
Ausgeschlossene Artikelnummern<Artikelnummern>Die hier angegeben Artikelnummern werden von der Übernahme ausgenommen.
Artikelnummer == SKUja/neinIst diese Option mit "ja" belegt, wird die Artikelnummer in Shopware auch als Lagerhaltungsnummer verwendet. Das Attributfeld für SKU ist dadurch nicht erforderlich.
Attributfeld für SKU, fall nicht Artikelnummer0 - 20Ist die Option "Artikelnummer == SKU" mit "ja" belegt, hat diese Option keine Funktion. Der Spaltentyp in Shopware ist "Einfacher Text".
Attributfeld für MHD0 - 20Im Rahmen des Lagerbestandsupdate, wird in dieses Feld das MHD des Artikels hinterlegt. Liegen verschiedene MHD am Lager, wird hier immer das kürzeste MHD übergeben. Ist die Option mit dem Wert "0" konfiguriert, wird diese Funktion deaktiviert. Der Spaltentyp in Shopware ist "Datumsfeld".

Artikel - Sonderfunktionen

OptionMögliche WerteBemerkung
Attributfeld für Bundle-Artikel0 - 20

Ist die Option mit dem Wert "0" konfiguriert, wird diese Funktion deaktiviert. Ist das Attributfeld im Shop leer, findet keine Anwendung statt. Auf die Lagerbestandsaktualisierung hat dieses Feld ebenfalls keinen Einfluss. Ist dieses Feld mit einem Wert belegt wird die Angabe der Artikelnummer oder SKU für die Übergabe an die Logistik ignoriert.

Diese Funktion dient dazu, anstelle des eigentlichen Artikels, die hier definierten Artikel im Lager zur Auslieferung zu bringen. Es handelt sich also um ein Bundle/Set ohne das Bundlemodul des Shops hierfür zu verwenden. Der Spaltentyp in Shopware ist "Einfacher Text".

Das Feld hat folgenden Syntax "<SKU>;<Menge>|<SKU>;<Menge>|<SKU>;<Menge>|<SKU>;<Menge>". Dieser Wert kann bis zur maximalen Feldlänge wiederholt werden. Beispiel: Der Artikel hat die Artikelnummer "ABC123". Bestellt der Kunde 2 Stück dieses Artikels bei dem folgende Werte hinterlegt sind "LAGER1;1|LAGER2;4" wird im Logistikauftrag folgendes übergeben. Der Kunde erhält dann 2x LAGER1 (2x bestellt x 1x LAGER1) und 8x LAGER2 (2x bestellt x 4x LAGER2). Bei Mengenangaben ist ein Punkt als Dezimaltrenner zu verwenden. Beispiel: Menge = "4,25 kg", Angabe im Feld = "4.25".

Aggregation der Bundle-Artikelja/nein

Bundle-Artikel in einem Auftrag mit dem gleichen Artikel werden in eine Position zusammengefasst und die Einzelmengen aufsummiert.

Die Lagerbundles im "Attributfeld für Bundle-Artikel" werden dadurch nicht aggregiert. Es werden nur die Bestellpositionen in Shopware selbst zusammenfasst.

Bestellung

OptionMögliche WerteBemerkung
Aggregation der Bestellpositionenja/nein

Bestellpositionen in einem Auftrag mit dem gleichen Artikel werden in eine Position zusammengefasst und die Einzelmengen für die Übergabe an das Lager aufsummiert.

Keine Übertragung der Anredeja/neinDie persönliche Anrede (Herr/Frau) des Kunden wird bei der Übertragung nicht mit übernommen.
Kontaktdaten in Lieferadresse übernehmenja/neinBei aktivierter Option werden die Kontaktdaten (E-Mail, Telefon- und Faxnummer) aus der Rechnungsadresse übernommen. Sofern diese nicht in der Lieferadresse angegeben wurden.
DHL Packstationsadresse aufbereitenja/neinBei aktivierter Option wird die Lieferadresse nach vorgaben der DHL für Packstationen formatiert, sofern die Lieferung an eine Packstation erfolgt.
Fehlende Hausnummer mit '0' ergänzenja/neinHat der Kunde in der Adresse keine Hausnummer angegeben wird nach der Straßenangabe als Hausnummer eine '0' ergänzt. Hintergrund ist hier das Bestellungen die fristgerecht versendet werden müssen ansonsten nicht versendet werden können. Daher ist es in einigen Fällen ggf. günstiger die Sendung bewusst falsch Adressiert zu versenden. Bevor die Hausnummer mit '0' belegt wird, versucht die Schnittstelle im Adresszusatzfeld 1 und 2 eine Hausnummer zu ermitteln und in die Straße umzuziehen.

Lagerbestand

OptionMögliche WerteBemerkung
Reservieren der Artikelja/neinFalls ja, dann ist der frei verfügbare Lagerbestand - Menge in offenen Bestellungen des Shops = Lagerbestand im Shop
Lagerbestand in Shop übertragenja/nein

Tracking

OptionMögliche WerteBemerkung
Trackingdaten in Shop übertragenja/nein
Verwerfen zusätzlicher Trackingnummern im Feld 'Tracking Code'ja/nein

Ist die Option mit dem Wert 'nein' konfiguriert, wird diese Funktion deaktiviert und alle Sendungsnummern werden im Feld 'Tracking Code' zur Bestellung abgelegt. Das ist das Standardverhalten.

Bei aktivierter Option ('ja') wird nur die erste Sendungsnummer im Feld 'Tracking Code' zur Bestellung abgelegt. Alle weiteren Sendungsnummern, sofern vorhanden, sind im internen Kommentar zur Bestellung einsehbar.

Versandmengen auf Positionsebene bei Versand setzenja/neinBei aktivierter Option werden die Bestellpositionen im Rahmen der Sendungsdatenrückgabe aktualisiert. Die Versandmenge wird dadurch immer auf die Bestellmenge gesetzt. Dadurch werden die reservierten Mengen in Pickware aufgelöst und als versendet gekennzeichnet.

Statuskennzeichen der Bestellungen

OptionMögliche WerteBemerkung
Freigabe zum Versand

Auftragsstatus: offen

Zahlstatus: "komplett bezahlt" ODER "komplett in Rechnung gestellt"

Die vorstehenden Angaben sind die Standardwerte der Schnittstelle, bitte anpassen falls abweichend.

Es sind alle in Shopware zuläsigen Statuswerte, die in der Standardinstallation verfügbar sind (Shopware Core).

Zusätzlich werden benutzerdefinierte Stati mit der internen ID 9 - 99 beim Auftragsstatus und der internen ID 36 - 99 beim Zahlstatus unterstützt.

Bestellung ist übertragenAuftragsstatus: "zur Lieferung bereit"

Die vorstehenden Angaben sind die Standardwerte der Schnittstelle, bitte anpassen falls abweichend.

Der Zahlstatus wird nicht mehr ausgewertet oder verändert.

Bestellung ist abgeschlossenAuftragsstatus: "komplett ausgeliefert"

Die vorstehenden Angaben sind die Standardwerte der Schnittstelle, bitte anpassen falls abweichend.

Der Zahlstatus wird nicht mehr ausgewertet oder verändert.

Fehler in der BestellungAuftragsstatus: "klärung notwendig"

Details hierzu stehen, bei einem Fehler, im internen Kommentar der Bestellung.

Die vorstehenden Angaben sind die Standardwerte der Schnittstelle, bitte anpassen falls abweichend.

Der Zahlstatus wird nicht mehr ausgewertet oder verändert.

Versand

Nur falls mehr als eine Versandart verwendet wird, sind angaben erforderlich. Standardmäßig wird immer als versichertes Paket versendet.


OptionMögliche WerteBemerkung
Abholung ab Lager<Name der Versandart(en)>Die gewählte Versandmethode führt zu einer Bereitstellung der Waren zur Abholung ab Lager beim Dienstleister. Bitte geben sie pro Zeile die Bezeichnung der Versandart an, auf die diese Regel zutrifft.
Versicherter Versand<Name der Versandart(en)>

Dies ist die Standardversandart. Die Information wird aus dem Feld "Name" entnommen.

Die gewählte Versandmethode führt zu einem versicherten Versand beim Dienstleister. Bitte geben sie pro Zeile die Bezeichnung der Versandart an, auf die diese Regel zutrifft.

Unversicherter Versand<Name der Versandart(en)>Die gewählte Versandmethode führt zu einem unversicherten Versand beim Dienstleister. Bitte geben sie pro Zeile die Bezeichnung der Versandart an, auf die diese Regel zutrifft.
Speditionsversand<Name der Versandart(en)>Die gewählte Versandmethode führt zu einem versicherten Versand per Spedition beim Dienstleister. Bitte geben sie pro Zeile die Bezeichnung der Versandart an, auf die diese Regel zutrifft.
Gesperrte Versandarten<Name der Versandart(en)>Die hier angegebenen Versandarten sind gesperrt. Eine Übernahme in die Logistik findet für Aufträge mit diesen Versandarten nicht statt.
Interner Warenverkehr<Name der Versandart(en)>Die gewählte Versandmethode führt zu einem internen Warenverkehr im Lager des Dienstleisters. Bitte geben sie pro Zeile die Bezeichnung der Versandart an, auf die diese Regel zutrifft.

Zahlung

OptionMögliche WerteBemerkung
Zahlarten ID für Nachname<ID der Zahlart im Shop>

Standardwert ist "3" (Shopware Standard).

Bei dieser Zahlart wird der Bruttogesamtbetrag der Bestellung als Einzugsbetrag übergeben.

Sonderfunktionen

OptionMögliche WerteBemerkung
Zuordung von Attributen<attrN|Feldname>

Hier können die Standardattribute für Artikel attr1 bis attr20 eigenen benutzerdefinierten Feldern zugewiesen werden.

Der Aufbau ist '<Standardattributsfeld>|<Benutzerdefiniertes Attributsfeld>'.

Dublettenprüfung für Bestellungenja/neinDiese Funktion prüft ob die Bestellung bereits übernommen wurde. In Sonderfällen wird durch externe Plugins die Bestellung wieder in den Status 'offen' gesetzt. Dadurch wird die Bestellung erneut übertragen. Hier wird anhand der internen ID der Bestellung geprüft ob diese bereits übernommen wurde. Das erfolgt unabhängig vom Statuswechsel der Bestellung.

Storefront

OptionMögliche WerteBemerkung
Begrenzung auf Storefrontlt. AuswahllisteDie Begrenzung auf ein Storefront führt dazu das alle Bestellungen der anderen Storefronts nicht übernommen werden. Wird die Einstellung '[Alle Storefronts]' ausgewählt werden alle Aufträge aus allen Quellen übernommen.
Ausschluss eines Storefrontlt. AuswahllisteDer Ausschluss eines Storefront führt dazu das alle Bestellungen dieses Storefronts nicht übernommen werden. Wird die Einstellung '[Keine Storefront]' ausgewählt ist kein Storefront von der Übernahme ausgeschlossen.
Manuelle Whitelist für StorefrontsEindeutige Liste der Storefront ID'sSind in dieser Liste Einträge vorhanden, setzt dies die 'Begrenzung auf Storefront' und 'Ausschluss eines Storefront' außer Kraft. Pro Zeile ist die eindeutige ID des Storefronts, wie in Shopware geführt, anzugeben. Alle Bestellungen die nicht von einem der Storefront stammen, die in dieser Liste aufgeführt sind, werden von der Übernahme ausgeschlossen.

Verhalten der Schnittstelle

Nachfolgend haben wir ihnen zum besseren Verständnis, das Verhalten der Schnittstelle näher erläutert.

Übergabe von Aufträgen

Befindet sich der Auftrag im Status "Freigabe zum Versand" wird dieser von der Schnittstelle übernommen. Nach der erfolgreichen Übernahme wird der Status "Bestellung ist übertragen" gesetzt.

Ein bereits übernommener Auftrag wird erneut übertragen, wenn im Shop der Status "Freigabe zum Versand" wiederholt gesetzt wird.

Aktivierte PDF Übernahme zum Auftrag, ohne obligatorisch erforderliche Plugineinrichtung im Shop

In diesem Fall, wird der Auftrag nicht übernommen.

FAQ

Welche Rechte sind im Shop für den API Benutzer zu hinterlegen?

API-EndpunktRechte
URLRessourceerstellenlesenaktualisierenlöschenBemerkungen

/api/articles

articles

-

X

-

-

X = erteilt / - = nicht erforderlich

/api/caches

caches

-

-

-

-


/api/categories

categories

-

X

-

-


/api/customerGroups

CustomerGroup

-

X

-

-


/api/customers

customer

-

X

-

-


/api/generateArticleImages

article

-

-

-

-


/api/media

media

-

-

-

-


/api/orders

order

-

X

X

-


/api/propertyGroups

PropertyGroup

-

X

-

-


/api/shops

shop

-

X

-

-


/api/translations

translations

-

-

-

-


/api/variants

variants

-

X

-

-


/api/version

version

-

X

-

-


/api/documents

order/documents

-

X

-

-

Dokumentenabruf (Plugin)

Was passiert wenn ein übertragener Auftrag vor Auslieferung in Shopware bereits gelöscht wurde?

Schlägt das zurückgeben von Statusinformationen oder Sendungsdaten fehl, weil z. B. der Auftrag nicht mehr in Shopware gefunden wird, wird der Auftrag mit Fehlerkennzeichen in der Schnittstelle geschlossen. Es wird nicht mehr Versucht den Status zu übermitteln.


  • No labels