WS-REST-OrderManagement

Mit WS-REST-OrderManagement fordert der Shop Daten in Echtzeit von Ihrem ERP-System an und zeigt sie dem Kunden direkt im Shop. Der wichtigste Anwendungsfall: dem Kunden alle seine Bestellungen zeigen, also auch die, die nicht im Shop entstanden sind, sondern beispielsweise über das Callcenter, per Brief oder per Fax. In der Gegenrichtung meldet der Shop Stornos und Retouren an das ERP-System zurück.

Eigenschaft	Wert
Info	REST-basierte Schnittstelle für den bidirektionalen Datenaustausch
Übertragungsrichtung	ERP/Warenwirtschaft ↔ WEBSALE Shop (bidirektional)
Übertragungsart	REST
Dateiformate	JSON

Übertragbar sind eine einzelne Bestellung oder eine Liste von Bestellungen, die letzte Shop-Bestellnummer, PDF-Dateien, der Lagerbestand eines Produkts oder einer Filiale in Echtzeit sowie allgemeine Zusatzinformationen über einen Kunden.

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 beispielsweise 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 beispielsweise 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 beispielsweise 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	Erforderlich	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 (beispielsweise 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	Erforderlich	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	Erforderlich	Datentyp	Bemerkung
`ID`	128	ja	String	Eindeutige ID der Bestellung, beispielsweise 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 (beispielsweise 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 (beispielsweise 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	Erforderlich	Datentyp	Bemerkung
`Name`	5	ja	String	Der Name des Kopfdatenfeldes H1…H1000
`Value`	4096 je Value	ja	String	Ein oder mehrere Werte die dem Kopfdatenfeld zugeordnet sind. Bitte beachten: Dieser Parameter darf maximal 10-mal auftreten!

Fest vorgegebene Positionsdaten

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`PositionID`	128	Ja	String	Eindeutige ID der Position, beispielsweise die Artikelnummer oder laufende Positionsnummer
`OrderQuantity`		Ja	Integer	Bestellmenge
`MaxReturns`		Ja	Integer	Maximale Stückzahl der möglichen Retouren. 0 = Keine Retoure möglich
`PartReturns`		Ja	Boolean	true=Teil-Retouren möglich false= keine Teil-Retouren möglich nur „MaxReturns“ möglich Beispiel: MaxReturns=5 PartReturns=true → Kunde kann 1..5 Stück retournieren Beispiel: MaxReturns=5 PartReturns=false → Kunde muss alle 5 Stück retournieren
`MaxCancellations`		Ja	Integer	Maximale Stückzahl der möglichen Stornos. 0 = Kein Storno möglich
`PartCancellations`		Ja	Boolean	true=Teil-Stornos möglich false= keine Teil-Stornos möglich nur „MaxCancellations“ möglich. Beispiel: MaxCancellations=5 PartCancellations=true → Kunde kann 1..5 Stück stornieren Beispiel: MaxCancellations=5 PartCancellations=false → Kunde muss 5 Stück stornieren

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: <PositionData> P1 = Artikelnummer P2 = Bezeichnung P3 = Farbe P4 = Gewicht P5 = Stückpreis ... </PositionData>

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`Name`	5	ja	String	Der Name des Positionsdatenfeldes P1…P1000
`Value`	4096 je Value	ja	String	Ein oder mehrere Werte die dem Positionsdatenfeld zugeordnet sind. Bitte beachten: Dieser Parameter darf maximal 10-mal auftreten!

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

Parameter	Max. Länge	Erforderlich	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 Bestellungen 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 (beispielsweise DEU) des Bestellers, falls im Shop bekannt.
`Type`		ja	Integer	Dieser Wert wurde vom ERP-System in der Liste geliefert und wird hier zurückgegeben.
`ID`	128	ja	String	Dieser Wert wurde vom ERP-System in der Liste geliefert und wird hier zurückgegeben.

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

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`Code`		ja	Integer	Der Code der Begründung
`Text`	1024	ja	String	Der lesbare Text der Begründung, der im Shop zur Auswahl steht.

Übertragung einer PDF-Datei

Wird beispielsweise 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

Parameter	Max. Länge	Erforderlich	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 Bestellungen 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 (beispielsweise DEU) des Bestellers, falls im Shop bekannt.
`Type`		ja	Integer	Dieser Wert wurde vom ERP-System in der Liste geliefert und wird hier zurückgegeben. Bitte beachten Sie: Liegt ein Retouren-PDF vor und meldet der Kunde eine Retoure an, dann sendet der Shop den Typ „1001“ und fordert damit das Retouren-Dokument an. Analog wird bei einem durchgeführten Storno der Typ „1002“ übergeben.
`ID`	128	ja	String	Dieser Wert wurde vom ERP-System geliefert und wird hier zurückgegeben.

Anfrage /GetFile:

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

Antwort vom ERP-System als PDF-Datei /GetFile

Das ERP-System liefert folgende Daten zurück:

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`FileName`	128	ja	String	Name der PDF-Datei, beispielsweise 12345.pdf
`FileData`	2 MByte	ja	String	Base64-kodierte PDF-Daten

Antwort vom ERP-System /GetFile:

{
  "FileName": "1234567890.pdf",
  "FileData": "Base64-kodierte PDF-Daten"
}

Der Dateiname sollte vom ERP-System möglichst eindeutig generiert werden, beispielsweise aus der Rechnungsnummer und der Endung „pdf“. Er sollte keine Sonderzeichen oder Leerzeichen beinhalten. Das Dateiformat muss nicht notwendigerweise PDF sein. Prinzipiell kann jedes Format gesendet werden, welches eine möglichst hohe Verbreitung unter den Internet-Usern hat. Derzeit ist PDF die beste Wahl.

Storno/Retoure von Positionen einer Bestellung

Wie oben beschrieben gibt das ERP-System je Position bekannt, ob und wie viele Stücke storniert/retourniert werden können.

{
 ...
 "Positions": [
 {
 "MaxCancellations": 0,
 "MaxReturns": 2,
 "OrderQuantity": 2,
 "PartCancellations": false,
 "PartReturns": true,
 "PositionData": [
 {
 "Name": "P3",
 "Value": "asdf0000"
 }
 ],
 "PositionID": "1"
 },
 ...

Somit könnte ein Besteller beispielsweise die erste Position stornieren und die 2. Position retournieren, falls die 2. Position bei einer Teillieferung bereits ausgeliefert wurde. Eine Position kann entweder storniert oder retourniert werden. Beides gleichzeitig ist nicht möglich. Storno je Position Übergibt das ERP-System den Wert „0“, dann wird kein Storno angeboten. Ansonsten wird eine

Storno-Checkbox
Mengeneingabefeld, falls MaxCancellations > 1
DropDown-Liste für eine Begründung

angeboten. Retoure je Position Übergibt das ERP-System den Wert „0“, dann wird keine Retoure angeboten. Ansonsten wird eine

Retouren-Checkbox
Mengeneingabefeld, falls MaxReturns > 1
DropDown-Liste für eine Begründung

angeboten. Der Shop bietet optional zu jeder Position eine frei konfigurierbare DropDown-Liste an, mittels derer der Kunde eine Begründung angeben kann. Dem ERP-System wird hierzu ein Code übermittelt. Beispiel für Retouren: 0=keine Begründung angegeben 1=Qualität gefällt nicht 2=Falscher Artikel geliefert 3=zu spät geliefert etc. Der Code und die Texte werden vom ERP-System vorgegeben und im Shop hinterlegt. Abfragen der Bankverbindung Meldet das ERP-System dem Shop, dass die Bankverbindung für die Erstattung abgefragt werden soll (BankTransferRefund=true), so werden 4 weitere Eingabefelder als Pflichtfelder

Name der Bank
Kontoinhaber
IBAN
BIC

angezeigt.

Senden einer Retoure oder eines Stornos an das ERP-System /CancelOrder

Parameter	Max. Länge	Erforderlich	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 Bestellungen 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 (beispielsweise DEU) des Bestellers, falls im Shop bekannt.
`ID`	128	ja	String	Dieser Wert wurde vom ERP-System für die Bestellung übergeben und wird hier zurückgegeben.
`PositionID`	128	ja	String	Dieser Wert wurde vom ERP-System für die Position übergeben und wird hier zurückgegeben.
`CancelType`		ja	Integer	1=Storno 2=Retoure
`Quantity`		Ja	Integer	Menge/Stückzahl pro Position, die retourniert/storniert werden soll.
`ReasonCode`		Nein	Integer	Code der Begründung.
`RefundBankName`	128	nein	String	Name des Kreditinstitutes, falls die Erstattung per Banküberweisung erfolgt
`RefundBankOwner`	128	nein	String	Kontoinhaber, falls die Erstattung per Banküberweisung erfolgt
`RefundBankIBAN`	128	nein	String	IBAN, falls die Erstattung per Banküberweisung erfolgt
`RefundBankBIC`	128	nein	String	BIC, falls die Erstattung per Banküberweisung erfolgt

Anfrage /CancelOrder:

{
 "ShopID": "myshop",
 "Password": "1234567890",
 "SubshopID": "Deutsch",
 "BillCountry": "DEU",
 "CustomerID": "1001",
 "CustomerSubshopIDs": [
 "Deutsch"
 ],
 "ID": "90909009909009",
 "RefundBankBIC": "BIC",
 "RefundBankIBAN": "IBAN",
 "RefundBankName": "Bankname",
 "RefundBankOwner": "Kontoinhaber",
 "Positions": [
 {
 "PositionID": "1",
 "CancelType": 1,
 "ReasonCode": 0,
 "Quantity": 1
 },
 ...
 ]
}

Bitte beachten Sie: Es werden nur die Positionen an das ERP-System gesendet, die storniert/retourniert werden sollen.

Antwort vom ERP-System /CancelOrder

Das ERP-System liefert alle Daten (Kopf- und alle Positionsdaten) der Bestellung zurück. Zusätzliche Kopfdaten In den Kopfdaten kann das ERP-System jetzt und in späteren Anfragen zu dieser Bestellung mitteilen, dass eine Retouren-PDF-Datei, bzw. Storno-PDF-Datei abgeholt werden kann.

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`ReturnsFileAvailable`		nein	Boolean	Nur, wenn Retoure angemeldet wurde. Dieser Parameter gibt an, ob bei einer angemeldeten Retoure eine PDF-Datei (beispielsweise Retourenaufkleber etc.) zur Verfügung steht. Mögliche Werte „true“ oder „false“
`CancellationFileAvailable`		nein	Boolean	Nur, wenn ein Storno durchgeführt wurde. Dieser Parameter gibt an, ob bei einem durchgeführten Storno eine PDF-Datei zur Verfügung steht. Mögliche Werte „true“ oder „false“

Zusätzliche Positionsdaten Das ERP-System meldet für jede Position, welche Aktion durchgeführt wurde und ob die Aktion erfolgreich bzw. nicht erfolgreich war. Diese Werte sollten nur einmal gesendet werden. Bei späteren Anfragen sollten diese dann entfallen.

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`CancelType`		nein	Integer	1=Storno 2=Retoure
`CancelErrCode`		nein	Integer	Ein Fehlercode 0: Alles OK >0: Fehler (wird vom ERP-System verwaltet)
`CancelErrMsg`	1024	nein	String	Eine optionale Fehlermeldung vom ERP-System

Bitte beachten Sie: Wurde eine Position erfolgreich retourniert, so muss das ERP-System die Werte für

"MaxReturns": 0,
"PartReturns": false,

in dieser Antwort (und allen späteren Antworten) entsprechend anpassen, damit der Besteller nicht erneut retournieren kann. Das gleiche gilt für eine erfolgreiche Stornierung. Außerdem sollte das ERP-System ab diesem Zeitpunkt das Datum und die Uhrzeit der Stornierung/Retoure übergeben, damit diese Informationen dem Besteller bei späteren Abfragen angezeigt werden können. Antwort /CancelOrder (Beispiel: Besteller hat 2. Position storniert und 3. Position retourniert):

{
 "Type": 0,
 "BankTransferRefund": true,
 "FileAvailable": true,
 "ID": "90909009909009",
 "HeadData": [
 {
 "Name": "H1",
 "Value": "Kundennummer"
 },
 ...
 ],
 "Positions": [
 {
 "MaxCancellations": 2,
 "MaxReturns": 0,
 "OrderQuantity": 2,
 "PartCancellations": true,
 "PartReturns": false,
 "PositionData": [
 {
 "Name": "P1",
 "Value": "Artikelnummer”
 },
 ...
 ],
 "PositionID": "1"
 },
 {
 "MaxCancellations": 0,
 "MaxReturns": 0,
 "OrderQuantity": 1,
 "PartCancellations": false,
 "PartReturns": false,
 "CancelType": 1,
 "CancelErrCode": 0,
 "CancelErrMsg": "Position erfolgreich storniert",
 "PositionData": [
 {
 "Name": "P1",
 "Value": "Artikelnummer"
 },
 ...
 ],
"PositionID": "2” },
 {
 "MaxCancellations": 0,
 "MaxReturns": 0,
 "OrderQuantity": 2,
 "PartCancellations": false,
 "PartReturns": false,
 "CancelType": 2,
 "CancelErrCode": 0,
 "CancelErrMsg": "Retoure erfolgreich angemeldet",
 "PositionData": [
 {
 "Name": "P3",
 "Value": "asdf0003"
 }
 ],
 "PositionID": "3"
 },
 ...
 ]
}

Übertragung der letzten Shop-Bestellnummer /GetLastOrderNumber

Damit der Shop die Bestellungen anzeigen kann, die noch nicht in das ERP-System importiert wurden, ist es erforderlich, dass das ERP-System dem Shop die letzte Shop-Bestellnummer mitteilt, welches das ERP-System importiert hat bzw. dem ERP-System bekannt ist. Die Anfrage des Shops enthält folgende Parameter:

Parameter	Max. Länge	Erforderlich	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 Bestellungen 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 (beispielsweise DEU) des Bestellers, falls im Shop bekannt.

Anfrage vom Shop /GetLastOrderNumber:

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

Antwort vom ERP-System für die letzte Shop-Bestellnummer /GetLastOrderNumber

Das ERP-System liefert folgende Daten zurück:

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`LastOrderNumber`	64	ja	String	Shop-Bestellnummer

Antwort vom ERP-System /GetLastOrderNumber:

{
  "LastOrderNumber": "1234567890"
}

Abfrage eines einzelnen Lagerbestandes (einer Filiale) /GetStockAmount

Diese Funktion eignet sich für die Abfrage in Echtzeit, ob ein Produkt in einer ausgewählten Filiale verfügbar ist. Die Anfrage des Shops enthält folgende Parameter:

Parameter	Max. Länge	Erforderlich	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
`ProductNumber`	64	ja	String	Artikelnummer
`BranchID`	64	nein	String	Optionale Filial-ID

Die Filial-ID ist optional. Wird keine Filial-ID übergeben, dann liefert das ERP-System den Lagerbestand des Artikels bzgl. des Subshops. Wird eine Filial-ID übergeben, dann liefert das ERP-System den Lagerbestand bzgl. der Filiale. Anfrage vom Shop /GetStockAmount:

{
  "ShopID": "myshop",
  "Password": "1234567890",
  "SubshopID": "Deutsch",
  "ProductNumber": "1234567",
  "BranchID": "123"
}

Antwort vom ERP-System für den einzelnen Lagerbestand /GetStockAmount

Das ERP-System liefert folgende Daten zurück:

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`StockAmount`		ja	Integer	Lagerbestand

Antwort vom ERP-System /GetStockAmount:

{
  "StockAmount": 100
}

Übertragung von allgemeinen, zusätzlichen Kundendaten /GetCommonData

Bei diesen Informationen geht es nicht um Bestelldaten, sondern um zusätzliche, frei konfigurierbare Kundendaten, wie beispielsweise die angesammelten Bonuspunkte oder die Rabatte eines Kunden bei einem Kauf. Die Anfrage des Shops enthält folgende Parameter:

Parameter	Max. Länge	Erforderlich	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
`CustomerSubshopIDs`	128 je ID	ja	String-Array	Liste der gültigen Subshops des Kunden
`CustomerID`	64	ja	String	Eine eindeutige Kundennummer
`Type`		nein	Integer	Die möglichen Werte legt das ERP-System fest. Ist der Typ 0, dann liefert das ERP-System alle allgemeinen Daten zurück. Bitte beachten: Die Typen 1000 bis 1100 sind für interne Zwecke reserviert.
`BillCountry`	3	nein	String	Rechnungsland ISO 3166 (beispielsweise DEU) des Bestellers, falls im Shop bekannt.

Anfrage vom Shop /GetCommonData:

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

Antwort vom ERP-System für allgemeine Daten /GetCommonData

Das ERP-System liefert im Shop frei konfigurierbare Daten zurück.

Im Shop frei konfigurierbare Daten:

Im Shop werden maximal 1000 verschiedene Commondaten C1…C1000 unterstützt. Die maximale Länge eines einzelnen Datensatzes beträgt 4096 Zeichen. Commondaten sind im Shop (optional je Typ) frei konfigurierbar. Beispiel einer Konfigurationsdatei im Shop unabhängig des Daten-Typs: <CommonData> C1 = Bonuspunkte C2 = Kundenspezifische Rabatte nach Kalenderjahr ... </CommonData>

Parameter	Max. Länge	Erforderlich	Datentyp	Bemerkung
`Name`	5	ja	String	Der Name des Commondatenfeldes C1…C1000
`Value`	4096 je Value	ja	String	Ein oder mehrere Werte, die dem Commondatenfeld zugeordnet sind. Bitte beachten: Dieser Parameter darf maximal 10-mal auftreten!

Antwort vom ERP-System /GetCommonData:

[
{
 "Name": "C1",
 "Value": "100"
 },
 {
 "Name": "C2",
 "Value": [
 "umsatzabhängiger Kundenrabatt 2010: 5%",
 "umsatzabhängiger Kundenrabatt 2011: 12%",
 "umsatzabhängiger Kundenrabatt 2012: 5%",
 "umsatzabhängiger Kundenrabatt 2013: 12%"
 ]
 },
 ...
]

Schnittstellen

Allgemeines

REST-Funktionen

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

Übertragung einer einzelnen Bestellung (Kopf- und Positionsdaten)

Übertragung einer PDF-Datei

Storno/Retoure von einer oder mehreren Positionen

Übertragung der letzten Shop-Bestellnummer

Übertragung des Lagerbestands/Filialbestandes eines einzelnen Produkts

Übertragung von allgemeinen Kundendaten

Ausschließlich verschlüsselter Abruf

UTF-8-Codierung

Fehler

Übertragung einer Liste von Bestellungen /GetOrderList

Anfrage vom Shop für eine Liste von Bestellungen

Vom ERP-System vorgegebene freie Suchfilter

Antwort vom ERP-System

Fest vorgegebene Kopfdaten

Im Shop frei konfigurierbare Kopfdaten

Fest vorgegebene Positionsdaten

Im Shop frei konfigurierbare Positionsdaten

Übertragung einer einzelnen Bestellung /GetOrder

Anfrage vom Shop für eine einzelne Bestellung

Antwort vom ERP-System /GetOrder:

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

Übertragung einer PDF-Datei

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

Antwort vom ERP-System als PDF-Datei /GetFile

Storno/Retoure von Positionen einer Bestellung

Senden einer Retoure oder eines Stornos an das ERP-System /CancelOrder

Antwort vom ERP-System /CancelOrder

Übertragung der letzten Shop-Bestellnummer /GetLastOrderNumber

Antwort vom ERP-System für die letzte Shop-Bestellnummer /GetLastOrderNumber

Abfrage eines einzelnen Lagerbestandes (einer Filiale) /GetStockAmount

Antwort vom ERP-System für den einzelnen Lagerbestand /GetStockAmount

Übertragung von allgemeinen, zusätzlichen Kundendaten /GetCommonData

Antwort vom ERP-System für allgemeine Daten /GetCommonData

Im Shop frei konfigurierbare Daten:

Verwandte Themen

​Allgemeines

​REST-Funktionen

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

​Übertragung einer einzelnen Bestellung (Kopf- und Positionsdaten)

​Übertragung einer PDF-Datei

​Storno/Retoure von einer oder mehreren Positionen

​Übertragung der letzten Shop-Bestellnummer

​Übertragung des Lagerbestands/Filialbestandes eines einzelnen Produkts

​Übertragung von allgemeinen Kundendaten

​Ausschließlich verschlüsselter Abruf

​UTF-8-Codierung

​Fehler

​Übertragung einer Liste von Bestellungen /GetOrderList

​Anfrage vom Shop für eine Liste von Bestellungen

​Vom ERP-System vorgegebene freie Suchfilter

​Antwort vom ERP-System

​Fest vorgegebene Kopfdaten

​Im Shop frei konfigurierbare Kopfdaten

​Fest vorgegebene Positionsdaten

​Im Shop frei konfigurierbare Positionsdaten

​Übertragung einer einzelnen Bestellung /GetOrder

​Anfrage vom Shop für eine einzelne Bestellung

​Antwort vom ERP-System /GetOrder:

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

​Übertragung einer PDF-Datei

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

​Antwort vom ERP-System als PDF-Datei /GetFile

​Storno/Retoure von Positionen einer Bestellung

​Senden einer Retoure oder eines Stornos an das ERP-System /CancelOrder

​Antwort vom ERP-System /CancelOrder

​Übertragung der letzten Shop-Bestellnummer /GetLastOrderNumber

​Antwort vom ERP-System für die letzte Shop-Bestellnummer /GetLastOrderNumber

​Abfrage eines einzelnen Lagerbestandes (einer Filiale) /GetStockAmount

​Antwort vom ERP-System für den einzelnen Lagerbestand /GetStockAmount

​Übertragung von allgemeinen, zusätzlichen Kundendaten /GetCommonData

​Antwort vom ERP-System für allgemeine Daten /GetCommonData

​Im Shop frei konfigurierbare Daten:

​Verwandte Themen

Allgemeines

REST-Funktionen

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

Übertragung einer einzelnen Bestellung (Kopf- und Positionsdaten)

Übertragung einer PDF-Datei

Storno/Retoure von einer oder mehreren Positionen

Übertragung der letzten Shop-Bestellnummer

Übertragung des Lagerbestands/Filialbestandes eines einzelnen Produkts

Übertragung von allgemeinen Kundendaten

Ausschließlich verschlüsselter Abruf

UTF-8-Codierung

Fehler

Übertragung einer Liste von Bestellungen /GetOrderList

Anfrage vom Shop für eine Liste von Bestellungen

Vom ERP-System vorgegebene freie Suchfilter

Antwort vom ERP-System

Fest vorgegebene Kopfdaten

Im Shop frei konfigurierbare Kopfdaten

Fest vorgegebene Positionsdaten

Im Shop frei konfigurierbare Positionsdaten

Übertragung einer einzelnen Bestellung /GetOrder

Anfrage vom Shop für eine einzelne Bestellung

Antwort vom ERP-System /GetOrder:

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

Übertragung einer PDF-Datei

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

Antwort vom ERP-System als PDF-Datei /GetFile

Storno/Retoure von Positionen einer Bestellung

Senden einer Retoure oder eines Stornos an das ERP-System /CancelOrder

Antwort vom ERP-System /CancelOrder

Übertragung der letzten Shop-Bestellnummer /GetLastOrderNumber

Antwort vom ERP-System für die letzte Shop-Bestellnummer /GetLastOrderNumber

Abfrage eines einzelnen Lagerbestandes (einer Filiale) /GetStockAmount

Antwort vom ERP-System für den einzelnen Lagerbestand /GetStockAmount

Übertragung von allgemeinen, zusätzlichen Kundendaten /GetCommonData

Antwort vom ERP-System für allgemeine Daten /GetCommonData

Im Shop frei konfigurierbare Daten:

Verwandte Themen