Präambel

Die IDS Webshop Schnittstelle dient der (halb-)automatischen Kommunikation zwischen der kaufmännischen Software von Handwerksbetrieben mit den Internetpräsenzen der Großhändler.

Um beiden Seiten (Handwerk und Großhandel) gerecht zu werden, soll die Kommunikation nicht nur unsichtbar Informationen austauschen, sondern Rücksicht nehmen auf die optische und inhaltliche Präsentation des Großhandels. Beim Austausch von Informationen ist es besonders wichtig, dass die gegenseitigen Referenznummern der Dokumente und der einzelnen Positionen erhalten bleiben. Es darf nicht passieren, dass wie bei dem Spiel „Stille Post“ wichtige Bezüge durch die Übergabe zum Shop und die Rückübertragung zur Handwerkersoftware verloren gehen.

Für die Handwerkersoftware ist wichtig, dass alle Webshops (Internetpräsenzen der Großhändler) auf identische Weise angesteuert werden können. Damit sind auf Seiten der Handwerkersoftware keine Sonderprogrammierungen oder spezielle Anpassungen für den Shop-Datenaustausch mehr erforderlich. Für die Großhandelsseite ergibt sich der Vorteil, dass mit einer „Standardsoftware“ der Austausch mit vielen Kunden möglich ist.

Der Umfang der Möglichkeiten kann allerdings zwischen den Großhandelssystemen differieren. Die tatsächlich nutzbaren Funktionen können über eine in der Schnittstelle definierte Abfrage festgestellt werden.

Die Webshop Schnittstelle basiert nicht auf klassischen Webservices, sondern im Wesentlichen auf der Zurverfügungstellung folgender zweier Funktionen:

• Senden von Daten und Instruktionen vom Handwerker an den Webshop und

• Empfangen von Daten und Instruktionen aus dem Webshop zurück an den Handwerker.

Zwischen diesen beiden Funktionen steht der Webshop bzw. die Internetpräsenz des Großhändlers als sogenannte Blackbox.

Daher ist diese Webshop-Schnittstelle als halbautomatische Kommunikation zu verstehen, da alle Aktionen von Seiten des Handwerkers initiiert werden müssen. Weitere manuelle Aktionen auf der Webseite des Großhändlers können erfolgen, wobei deren Ergebnisse in der Regel zur Handwerkersoftware zurück gegeben werden.

Der Webshop muss nicht zwingend zu einem Großhändler gehören, sondern kann vom Hersteller betrieben werden. In diesem Falle entfallen ggf. einige Funktionen, wie z.B. die der Übermittlung von Einkaufspreisen, Lieferkonditionen sowie Bestellabläufe.

Zu den derzeitigen Grundfunktionen der Schnittstelle gehören:

• Warenkorb senden: Übermittlung einer Artikelliste (Warenkorb) vom Handwerker an den Webshop

• Warenkorb Empfangen: Übermittlung einer Artikelliste (Warenkorb) vom Webshop an den Handwerker

• Deeplink: Aufruf einer Artikelinformationsseite vom Handwerker an den Webshop

• Logininformationen: Aufruf der Informationen die zum Login erforderlich sind

• Schnittstellenversion: Aufruf der Versionen die unterstützt werden.

Die zentrale Idee der Schnittstelle ist die Aufrechterhaltung des Workflows, sowohl auf Seiten des Handwerkers als auch auf Seiten des Großhandels. Dies wird dadurch gewährleistet, dass bei der Übermittlung von Warenkörben alle Positionen mit Referenznummern des Handwerkers und des Großhändlers erfolgen können, die von der anderen Seite keinesfalls verändert oder vernichtet werden dürfen. Dadurch soll zu jeder Zeit sichergestellt werden, dass

• auf beiden Seiten der jeweilige Bezug zu deren Vorgängern (Angebot, Bestellung, Abruf, etc.) vorhanden ist und dass

• manuelle Eingriffe (Änderungen, Ergänzungen, Löschungen) im Webshop bzw. im Warenkorb korrekt und nachvollziehbar an die Handwerkersoftware zurück übermittelt werden können. Dazu ist es wichtig, dass beim Ändern von Positionen (auch beim Wechsel der Artikelnummer) die Referenznummern des Handwerkers beibehalten werden.
  Die Tatsache, dass anscheinend viele Shops keine Änderungsfunktion haben, sondern nur Positionen löschen und neue einfügen können, ist bedauerlich und es sollte eine Überarbeitung angestrebt werden.

