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:

<?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:GetInquiries>
      <request>
        <ShopID>testshop</ShopID>
        <Password>123456</Password>
        <Date>2013-05-11</Date>
        <Time>09:53:11</Time>
        <InquiryNumber>7654321</InquiryNumber>
        <MaxInquiryCount>11</MaxInquiryCount>
        <SkipFirstMatch>false</SkipFirstMatch>
      </request>
    </ns:GetInquiries>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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:

<?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:GetInquiriesResponse>
      <response>
        <Finished>true</Finished>
        <MsgID></MsgID>
        <InquiryCount>1</InquiryCount>
        <Inquiries>
          <Inquiry>
            <Date>2012-05-25</Date>
            <Time>12:24:00</Time>
            <InquiryNumber>161337941471350</InquiryNumber>
            <InquiryData>  
              &lt;xmlorderv2&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;Header&gt;&#xD;&#xA;  
              &lt;FormatID&gt;INQUIRY-4&lt;/FormatID&gt;&#xD;&#xA;  
              &lt;Generator&gt;INQUIRY-4&lt;/Generator&gt;&#xD;&#xA;  
              ...  
              &lt;value&gt;&#xD;&#xA;  
                nvsjvbkjs 
                svnbsj&#xD;&#xA;  
              &lt;/value&gt;&#xD;&#xA;  
              &lt;/Item&gt;&#xD;&#xA;  
              &lt;/Inquiry&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;Newsletter&gt;&#xD;&#xA;&lt;/Newsletter&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;/xmlorderv2&gt;&#xD;&#xA;
            </InquiryData>
          </Inquiry>
        </Inquiries>
      </response>
    </ns:GetInquiriesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Format and content of the inquiry data

The format and the content is described in the separate documentation

Format and content - WS-Anfragedaten (EN)

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:

<?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:GetAddresses>    
      <request>    
        <ShopID>testshop</ShopID>
        <Password>123456</Password>
        <Date>2013-05-11</Date>    
        <Time>12:10:10</Time>    
        <AddressNumber>1234567</AddressNumber>    
        <MaxAddressCount>10</MaxAddressCount>    
        <SkipFirstMatch>false</SkipFirstMatch>   
      </request>  
    </ns:GetAddresses> 
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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 Format and content - WS-Adressdatenänderungen (EN)	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:

<?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:GetAddressesResponse>
      <response>
        <Finished>true</Finished>
        <MsgID></MsgID>
        <AddressCount>1</AddressCount>
        <Addresses>
          <Address>
            <AddressData>  
              &lt;xmlorderv2&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;Header&gt;&#xD;&#xA;  
              &lt;FormatID&gt;WEBSALE-8&lt;/FormatID&gt;&#xD;&#xA;  
              &lt;Generator&gt;WEBSALE 8&lt;/Generator&gt;&#xD;&#xA;  
              &lt;VersionNumber&gt;8&lt;/VersionNumber&gt;&#xD;&#xA;  
              ...  
              &lt;Type&gt;1&lt;/Type&gt;&#xD;&#xA;  
              &lt;CCType&gt;0&lt;/CCType&gt;&#xD;&#xA;  
              &lt;/CreditCard&gt;&#xD;&#xA;&#xD;&#xA;  
              &lt;/xmlorderv2&gt;&#xD;&#xA;
            </AddressData>
            <Date>2012-05-25</Date>
            <AddressNumber>161337941471350</AddressNumber>
            <Time>12:24:00</Time>
          </Address>
        </Addresses>
      </response>
    </ns:GetAddressesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Format and content of the address changes

The format and content is described in the separate documentation

Format and content - WS-Adressdatenänderungen (EN)

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.

<?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:GetVouchers>   
      <request>    
        <ShopID>testshop</ShopID>    
        <Password>123456</Password>    
        <VoucherNumber>1234-1234-1234-1234</VoucherNumber>    
        <MaxVoucherCount>100</MaxVoucherCount>    
        <SkipFirstMatch>false</SkipFirstMatch>   
      </request>  
    </ns:GetVouchers> 
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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

Table of parameters

Parameter	Description	Required field

Parameter	Description	Required field

SOAP-from-Shop (EN)

General

Exclusively encrypted retrieval

UTF-8 encoding

Order retrieval

Prerequisite

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

First retrieval

Running mode

Retrieve single order

Note

Table of parameters

Examples GetOrders requests:

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

Table of parameters

Example of a response to a GetOrders request:

Format and content of the order data

Retrieval of Inquiries

Prerequisite

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

First retrieval

Running mode

Retrieve single request

Table of parameters

Example of a GetInquiries request:

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

Table of parameters

Example of a response to a GetInquiries request:

Format and content of the inquiry data

Retrieval of address changes

Prerequisite

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

First retrieval

Running mode

Retrieve single address change

Table of parameters

Example for a GetAddresses request:

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

Table of parameters

Example of a response to a GetAddresses request:

Format and content of the address changes

Retrieval of vouchers

Prerequisite

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

First retrieval

Running mode

Retrieve single voucher data

Table of parameters

Example of a GetVouchers request:

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

Table of parameters