General

This documentation describes the SOAP-based retrieval of

Orders
Requests (INQUIRY4)
Address data changes
Voucher data

from the WEBSALE shop system.

Exclusively encrypted retrieval

The web service must be accessed via SSL. Unencrypted connections will be rejected.

UTF-8 encoding

All data is transferred in UTF-8 format.

Order retrieval

The retrieval of orders is done in two steps:

Sending of the request by the external system
transfer of the requested data from the WEBSALE system

Prerequisite

The external system must

transfer the ShopID and the password with each request
save the last received order number.

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

First retrieval

During the first retrieval of orders, the retrieving external system does not yet have the last order number. In this case, the request is made with date+time from which the orders stored in the shop system should be transmitted. The "SkipFirstMatch" parameter is set to "false".

Running mode

In this request, the external system passes the last saved (last received) order number where the transmission should start. Optionally, the maximum desired number of orders can also be specified.

If there are more orders in the WEBSALE system than requested by the external system, the external system must repeat the GetOrders procedure until all present orders have been transmitted. The external system stores the last received order number and performs the next request with it. The "SkipFirstMatch" parameter is set to "true" during this process.

Retrieve single order

For this purpose the order number and the maximum number of orders to be sent is passed with "1". The "SkipFirstMatch" parameter is set to "false".

Note

If a request contains both an order number and date+time, the order number is used and date+time are ignored.

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
ShopID	The shop ID	yes
Password	The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
SubshopIDs	A comma-separated list of subshopIDs for which the orders should be retrieved. If the list is empty or the parameter is missing completely, the orders of all subshops will be sent. On the server side, the subshopIDs may also be restricted. In this case, the transmission will abort with an error if subshops are specified in the SubshopID list that are not enabled.	no
Date	Date in YYYY-MM-DD format at which the transfer should start.	yes, if OrderNumber is missing
Time	Time in the format HH:MM:SS at which the transfer should start.	no
MaxOrderCount	The maximum number of orders to be sent (default value: 100, maximum: 1000).	no
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
OrderNumber	Order number at which the transmission should start.	yes, if Date/Time is missing
SkipFirstMatch	"true": The transfer will start with the following order. "false": The transfer will start from the given order number or date+time	yes

Examples GetOrders requests:

(a) Retrieve max 100 orders received since 11/05/2013 at 11:00:

<?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:GetOrders>   
      <request>
        <ShopID>testshop</ShopID>
        <Password>123456</Password>
        <Date>2013-05-11</Date>
        <Time>11:00:00</Time>
        <SkipFirstMatch>false</SkipFirstMatch>
      </request>
    </ns:GetOrders>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

b) Retrieve max 10 orders received after the order with OrderNumber "3744567":

<?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:GetOrders>   
      <request>    
        <ShopID>testshop</ShopID>    
        <Password>123456</Password>    
        <OrderNumber>3744567</OrderNumber>    
        <MaxOrderCount>10</MaxOrderCount>    
        <SkipFirstMatch>true</SkipFirstMatch>   
      </request>  
    </ns:GetOrders> 
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sending the orders through WEBSALE (step 2, "GetOrdersResponse")

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
OrderData	The actual data of the order in XML format. The format and content of the order data is described in the separate documentation Format and content - WS-Bestelldaten (EN)	yes, within "Order
Date	Date of the orders in the format YYYY-MM-DD	yes, within "Order
Time	Time of the order in the format HH:MM:SS	yes, within "Order
Finished	"true: All present orders have been sent. "false": Orders are still present. In this case a new request must be made.	yes
OrderNumber	Order number	yes, within "Order
MsgID	MsgID passed by the external system in the request	no
Order	Contains the subelements "Date", "Time", "OrderNumber", and "OrderData	no
OrderCount	The number of orders sent	yes
Orders	Contains an "Order" subelement for each of the sent orders	yes
SubshopIDs	If the SubshopIDs field was filled in the request or the shop configuration restricts the retrieval of order data to certain subshops, then a comma-separated list of the subshopIDs for which order data can be retrieved is returned here.	no

