Allgemeines

Im Folgenden wird eine REST-basierte Schnittstelle beschrieben, mit deren Hilfe ein WEBSALE Shop kundenspezifische Bestellungen von einem ERP-System in Echtzeit übermittelt bekommt und diese dem Kunden/Besteller im Shop anzeigt. Insbesondere dient diese Schnittstelle dazu, dem Kunden alle Bestellungen anzuzeigen, also auch die Bestellungen, die nicht im Shop getätigt wurden, sondern z. B. per Callcenter, Brief oder Fax aufgegeben wurden. Des Weiteren können dem ERP-System Stornos und Retouren übermittelt werden.

Falls das ERP-System nicht direkt über das Internet erreichbar ist, dann kann die WEBSALE AG einen VPN-Tunnel zur Verfügung stellen. Über diesen VPN-Tunnel kann das ERP-System eine sichere TCP/IP-Verbindung ins Internet herstellen.

REST-Funktionen

Alle hier aufgelistete Funktionen werden mittels POST aufgerufen. Bei Erfolg liefert das ERP-System den Http-Code 200 zurück.

Übertragung einer Liste von Bestellungen (Kopf- und optionale Positionsdaten)

Der Shop fordert eine Liste von Bestellungen vom ERP-System an.
Das ERP-System liefert eine Liste von Bestellungen zurück.

In der Liste wird nur ein Teil der Bestelldaten übermittelt. In der Regel sind dies die Kopfdaten.

Übertragung einer einzelnen Bestellung (Kopf- und Positionsdaten)

Der Shop fordert eine einzelne Bestellung vom ERP-System an.
Das ERP-System liefert die Kopf- und alle Positionsdaten der Bestellung zurück.

Übertragung einer PDF-Datei

Der Shop fordert die PDF-Datei vom ERP-System an.
Das ERP-System liefert die PDF-Datei zurück.
Der Shop bietet die PDF-Datei dem Kunden als Download an.

Storno/Retoure von einer oder mehreren Positionen

Der Besteller storniert/retourniert eine oder mehrere Positionen.
Der Shop sendet die Stornierung/Retoure an das ERP-System.
Das ERP-System bestätigt die Stornierung/Retoure oder lehnt diese ab.

Übertragung der letzten Shop-Bestellnummer

Der Shop fordert die letzte Shop-Bestellnummer vom ERP-System an.
Das ERP-System liefert die letzte Shop-Bestellnummer zurück.

Übertragung des Lagerbestands/Filialbestandes eines einzelnen Produkts

Der Shop fordert den Lagerbestand zu einem einzelnen Produkt an.
Das ERP-System liefert den Lagerbestand des Produktes zurück.

Übertragung von allgemeinen Kundendaten

Der Shop fordert allgemeine Kundendaten vom ERP-System an.
Das ERP-System liefert die allgemeinen Kundendaten zurück.

Ausschließlich verschlüsselter Abruf

Der Webservice wird ausschließlich über SSL aufgerufen. Unverschlüsselte Verbindungen müssen auf beiden Seiten (Shop/ERP-System) abgelehnt werden.

UTF-8-Codierung

Alle Daten werden im UTF-8 Format übergeben.

Fehler

Das ERP-System antwortet mit einem Http-Code ungleich 200, wenn es keine Daten liefern kann. Dies ist z. B. in den folgenden Fällen gegeben:

falsches REST-Passwort
unbekannte Kundennummer
unbekannte ShopID/SubshopID
unbekannter Typ
interner Fehler
etc.

Der Shop erwartet einen Fehler-Code, der vom ERP-System vorgegeben wird, und eine optionale Fehlermeldung. Aufgrund des Fehler-Codes kann der Designer dem Besteller sprachabhängige Erläuterungen/Hinweismeldungen anzeigen. Die optionale Fehlermeldung dient nicht dazu, diese dem Besteller anzuzeigen, sondern wird zur Protokollierung in der Log-Datei verwendet. Sie kann daher rein technisch sein.

