1 Allgemeines
- 1.1 Ausschließlich verschlüsselter Abruf
- 1.2 UTF-8 Codierung
- 1.3 Voraussetzung
2 Senden des Request durch das externe System (Schritt 1, „SetStocks“)
- 2.1 Beispiel SetStocks-Requests:
3 Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „SetStocksResponse“)
- 3.1 Beispiel für eine Antwort auf einen SetStocks-Request:
4 Fehlerbehandlung
5 WSDL-Datei
6 URL des SOAP-Servers für Lagerbestände

Allgemeines

Diese Dokumentation beschreibt das SOAP-basierte Senden von Lagerbeständen zum WEBSALE-Shopsystem von einem externen System. Das Senden von Lagerbeständen erfolgt in zwei Schritten:

Senden des Request durch das externe System
Übergabe der Antwort vom WEBSALE-System

Ausschließlich verschlüsselter Abruf

Der Webservice muss über SSL aufgerufen werden. Unverschlüsselte Verbindungen werden abgelehnt.

UTF-8 Codierung

Alle Daten müssen im UTF-8 Format gesendet werden.

Voraussetzung

Das externe System muss bei jedem Aufruf die ShopID und das Passwort übergeben

Senden des Request durch das externe System (Schritt 1, „SetStocks“)

Bei diesem Request übergibt das externe System eine Liste von Lagerbeständen. Die Zahl der Datensätze ist auf 1000 begrenzt. Sollen mehr Lagerbestände gesetzt werden, so müssen diese auf mehrere Requests aufgeteilt werden.

Parameter	Übergeordnetes Element	Beschreibung	Pflichtfeld

Parameter	Übergeordnetes Element	Beschreibung	Pflichtfeld
ShopID		Die Shop-ID	ja
Password		Das Passwort für die SOAP-Schnittstelle. Das Passwort erhalten Sie von der WEBSALE AG.	ja
MsgID		Optional kann das externe System eine MsgID mitgeben, die vom WEBSALE-System in der Antwort zurückgegeben wird. Für die Verarbeitung des Requests hat die MsgID keine Bedeutung.	nein
Stocks		Enthält für jedes Produkt dessen Bestand gesetzt werden soll ein „Stock“ Unterelement	ja
Stock	Stocks	Enthält die Unterelemente „ProductID“, „Amount“ und optional „Type“	nein
ProductID	Stock	Wenn für das Produkt eine Lagerartikelnummer (StoreID) gesetzt ist, so muss diese im Feld „ProductID“ übergeben werden. Ansonsten muss dieses Feld den Produkt-Index bzw. den Variations-Index enthalten. Die ProductID darf nur ASCII-Zeichen bzw. die ersten 128 Zeichen der ISO-8859-X Zeichensätze enthalten.	ja
Amount	Stock	Der Bestand des Produktes, z. B. „25“. Normalerweise sind Lagerbestandsangaben ganzzahlig. Es können jedoch auch Fließkommawerte (z. B. 25.123) übergeben werden. Sinnvoll sind solche Fließkommawerte allerdings nur dann, wenn auch entsprechende Mengen im Shop bestellt werden können (z. B. bei Flüssigkeiten oder Stoffen). Ob für ein Produkt Fließkommawerte als Bestellmengen zulässig sind wird beim Produkt definiert.	ja
Type	Stock	Kann die Werte „absolute“ (default) oder „relative“ haben. Der Wert „relative“ bewirkt, dass der unter „Amount“ angegebene Wert zu dem im Shop vorhandenen Bestand addiert oder (wenn er ein negatives Vorzeichen hat, z. B. „-25“) davon abgezogen wird. Hat das Feld den Wert „absolute“, so wird der unter „Amount“ angegebene Wert als Lagerbestand in den Shop übernommen.	nein
WarehouseStocks	Stock	Enthält die Daten der Warehouse-Lagerbestände. Zusätzlich zu dem normalen Lagerbestand können für jedes Produkt bis zu 10 Warehouse-Lagerbestände gesetzt werden. Diese Warehouse-Lagerbestände haben für die Funktion des Shops keine Bedeutung, können jedoch im Shop angezeigt werden. Wird für eine ID kein „Warehouse-Lagerbestand“ geliefert, so bleibt der in der Datenbank gespeicherte Wert erhalten. Ein explizites Entfernen von Warehouse-Lagerbeständen ist nicht vorgesehen.	nein
WarehouseStock	WarehouseStocks	Enthält die Daten eines Warehouse-Lagerbestands	nein
ID	WarehouseStock	Die ID des Warehouses	nein
Amount	WarehouseStock	Der Bestand in dem Warehouse	nein