Example of a response to a GetOrders 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:GetOrdersResponse>
      <response>
        <Finished>true</Finished>
        <MsgID></MsgID>
        <OrderCount>2</OrderCount>
        <Orders>
          <Order>
            <OrderNumber>132499966231815</OrderNumber>
            <Date>2013-05-10</Date>
            <Time>16:27:42</Time>
            <OrderData>  
              &lt;xmlorderv2&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;Header&gt;&#xD;&#xA;  
              &lt;FormatID&gt;WEBSALE-8&lt;/FormatID&gt;&#xD;&#xA;  
              &lt;VersionNumber&gt;8&lt;/VersionNumber&gt;&#xD;&#xA;  
              &lt;Generator&gt;WEBSALE 8&lt;/Generator&gt;&#xD;&#xA;  
              &lt;Copyright&gt;&lt;ProductDiscount&gt;0.00&lt;/ProductDiscount&gt;&#xD;&#xA;       
              ...  
              &lt;Total&gt;20.00&lt;/Total&gt;&#xD;&#xA;  
              &lt;Total_DValue&gt;20,00 EUR&lt;/Total_DValue&gt;&#xD;&#xA;  
              &lt;Total_DName&gt;Summe&lt;/Total_DName&gt;&#xD;&#xA;  
              &lt;/Item&gt;&#xD;&#xA;&lt;/OrderList&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;/xmlorderv2&gt;&#xD;&#xA;
            </OrderData>
          </Order>
          <Order>
            ...
          </Order>
        </Orders>
      </response>
    </ns:GetOrdersResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Format and content of the order data

The format and content is described in the separate documentation

Format and content - WS-Bestelldaten (EN)

Retrieval of Inquiries

Analogous to the retrieval of orders, the retrieval of inquiries is done in two steps:

Sending of the request by the external system
Sending of the requested data by the WEBSALE system

Prerequisite

The external system must

pass the ShopID and the password with each request
store the last received request number and the last received date+time of the request

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

First retrieval

At the first request retrieval, the external system does not yet have the last request number. In this case, the request is sent only with date+time from which the requests should be transmitted. The parameter "SkipFirstMatch" is set to "false". The next request is then made with the last stored data of request number, date+time.

Running mode

With this request the external system passes the stored (last received) request number and the stored (last received) date+time of the request from which the transmission should start and optionally how many requests should be sent at maximum.
If there are more requests in the WEBSALE system than requested by the external system, the external system must repeat the procedure until all present requests have been transmitted. The "SkipFirstMatch" parameter is set to "true". The external system stores the last received request number and the last received date+time and performs the next request with the stored data.

Retrieve single request

For this purpose the request number, date+time and the maximum number of requests to be sent is passed with "1". The parameter "SkipFirstMatch" is set to "false".

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
ShopID	The shop ID	yes
Password	The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
Date	Date in the format YYYY-MM-DD at which the transfer should start.	yes
Time	Time in the format HH:MM:SS at which the transfer should start.	no
InquiryNumber	Inquiry number	no
MaxInquiryCount	The maximum number of inquiries to send (default value: 100, maximum: 1000).	no
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
SkipFirstMatch	"true": The transfer starts with the following request. "false": The transfer starts from the transferred request number incl. date+time	yes

Example of a GetInquiries request:

Sending the requests by WEBSALE (step 2, "GetInquiriesResponse")

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
InquiryData	The actual request data in XML format. The format and content of the request data is described in the separate documentation Format and content - WS-Anfragedaten (EN)	yes, within "Inquiry
Date	Date of the inquiry in the format YYYY-MM-DD	yes, within "Inquiry
Time	Time of the Inquiry in format HH:MM:SS	yes, within "Inquiry
Finished	"true": All available inquiries have been sent. "false": Inquiries are still present. In this case a new request must be sent.	yes
InquiryNumber	The InquiryNumber	yes, within "Inquiry
MsgID	The MsgID passed by the external system in the request	no
Inquiry	Contains the subelements "Date", "Time", "InquiryNumber", and "InquiryData	no
InquiryCount	The number of sent inquiries	yes
Inquiries	Contains an "Inquiry" subelement for each of the sent inquiries	yes