Die Schnittstelle ist so konstruiert, dass weitere Funktionen definiert werden können. Auf- und Abwärtskompatibilität werden durch eine Versionierung sichergestellt. Die IDS Schnittstelle und Kommunikation ist in sich abgeschlossen und bedarf keiner weiteren Quelle zum reibungslosen Ablauf. Da die Schnittstelle durch die manuelle Bedienung des Webshops eine „menschliche“ Komponente hat, haben beide Seiten dafür zu sorgen, dass mögliche Fehlerquellen abgefangen, bzw. entsprechend gemeldet werden.

Erläuterungen zur Implementierung

Handwerkersoftware:

Bei der Zusammenstellung des Warenkorbes sollte die Möglichkeit bestehen, nur die Artikel zu nehmen, die bei diesem Lieferanten geführt werden.

Bei den aus dem Shop erhaltenen Artikeln sollte die Möglichkeit eines Abgleichs bestehen. Der Abgleich wird sicherlich auf Basis der in den Shop reingereichten Referenznummern geschehen. Wie mit den geänderten Artikeln umgegangen wird, muss jeder Software-Hersteller für sich selbst festlegen.

Die Anwendung der Schnittstelle sollte möglichst einfach sein, um die Akzeptanz der Shopsysteme zu erhöhen.

Shopsystem

Artikel eines reingereichten Warenkorbes, die nicht im Sortiment enthalten sind, dürfen nicht entfallen, sondern müssen zwingend in der Darstellung des Warenkorbes angezeigt werden. Dies ist unter dem Hintergrund zu sehen, dass der Anwender sonst nicht merkt, dass einige Artikel nicht bestellt werden können.

Wünschenswert ist eine Tauschfunktion, bei der der Anwender jeden beliebigen oder nicht im Shop vorhandenen Artikel markiert und unter Beibehaltung der von der Handwerkersoftware vergebenen Referenznummer (wahrscheinlich die Positionsnummer) einen anderen Artikel wählen kann.

Eine wichtige Funktion ist natürlich, mit dem reingereichten Warenkorb eine Bestellung auszulösen. Für einige Handwerkerprogramme ist es wichtig, dass diese Bestellung zusätzlich in das Handwerkersystem zurück kommt. Wenn in der Handwerkersoftware eine Bestellüberwachung und eine darauf basierende Rechnungsprüfung angewendet wird, ist die Rückgabe zwingend erforderlich. Im Shop vorgenommene Änderungen ständen sonst nicht zur Verfügung.

Auch wenn die Shop-Anbindung aus Großhandelssicht primär für Bestellungen vorgesehen ist, so muss es im Shop auch eine einfache und schnelle Möglichkeit geben, keine Bestellungen, sondern nur eine Artikelsuche mit Rückgabe zum Handwerker auszulösen. Damit kann der Handwerker schnell und einfach Angebote zusammenstellen. Ansonsten kommt es leicht zu Fehlbestellungen, so dass die Anwender Angst bekommen und die Schnittstelle nicht mehr nutzen.

Da alle Änderungen im Warenkorb prinzipiell an das Handwerkerpaket zurückkommen, sollte der Shop eine einfach zu erkennende Möglichkeit haben, alle Änderungen im Shop zu verwerfen, keine Aktion im Shop auszulösen und nichts an die Handwerkersoftware zurück zu liefern.

Rahmenbedingungen

Die in diesem Dokument beschriebene Schnittstelle ist in Anlehnung an die Schnittstelle GAEB XML Version 3.1 erstellt worden. Dateninhalte, die nicht innerhalb der GAEB Struktur enthalten sind, wurden für diese Schnittstelle ergänzt.

Technisches Vorgehen

Warenkorbübernahme Shop zur Handwerkssoftware

Über diese Funktion soll die Übernahme eines Warenkorbs aus dem Shop-System in die Handwerkssoftware realisiert werden.

Für den Prozess wurden folgende Prozessschritte abgestimmt.

a) Starten des GH-Shops aus der Handwerkssoftware in einem Browserfenster
Beim Aufruf des GH-Shops soll eine automatische Anmeldung erfolgen. Hierfür werden bei der Anfrage die Parameter „Kundennummer“, „Benutzername“ und „Passwort“ übertragen.

Zusätzlich ist der Parameter „Version“ zur Angabe der Version der Schnittstelle (ab Version 1.3) möglich.

Die Zugangsdaten sollen den beim Anwender bereits bekannten Zugangsdaten im Shop-System entsprechen.