Beispiel SetStocks-Requests:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns="http://www.websale.de/">
	<SOAP-ENV:Body>
		<ns:SetStocks>
			<request>
				<MsgID></MsgID>
				<Password>123456</Password>
				<ShopID>testshop</ShopID>
				<Stocks>
					<Stock>
						<ProductID>&lt;CEV188&gt;&lt;1-4067&gt;</ProductID>
						<Amount>50</Amount>
					</Stock>
					<Stock>
						<ProductID>LAN-123</ProductID>
						<Amount>-3.0</Amount>
						<Type>relative</Type>
						<WarehouseStocks>
							<WarehouseStock>
								<ID>WH1</ID>
								<Amount>11</Amount>
							</WarehouseStock>
							<WarehouseStock>
								<ID>WH2</ID>
								<Amount>9</Amount>
							</WarehouseStock>
						</WarehouseStocks>
					</Stock>
					<Stock>
						<ProductID>LAN-124</ProductID>
						<Amount>dreiundfuenfzig</Amount>
					</Stock>
				</Stocks>
			</request>
		</ns:SetStocks>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „SetStocksResponse“)

Als Antwort übermittelt das WEBSALE-System für jeden übergebenen Lagerbestand den Status der Aktualisierung, d. h. ob ein neuer Datensatz angelegt oder ein vorhandener Datensatz aktualisiert wurde oder ob ein Fehler aufgetreten ist.

Parameter	Beschreibung	Pflichtfeld

Parameter	Beschreibung	Pflichtfeld
SuccessCount	Die Anzahl der erfolgreich aktualisierten Lagerbestände	ja
FailedCount	Die Anzahl der Lagerbestände, die nicht angelegt/aktualisiert werden konnten	ja
MsgID	Die vom externen System im Request übergebene MsgID	nein
StocksStatus	Enthält einen „StockStatus“ für jeden „Stock“ Eintrag im Request	nein
StockStatus	Enthält die Unterelemente „ProductID“, „Amount“, Status, ErrorText und ErrorCode	nein
ProductID	Die im Request übergebene ProductID.	ja
Given Amount	Der im Request übergebene Lagerbestand (Amount)	ja
ShopAmount	In diesem Feld wird der Bestand im Shop nach der Aktualisierung zurückgegeben. Beispiel: Type = relative: Bestand im Shop vor dem Update = 50 Amount = -30 → ShopAmount = 20 Beispiel: Type = absolute: Bestand im Shop vor dem Update = 50 Amount = 30 → ShopAmount = 30	ja
Status	Created: Der Bestand wurde neu angelegt. Updated: Ein vorhandener Bestand wurde aktualisiert. Hinweis: Es können auch Lagerbestände von ProductIDs übergeben werden, die im Shop noch nicht existieren.	ja
ErrorText	Fehler-Text, z. B. „Fehlende ProductID“. Wird nur bei einem Fehler ausgegeben. Siehe nachfolgendes Beispiel.	nein
ErrorCode	Fehler-Code z. B. „ESINV001“. Wird nur bei einem Fehler ausgegeben. Siehe nachfolgendes Beispiel.	nein

Beispiel für eine Antwort auf einen SetStocks-Request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns="http://www.websale.de/">
	<SOAP-ENV:Body>
		<ns:SetStocksResponse>
			<response>
				<SuccessCount>2</SuccessCount>
				<FailedCount>1</FailedCount>
				<StocksStatus>
					<StockStatus>
						<ProductID>&lt;CEV188&gt;&lt;1-4067&gt;</ProductID>
						<GivenAmount>50</GivenAmount>
						<Status>Created</Status>
					</StockStatus>
					<StockStatus>
						<ProductID>LAN-123</ProductID>
						<GivenAmount>-3.0</GivenAmount>
						<ShopAmount>27.98</ShopAmount>
						<Status>Updated</Status>
					</StockStatus>
					<StockStatus>
						<ProductID>LAN-124</ProductID>
						<GivenAmount>dreiundfünfzig</GivenAmount>
						<Status>Error</Status>
						<ErrorCode>ESINV004</ErrorCode>
						<ErrorText>Ungültiger Amount</ErrorText>
					</StockStatus>
				</StocksStatus>
			</response>
		</ns:SetStocksResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Fehlerbehandlung