Example of a response to a GetInquiries request:

Format and content of the inquiry data

The format and the content is described in the separate documentation

Retrieval of address changes

When a customer orders from the shop, their address data is transmitted along with the other order data. Therefore, an explicit retrieval of address changes is not strictly necessary.
When retrieving address changes, changes are transmitted to addresses that customers have made but have not placed an order.

Analogous to the retrieval of orders, the retrieval of address changes takes place in two steps:

Sending of the request by the external system
Sending of the requested data by the WEBSALE system

Prerequisite

The external system must

pass the ShopID and the password with each request
store the address number and the last received date+time of the address change

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

First retrieval

During the first retrieval of address changes, the external system does not yet have the last address number. In this case, the request is made only with date+time from which the address changes are to be transmitted. The parameter "SkipFirstMatch" is set to "false". The next request is then made with the last stored data of address number, date+time.

Running mode

With this request the external system passes the stored (last received) address number and the stored (last received) date+time of the address change from which the transmission should start and optionally how many address changes should be sent at maximum.
If there are more address changes in the WEBSALE system than requested by the external system, the external system must repeat the procedure until all available address changes have been transmitted. The "SkipFirstMatch" parameter is set to "true". The external system stores the last received address number and the last received date+time and performs the next request with the stored data.

Retrieve single address change

For this purpose the address number, date+time and the maximum number of address changes to be sent is passed with "1". The parameter "SkipFirstMatch" is set to "false".

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
ShopID	The shop ID	yes
Password	The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
Date	Date in the format YYYY-MM-DD at which the transfer should start.	yes
Time	Time in the format HH:MM:SS at which the transfer should start.	no
AddressNumber	Address number	no
MaxAddressCount	The maximum number of address changes to send (default value: 100, maximum: 1000).	no
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
SkipFirstMatch	"true": The transmission starts with the following address change. "false": The transfer starts from the transferred address number incl. date+time	yes

Example for a GetAddresses request:

Sending the address changes by WEBSALE (step 2, "GetAddressesResponse")

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
AddressData	The actual data in XML format. The format and content of the address changes is described in the separate documentation	yes, within "Address
Date	Date of the address change in the format YYYY-MM-DD	yes, within "Address
Time	Time of the address change in the format HH:MM:SS	yes, within "Address
Finished	"true: All available address changes have been sent. "false": There are still address changes. In this case a new request must be made.	yes
AddressNumber	The address number	yes, within "Address
MsgID	The MsgID passed by the external system in the request	no
Address	Contains the subelements "Date", "Time", "AddressNumber", and "AddressData	no
AddressCount	The number of address changes sent	yes
Addresses	Contains an "Address" subelement for each of the sent address changes	yes

Example of a response to a GetAddresses request:

Format and content of the address changes

The format and content is described in the separate documentation

Retrieval of vouchers

With the help of this interface external systems can retrieve the data of vouchers which have been generated with the voucher generator of WEBSALE AG. The purpose of the interface is not to retrieve data about the vouchers redeemed in the shop; this data is transmitted together with the order data.

The retrieval of the vouchers is done in two steps, analogous to the retrieval of orders:

Sending of the request by the external system

Sending the requested data by the WEBSALE system

Prerequisite

The external system must

transfer the ShopID and the password with each call
save the last received voucher number

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

First retrieval

During the first retrieval of vouchers, the external system does not yet have the last voucher number. In this case the request is made only with date+time from which the vouchers should be transmitted. The parameter "SkipFirstMatch" is set to "false". The next request is then made with the last saved voucher number.

Running mode