Bei der Übertragung der Parameter soll die POST Variante (komplexere Implementierung aber unbegrenzte Parameterlänge) möglich sein. Die GET Variante wird auf Grund der nicht ausreichenden Länge der Parameter nicht unterstützt.

Beim Aufruf der Shop-Anbindung muss im HTTP-Header der Content "text/html" angegeben werden. Weiterhin muss der Zeichensatz angegeben werden, um eine eindeutige Interpretation zu ermöglichen. Für die Formulardaten muss der enctype "multipart/form-data" angegeben werden. Die gleichen Festlegungen gelten auch beim Aufruf der Hook-URL.

Der Zeichensatz der xml Struktur für den Warenkorb soll in der xml Deklaration angegeben werden. Wird nichts angegeben, so wird utf-8 genutzt. Es kann in jeder Anfrage nur ein Warenkorb übermittelt werden.

Für die Übertragung wird die Nutzung von HTTPS empfohlen, grundsätzlich soll aber auch HTTP möglich sein.

Die Rück-Kommunikation zur Handwerkssoftware soll über eine HOOK-URL erfolgen. Diese wird als Parameter beim Aufruf des GH-Shops übertragen.

Zusätzlich kann der Parameter „Target“ angegeben werden. Hier wird das Target angegeben, welches durch die Handwerkssoftware überwacht wird, um den Abschluss der Rück-Kommunikation festzustellen. Das Target muss, nach Abschluss der Rück-Kommunikation, durch den Shop aktualisiert werden. Wird der Parameter nicht übertragen, wird „TOP“ als Standard-Target genutzt.

Die Festlegung, welche Aktion im GH-Shop aufgerufen werden soll, erfolgt über einen Aktionsparameter. Sollten für andere Aktionen weitere Parameter erforderlich sein, so werden diese in Abhängigkeit von der Aktion definiert.

Falls beim Aufruf Fehler auftreten, sollen diese im Browserfenster angezeigt werden. Das genaue Fehlerhandling obliegt den einzelnen GH-Shops und wird hier nicht weiter betrachtet.

Falls der GH-Shop ein Weiterarbeiten z. B. über eine manuelle Anmeldung ermöglicht, müssen die Aufrufparameter aus der Handwerkssoftware erhalten bleiben um den Abschluss des Prozesses zu ermöglichen.

Hinweis: Beim Zugriff auf die Shop-Systeme ist zu beachten, dass es zu Problemen kommen kann, wenn in einem Shop-System mehrere Funktionen parallel gestartet werden.

b) Aktionen in GH-Shop
Dieser Schritt wird für den Prozess als Blackbox betrachtet, da die möglichen Aktionen innerhalb der einzelnen GH-Shops individuell sind.

c) Übernahme des Warenkorbs
Die Übertragung des Warenkorbs erfolgt in den im Kapitel „Dateninhalte“ beschriebenen Datenstrukturen. Der übertragene Warenkorb muss dem Schema „Warenkorb_empfangen.xsd“ entsprechen.

Die Übernahme der Daten erfolgt als Übertragung eines Formulars an die HOOK-URL analog der OCI Schnittstelle.

d) Schließen des GH-Shops
Nach Abschluss der Verarbeitung muss das Browserfenster geschlossen werden und der Prozess ist abgeschlossen.

Warenkorbübergabe Handwerkssoftware zum Shop

Über diese Funktion soll die Übergabe eines Warenkorbs aus der Handwerkssoftware in das Shop-System realisiert werden.

Für den Prozess wurden folgende Prozessschritte abgestimmt.

a) Starten des GH-Shops aus der Handwerkssoftware in einem Browserfenster

Analog zu Punkt a) Warenkorbübernahme GH-Shop zur Handwerkssoftware.

Es wird ein anderer Aktionsparameter gesendet. Darüber hinaus werden die Daten des Warenkorbs als zusätzlicher Parameter übertragen.

Hinweis: Der Parameter Hook-Url muss in jedem Fall mitgesendet werden, da nur dann eine Rückübertragung möglich ist.

Die Übertragung des Warenkorbs erfolgt in den im Kapitel „Dateninhalte“ beschriebenen Datenstrukturen. Der übertragenen Warenkorb muss dem Schema „Warenkorb_senden.xsd“ entsprechen.

Bei der Verarbeitung des Warenkorbs im GH-Shop müssen folgende Punkte gegeben sein:

- Es dürfen kein Positionen „verschluckt“ werden (bei der Verarbeitung entfallen) bzw. es muss eine entsprechende Fehlermeldung angezeigt werden.

- Übertragene Positionsnummern müssen erhalten bleiben.

- Ein Bezug zu Belegen, z. B. Angeboten soll bei der Übertragung möglich sein und bei der Verarbeitung erhalten bleiben.

Hinweis: Beim Zugriff auf die Shop-Systeme ist zu beachten, dass es zu Problemen kommen kann wenn in einem Shop-System mehrere Funktionen parallel gestartet werden.

b) Bearbeitung des Warenkorbs

Dieser Schritt wird für den Prozess weitgehend als Blackbox betrachtet, da die möglichen Aktionen innerhalb der einzelnen GH-Shops individuell sind. Folgende Festlegung wurde allerdings getroffen:

- Beim Bearbeiten des Warenkorbs müssen die übertragenen Positionsnummern erhalten bleiben.

c) Rückübertragung des geänderten Warenkorbs

Analog zum Prozess Warenkorbübernahme GH-Shop zur Handwerkssoftware (Schritt c) soll auch hier die Rückübertragung der Daten möglich sein.

Artikeldeeplink

Über diese Funktion soll die Anfrage an das Shop-System mittels der GH-Nummer erfolgen. Als Antwort erscheint eine Seite im Browser, die Artikeldaten bereitgestellt.

Der Prozess wurde wie folgt festgelegt:

a) Starten des GH-Shops aus der Handwerkssoftware in einem Browserfenster

Analog zu Punkt a) Warenkorbübernahme GH-Shop zur Handwerkssoftware.

Es wird ein anderer Aktionsparameter gesendet. Zusätzlich wird die Artikelnummer als Parameter übertragen.

Hinweis: Beim Zugriff auf die Shop-Systeme ist zu beachten, dass es zu Problemen kommen kann, wenn in einem Shop-System mehrere Funktionen parallel gestartet werden.

Logininformationen

Über diese Funktion wird am Shop System angefragt, welche Logininformationen erforderlich sind.

Bei der Anfrage wird nur der Parameter Aktionscode = „LI“ für Logininformationen übertragen. Als Antwort wird folgende XML Struktur erwartet:

<Logininformationen>

<Kundennummer_erforderlich>false</Kundennummer_erforderlich>

<Benutzername_erforderlich>true</Benutzername_erforderlich>

<Passwort_erforderlich>true</Passwort_erforderlich>

</Logininformationen>

Erlaubte Werte sind true / false.

Schnittstellenversion

Über diese Funktion wird am Shop angefragt, welche Versionen der Schnittstelle unterstützt werden.

Bei der Anfrage wird nur der Parameter Aktionscode = „SV“ für Schnittstellenversion übertragen. Als Antwort wird folgende XML Struktur erwartet:

<Schnittstellenversionen>

<Version>1.3</Version>

<Version>2.0</Version>

</Schnittstellenversionen>

Erlaubte Werte sind „1.3“ und „2.0“.

Parameterdefinition

Innerhalb des Aufrufs der Funktionen können folgende Parameter übertragen werden:

Datentypen

Folgende skalare Datentypen werden verwendet:

Dateninhalte

Schema und Beispiel Datenstruktur Warenkorb senden

Schema und Beispiel Datenstruktur Warenkorb empfangen

Anhang

Codelisten

Aktioncodes

Mengeneinheiten

Fehlercodes

Zusätzlich zu dem angegebenen Code könne weitere Fehlercodes frei genutzt werden.

Rohstoffe

Beispiel Rohstoffangaben

50 Meter Ring Kabel.

Preis 10.000,00 € pro 1.000 Meter.

Kupfergewicht beträgt 96 Kilogramm pro 100 Meter.

Der Preis ist mit einem Kupferpreis von 150 € pro 100 Kilogramm kalkuliert.

Der aktuelle Kupferpreis beträgt 300 € pro 100 Kilogramm.

Der Rabatt entspricht 10%

Übertragene Daten

Berechnung

Kupferzuschlag (KZ) = AM * (GAW / BW) * (AN - BN)

= 50 m * (96 kg / 100 m) * ((300 € / 100 kg) – (150 € / 100 kg))

= 72 €

Nettopreis (NP) = (AM * (AP / PB) – R + KZ )

= (50 m * ((10.000 € / 1000 m ) -1.000 € / 1000 m))+ 72 €

= 50 m * (9.000 € / 1.000 m) +72 €

= 522 €