Der Fehlercode muss eindeutig und in jeder Antwort einheitlich sein. Beispiel:

0001: falsches REST-Passwort
0002: unbekannte Kundennummer
0003: unbekannte ShopID
0004: unbekannte SubshopID
0005: unbekannter Typ
1000: interner Fehler X
1001: interner Fehler Y
1002: interner Fehler Z
etc.

Liefert das ERP-System z. B. den Fehlercode „0002“, so könnte dem Besteller folgende Meldung angezeigt werden:

„Sehr geehrter Herr Müller,

leider liegen uns derzeit keine Informationen über Ihre Kundennummer vor. Bitte kontaktieren Sie uns unter der Telefonnummer XYZ oder benutzen Sie unser Kontaktformular (→ Link zum Kontaktformular)“

Außerdem können entsprechende (codeabhängige) Grafiken eingeblendet werden.

Response:

Http-Code = 400

{

"ErrCode": 2,

"ErrMsg": "Unbekannte Kundennummer"

}

Übertragung einer Liste von Bestellungen /GetOrderList

Bei der Übertragung liefert das ERP-System dem Shop

fest vorgegebene Daten
beliebige Daten

zurück.

Anfrage vom Shop für eine Liste von Bestellungen

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung
ShopID	128	ja	String	Eine eindeutige Shop-ID. Die Shop-ID wird von der WEBSALE AG vergeben.
Password	128	ja	String	Das REST-Passwort. Wird von der WEBSALE AG vergeben und muss vom ERP-System geprüft werden. Das ERP-System muss die Anfrage bei einem falschen Passwort ablehnen.
SubshopID	128	ja	String	Eine eindeutige Subshop-ID, in der die Daten angezeigt werden.
CustomerSubshopIDs	128 je ID	ja	String-Array	Liste der gültigen Subshops des Kunden
CustomerID	64	ja	String	Eine eindeutige Kundennummer
BillCountry	3	nein	String	Rechnungsland ISO 3166 (z. B. DEU) des Bestellers, falls im Shop bekannt.
Type		ja	Integer	Ein Typ, der die angeforderten Daten spezifiziert. Bei „0“ liefert das ERP-System alle Typen, die im ERP-System vorhanden sind zurück. Die einzelnen Typen sind im Shop frei konfigurierbar und werden vom ERP-System vorgegeben. Beispiel: 1: Rechnung 2: Retoure 3: Storno usw. Bitte beachten: Die Typen 1000 bis 1100 sind für interne Zwecke reserviert.
MaxEntries		nein	Integer	Die max. Anzahl der Listeneinträge, die gesendet werden sollen. Fehlt der Parameter oder ist er „0“, dann benutzt das ERP-System einen eigenen Standardwert für die maximalen Listeneinträge.
DateFrom	10	nein	String Format: JJJJ-MM-TT	Ein optionales Anfangsdatum, ab dem die Listeneinträge gesendet werden. Ob „DateFrom“ im Shop genutzt wird, lässt sich im Shop konfigurieren.
DateUntil	10	nein	String Format: JJJJ-MM-TT	Ein optionales Enddatum, bis zu dem die Listeneinträge gesendet werden. Ob „DateUntil“ im Shop genutzt wird, lässt sich im Shop konfigurieren.
SearchFilters		nein	Filter-Array	Optionale freie Suchfilter. Maximal 10 Einträge.

Vom ERP-System vorgegebene freie Suchfilter

Optional können dem ERP-System bis zu 10 freie Suchfilter übergeben werden. Die möglichen Filter und die dazugehörigen Codes werden vom ERP-System vorgegeben.

