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

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"
}
],
...
}

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

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:

Fest vorgegebene Positionsdaten

Im Shop frei konfigurierbare Positionsdaten

Im Shop werden maximal 1000 verschiedene Positionsdaten P1...P1000 unterstützt.

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

Die Positionsdaten sind im Shop (optional je Typ) frei konfigurierbar.

Beispiel einer Konfigurationsdatei im Shop unabhängig des Daten-Typs:

Antwort /GetOrderList:

[
{
"FileAvailable": true,
"HeadData": [
{
"Name": "H1",
"Value": "015552222"
},
{
"Name": "H2",
"Value": "10,99"
},
{
"Name": "H3",
"Value": "19,99"
},
...
],
"ID": "90909009909009",
"Type": 1
},
...
]

Übertragung einer einzelnen Bestellung /GetOrder

Anfrage vom Shop für eine einzelne Bestellung

Anfrage /GetOrder:

{
"ShopID": "myshop",
"Password": "1234567890",
"BillCountry": "DEU",
"CustomerID": "1001",
"CustomerSubshopIDs": [
"Deutsch"
],
"ID": "90909009909009",
"SubshopID": "Deutsch",
"Type": 1
}

Antwort vom ERP-System /GetOrder:

(Siehe auch Kopfdaten und Positionsdaten)

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
"CancellationFileAvailable": false,
"BankTransferRefund": true,
"HeadData": [
{
"Name": H1,
"Value": Kundennummer
},
{
"Name": H2,
"Value": Auftragsdatum
},
...
],
"Positions": [
{
"MaxCancellations": 0,
"MaxReturns": 1,
"OrderQuantity": 1,
"PartCancellations": true,
"PartReturns": false,
"PositionData": [
{
"Name": "P1",
"Value": "Artikelnummer"
},
{
"Name": "P2",
"Value": "Bezeichnung"
},
...
],
"PositionID": "p0"
},
{
"MaxCancellations": 1,
"MaxReturns": 2,
"OrderQuantity": 2,
"PartCancellations": true,
"PartReturns": false,
"PositionData": [
{
"Name": "P1",
"Value": "Artikelnummer"
}
],
"PositionID": "p1"
},
...
]
}

Übertragung der möglichen Begründungen bei Storno/Retoure

Optional kann das ERP-System in den Kopfdaten des Auftrags die möglichen Begründungen mitliefern, die der Kunde im Shop bei einem Storno oder einer Retoure auswählen kann.

Dies überschreibt alle in der Konfiguration des Shops hinterlegten Begründungen.

• Zum Überschreiben der Storno-Begründungen muss das CancellationReasons-Array übertragen werden.

• Zum Überschreiben der Retoure-Begründungen muss das ReturnReasons-Array übertragen werden.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
"CancellationFileAvailable": false,
"BankTransferRefund": true,
"CancellationReasons": [
{
"Code": 0,
"Text": "Ohne Begründung"
},
{
"Code": 1,
"Text": "Falsch bestellt"
},
...
],
"ReturnReasons": [
{
"Code": 0,
"Text": "Ohne Begründung"
},
{
"Code": 1,
"Text": "Falsch bestellt"
},
...
],
...
}

Übertragung einer PDF-Datei

Wird z. B. eine Rechnung per PDF angefordert, so liefert das ERP-System alle Daten einer Bestellung:

• komplette Rechnungsadresse

• komplette Lieferadresse

• alle Artikel der Bestellung

• Gesamtsumme

• Zahlungsart

• Versandart/Zusteller

• usw.

Der Shop übergibt dem ERP-System die eindeutige ID der Bestellung und den Typ, den das ERP-System in der Bestellung gesendet hat.

Retouren

Wird eine Retoure angemeldet, dann kann das ERP-System dem Shop eine PDF-Datei (Retourenaufkleber etc.) zur Verfügung stellen und gibt dies dem Shop in den Kopfdaten bekannt.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": true,
"CancellationFileAvailable": false,
"BankTransferRefund": false,
...
}

Die PDF-Datei einer Retoure wird mit dem Typ „1001“ angefordert.

Stornos

Wird ein Storno durchgeführt, dann kann das ERP-System dem Shop eine PDF-Datei (Stornobestätigung etc.) zur Verfügung stellen und gibt dies dem Shop in den Kopfdaten bekannt.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
"CancellationFileAvailable": true,
"BankTransferRefund": false,
...
}

Die PDF-Datei eines Stornos wird mit dem Typ „1002“ angefordert.

Anfrage vom Shop für eine einzelne Bestellung als PDF-Datei /GetFile