Tritt ein Fehler auf, der den gesamten Request betrifft, so gibt die Schnittstelle einen „SOAP Fault“ zurück. Folgende Fehler können auftreten:

Fehlermeldung	Beschreibung

Fehlermeldung	Beschreibung
ES001 Fehlende ShopID oder Passwort	Im Request fehlt der Parameter „ShopID“ oder der Parameter „Password“. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert.
ES002 Ungültige ShopID oder ungültiges Passwort	Der Request enthielt zwar „ShopID“ und „Password“, aber es existiert kein passender Shop, das Passwort ist falsch oder die Schnittstelle ist für den Shop gar nicht freigeschaltet. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert.
ES005 Fehler bei Server-Initialisierung	Bei der Initialisierung des SOAP-Servers trat ein Fehler auf. Versuchen Sie es später nochmal oder setzen Sie sich mit der WEBSALE AG in Verbindung.
ES007 SSL erforderlich	Der Aufruf des Programms muss über eine verschlüsselte Verbindung erfolgen. Ein Aufruf mit einer normalen “http” URL ist nicht zulässig.
ES008 Falsche Shop-Version	Es wurde das SOAP-Interface für die V8-Version eines Shops aufgerufen, aber es existiert kein V8-Shop.
ES009 Fehlendes Pflichtfeld XYZ	Ein Pflichtfeld im Request fehlt oder ist leer.
ES012 Formatfehler	Ein Feld für das ein bestimmtes Format vorgegeben ist hat einen falschen Aufbau.
ES015 Ungültiger Request	Das SOAP-Framework konnte den eingehenden Request nicht verarbeiten.
ES016 Mehr als 1000 Lagerbestandsupdates	Der Request enthielt mehr als die zulässigen 1000 Lagerbestände.
ES025 Services deaktiviert	Die Dienste des Shops sind wegen Wartungsarbeiten deaktiviert.

Beispiel für einen „SOAP-Fault“:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns="http://www.websale.de/">
	<SOAP-ENV:Body>
		<SOAP-ENV:Fault>
			<faultcode>SOAP-ENV:Client</faultcode>
			<faultstring>ES007 SSL erforderlich</faultstring>
		</SOAP-ENV:Fault>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Folgende Fehler können in der „FailedStocks“ Liste der SetStocksResponse auftreten:

Fehlermeldung	Beschreibung

Fehlermeldung	Beschreibung
ESINV001 Fehlende ProductID	Der Parameter „ProductID“ fehlte oder war leer.
ESINV002 Ungültige ProductID	Der Parameter „ProductID“ enthielt einen ungültigen Wert.
ESINV003 Fehlender Amount	Der Parameter „Amount“ fehlte oder war leer.
ESINV004 Ungültiger Amount	Der Parameter „Amount“ enthielt einen ungültigen Wert.
ESINV005 Ungültiger Type	Das „Type“ Feld enthielt einen ungültigen Wert.
ESINV006 Fehlende Warehouse-ID	In einer <WarehouseStocks>-Sektion ist keine ID vorhanden.

WSDL-Datei

Auf der untergeordneten Seite finden Sie eine WSDL-Datei (stocks.wsdl), die Sie nutzen können, um den Code zur Anbindung der Schnittstelle automatisiert zu erstellen. Voraussetzung dafür ist, dass es für die von Ihnen verwendete Programmiersprache ein passendes Tool gibt um die WSDL einzulesen.

URL des SOAP-Servers für Lagerbestände

Für V8-Shops lautet die URL des SOAP-Servers derzeit:

Lagerbestände: https://soap-toshop.websale.net/stock

Bitte beachten Sie, dass sich diese URL in Zukunft ändern kann. Stellen Sie also sicher, dass sich diese ohne größeren Aufwand bei Ihnen ändern lässt.

WS-SOAP-Lagerbestand (DE)