WS-SOAP-Lagerbestand (DE)

 

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:

  1. Senden des Request durch das externe System

  2. Ü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.