With this request the external system passes the stored (last received) voucher number from which the transmission should start and optionally how many vouchers should be sent at maximum.
If there are more vouchers in the WEBSALE system than requested by the external system, the external system has to repeat the procedure until all present vouchers have been transmitted. The parameter "SkipFirstMatch" is set to "true". The external system stores the last received voucher number and performs the next request with it.

Retrieve single voucher data

For this purpose the voucher number and the maximum number of vouchers to be sent is passed with "1". The parameter "SkipFirstMatch" is set to "false".

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
ShopID	The shop ID	yes
Password	The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
Date	Date in format YYYY-MM-DD at which the transfer should start.	no
Time	Time in the format HH:MM:SS at which the transfer should start.	no
VoucherNumber	Voucher number	no
MaxVoucherCount	The maximum number of vouchers to send (default value: 100, maximum: 1000).	no
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
SkipFirstMatch	"true": The transfer starts with the following voucher. "false": The transfer starts from the transferred voucher number	yes

Example of a GetVouchers request:

GetVoucher "1234-1234-1234-1234" and max 99 vouchers generated after it.

Sending the data by WEBSALE (step 2, "GetVouchersResponse")

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field
VoucherData	The actual data of the voucher in XML format	yes, within "Voucher
Date	Date of generation of the voucher in YYYY-MM-DD format	yes, within "Voucher
Time	Time of the voucher generation in the format HH:MM:SS	yes, within "Voucher
Finished	"true": All present vouchers have been sent. "false": Vouchers are still present. In this case a new request must be made.	yes
VoucherNumber	Voucher number	yes, within "Voucher
MsgID	MsgID passed by the external system in the request	no
Voucher	Contains the subelements "Date", "Time", "Number" and "VoucherData".	no
VoucherCount	The number of vouchers sent	yes
Vouchers	Contains a "Voucher" subelement for each of the sent vouchers	yes

Example of a response to a GetVouchers request:

Format and content of the voucher data

The format and the content is described in the separate documentation

Error handling

If an error occurs, the interface returns a "SOAP Fault". The following errors can occur:

Error message	Description

Error message	Description
ES001 Missing ShopID or Password	The "ShopID" parameter or the "Password" parameter 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. If the error persists for more than 30 minutes, 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 shop version	The SOAP interface for the V8 version of a shop was called, but no V8 shop exists.
ES009 Missing required field XYZ	A required field in the request is missing or empty.
ES010 Invalid record ID	A record ID (OrderNumber, InquiryNumber, AddressNumber or VoucherNumber) was passed in the request that does not exist in the WEBSALE system or does not exist for the specified date.
ES011 Date missing	A date is additionally required for the requested records even if a record ID is specified (inquiries and address data changes).
ES012 Format error	A field for which a specific format is specified (e.g. Date or Time) has an incorrect structure.
ES013 Subshop not enabled	The "SubshopIDs" field contained a SubshopID for which the collection of order data is not enabled.
ES014 Invalid MaxCount value	A maximum of 1000 records can be retrieved per SOAP call, higher values in a Max***Count field will result in this error, "0" or negative values are also invalid.
ES015 Invalid request	The SOAP framework could not process the incoming request.
ES016 Plugin error	An order could not be processed by a conversion plugin.

Example of a "SOAP Fault":

WSDL sample files

For each of the described interfaces of this documentation you will find a WSDL file (order.wsdl, inquiry.wsdl, address.wsdl and voucher.wsdl) on the subordinate page, which you can use to create the code to connect the interface automatically. The prerequisite for this is that there is a suitable tool for the programming language you are using to read in the WSDLs.

URL of the SOAP server

For V8 shops, the URLs of the SOAP server are:

Orders

Address changes

Requests

Coupons

https://soap-fromshop.websale.net/orders

https://soap-fromshop.websale.net/addresses

https://soap-fromshop.websale.net/inquiries

https://soap-fromshop.websale.net/vouchers

Please note that these URLs may change in the future. So make sure that they can be changed without much effort on your end.