General

This documentation describes the SOAP-based sending of stock to the WEBSALE shop system from an external system. Sending stock is done in two steps:

Sending of the request by the external system
transfer of the response from the WEBSALE system

Exclusively encrypted retrieval

The web service must be called via SSL. Unencrypted connections are rejected.

UTF-8 encoding

All data must be sent in UTF-8 format.

Requirement

The external system must pass the ShopID and password for each call

Sending the request by the external system (step 1, "SetStocks")

In this request, the external system passes a list of stock records. The number of records is limited to 1000. If more stock records are to be set, they must be divided into several requests.

Parameters	Parent element	Description	Required field

Parameters	Parent element	Description	Required field
ShopID		The shop ID	yes
Password		The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
MsgID		Optionally the external system can provide a MsgID which will be returned by the WEBSALE system in the response. The MsgID has no meaning for the processing of the request.	no
Stocks		Contains a "Stock" sub-element for each product whose stock is to be set	yes
Stock	Stocks	Contains the sub-elements "ProductID", "Amount" and optionally "Type".	no
ProductID	Stock	If a stock item number (ShopID) is set for the product, this must be passed in the "ProductID" field. Otherwise this field must contain the product index or the variation index. The ProductID may only contain ASCII characters or the first 128 characters of the ISO-8859-X character sets.	yes
Amount	Stock	The stock of the product, e.g. "25". Normally, stock amounts are integers. However, floating point values (e.g. 25,123) can also be passed. However, such floating point values are only useful if corresponding quantities can also be ordered in the shop (e.g. for liquids or substances). Whether floating point values are permitted as order quantities for a product is defined in the product.	yes
Type	Stock	Can have the values "absolute" (default) or "relative". The value "relative" causes the value specified under "Amount" to be added to or (if it has a negative sign, e.g. "-25") subtracted from the stock available in the shop. If the field has the value "absolute", the value specified under "Amount" will be taken as the stock in the shop.	no
WarehouseStocks	Stock	Contains the data of the warehouse stock. In addition to the normal warehouse stock, up to 10 warehouse stocks can be set for each product. These warehouse stock levels have no meaning for the function of the shop, but can be displayed in the shop. If no "Warehouse stock" is supplied for an ID, the value stored in the database is retained. Explicit removal of warehouse stock is not provided.	no
WarehouseStock	WarehouseStocks	Contains the data of a warehouse stock	no
ID	WarehouseStock	The ID of the warehouse	no
Amount	WarehouseStock	The amount of stock in the warehouse	no

Example 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>fifty-three</Amount>
					</Stock>
				</Stocks>
			</request>
		</ns:SetStocks>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (step 2, "SetStocksResponse")

As a response, the WEBSALE system transmits the status of the update for each transferred stock, i.e. whether a new record was created or an existing record was updated, or whether an error occurred.

Parameter	Description	Required field

Parameter	Description	Required field
SuccessCount	The number of successfully updated stock records	yes
FailedCount	The number of inventory items that could not be created/updated	yes
MsgID	The MsgID passed by the external system in the request	no
StocksStatus	Contains a "StockStatus" for each "Stock" entry in the request	no
StockStatus	Contains the subelements "ProductID", "Amount", Status, ErrorText and ErrorCode	no
ProductID	The ProductID passed in the request.	yes
Given Amount	The amount of stock transferred in the request	yes
ShopAmount	This field returns the amount of stock in the shop after the update. Example: Type = relative: Inventory in the shop before the update = 50 Amount = -30 → ShopAmount = 20 Example: Type = absolute: Inventory in the shop before update = 50 Amount = 30 → ShopAmount = 30	yes
Status	Created: The inventory was newly created. Updated: An existing inventory has been updated. Note Stocks of ProductIDs that do not yet exist in the shop can also be transferred.	yes
ErrorText	Error text, e.g. "Missing ProductID". Will only be output in case of an error. See the following example.	no
ErrorCode	Error code, e.g. "ESINV001". Only output in the event of an error. See following example.	no

Example of a response to a 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>fifty-three</GivenAmount>
						<Status>Error</Status>
						<ErrorCode>ESINV004</ErrorCode>
						<ErrorText>Invalid amount</ErrorText>
					</StockStatus>
				</StocksStatus>
			</response>
		</ns:SetStocksResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Error handling

If an error occurs that affects the entire request, the interface returns a "SOAP Fault". The following errors may occur:

Error Message	Description

Error Message	Description
ES001 Missing ShopID or password	The parameter "ShopID" or the parameter "Password" is missing in the request. For security reasons, the error is not specified exactly.
ES002 Invalid ShopID or password	The request contained "ShopID" and "Password", but there is no matching shop, the password is wrong or the interface is not enabled for the shop at all. For security reasons the error is not specified exactly.
ES005 Error during server initialization	An error occurred while initializing the SOAP server. Try again later or contact WEBSALE AG.
ES007 SSL required	The program must be called via an encrypted connection. A call with a normal "http" URL is not allowed.
ES008 Wrong shops version	The SOAP interface for the V8 version of a shops was called, but no V8 shops exists.
ES009 Missing required field XYZ	A required field in the request is missing or empty.
ES012 Format error	A field for which a certain format is specified has an incorrect structure.
ES015 Invalid request	The SOAP framework could not process the incoming request.
ES016 More than 1000 inventory updates	The request contained more than the allowed 1000 stock updates.
ES025 Services disabled	The shop's services are disabled due to maintenance.

Example of a "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 required</faultstring>
		</SOAP-ENV:Fault>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following errors can occur in the "FailedStocks" list of SetStocksResponse:

Error message	Description

Error message	Description
ESINV001 Missing ProductID	The parameter "ProductID" was missing or empty.
ESINV002 Invalid ProductID	The "ProductID" parameter contained an invalid value.
ESINV003 Missing Amount	The parameter "Amount" was missing or empty.
ESINV004 Invalid Amount	The Amount parameter contained an invalid value.
ESINV005 Invalid Type	The "Type" field contained an invalid value.
ESINV006 Missing Warehouse ID	There is no ID in a <WarehouseStocks> section.

WSDL file

A WSDL file (stocks.wsdl) is part of this documentation, which you can find on the subordinate page for download. You can use it to automatically create the code to connect the interface. The prerequisite for this is that there is a suitable tool for the programming language you use to read in the WSDL.

URL of the SOAP server for stock

For WEBSALE V8 shops, the URL of the SOAP server is currently:

Stocks: https://soap-toshop.websale.net/stock

Please note that this URL may change in the future. So make sure that it can be changed without much effort on your end.

Dokumentation

WS-Soap-Lagerbestand (EN)