{
"SearchFilters" : [
{
"Code": 1,
"Value": "FilterText"
},
{
"Code": 2,
"Value": "FilterText"
}
],
...
}

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung
Code	16	ja	String	Der Code des Suchfilters. Das ERP-System gibt vor, welche Codes es unterstützt. Ein Code darf nur die Zeichen a-z, A-Z und 0-9 beinhalten.
Value	128	ja	String	Der Wert, nach dem gefiltert wird. Die maximale eingebbare Länge kann vom Designer eingestellt/verringert werden.

Anfrage /GetOrderList

{
"ShopID": "myshop",
"Password": "1234567890",
"SubshopID": "Deutsch",
"BillCountry": "DEU",
"CustomerID": "1001",
"CustomerSubshopIDs": [
"Deutsch"
],
"MaxEntries": 10,
"SearchFilters": [
{
"Code": "code01",
"Value": "1"
}
],
"Type": 1,
"DateFrom": "2020-03-02",
"DateUntil": "2020-03-08",
}

Antwort vom ERP-System

Das ERP-System liefert dem Shop fest vorgegebene und im Shop frei konfigurierbare Daten zurück.

Fest vorgegebene Kopfdaten

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung
ID	128	ja	String	Eindeutige ID der Bestellung, z. B. die Bestellnummer
Type		ja	Integer	Ein Typ, der die gesendeten Daten spezifiziert. Der Typ wird vom ERP-System vergeben/verwaltet und ist im Shop frei konfigurierbar. Beispiel: 1: Rechnung 2: Umtausch 3: Retoure usw.
FileAvailable		ja	Boolean	Dieser Parameter gibt an, ob zur Bestellung eine PDF-Datei (z. B. die Rechnung/Stornierung etc.) zur Verfügung steht. Mögliche Werte „true“ oder „false“
ReturnsFileAvailable		nein	Boolean	Nur, wenn Retoure angemeldet wird. Dieser Parameter gibt an, ob bei einer angemeldeten Retoure eine PDF-Datei (z. B. Retourenaufkleber etc.) zur Verfügung steht. Mögliche Werte „true“ oder „false“
CancellationFileAvailable		nein	Boolean	Nur, wenn ein Storno durchgeführt wird. Dieser Parameter gibt an, ob bei einem durchgeführten Storno eine PDF-Datei zur Verfügung steht. Mögliche Werte „true“ oder „false“
BankTransferRefund		nein	Boolean	Nur bei einer möglichen Retoure/Storno. Dieser Parameter gibt an, ob bei einer möglichen Retoure/Storno die Erstattung per Banküberweisung erfolgt und die Bankverbindung vom Besteller abgefragt werden soll. Mögliche Werte „true“ oder „false“ Bei true kann das ERP-System dem Shop die hinterlegten Bankdaten des Kunden zusenden. Dann werden die Bank-Felder mit diesen Daten vorbelegt.
RefundBankName	128	nein	String	Name des Kreditinstitutes für die Erstattung
RefundBankOwner	128	nein	String	Kontoinhaber für die Erstattung
RefundBankIBAN	128	nein	String	IBAN für die Erstattung
RefundBankBIC	128	nein	String	BIC für die Erstattung

Im Shop frei konfigurierbare Kopfdaten

Im Shop werden maximal 1000 verschiedene Kopfdaten H1...H1000 unterstützt.

Die maximale Länge eines einzelnen Datensatzes beträgt 4096 Zeichen.

Die Kopfdaten sind im Shop (optional je Typ) frei konfigurierbar.
Beispiel einer Konfigurationsdatei im Shop unabhängig des Daten-Typs:

<HeadData>
H1 = Kundennummer
H2 = Auftragsdatum
H3 = Auftragsnummer
H4 = Rechnungsnummer
...
</HeadData>

Parameter	Max. Länge	Erfor-derlich	Datentyp	Bemerkung

Parameter

Max. Länge

Erfor-derlich

Datentyp

Bemerkung

Name

5

ja

String

Der Name des Kopfdatenfeldes

H1...H1000

Value

4096 je Value

ja