SOAP-from-Shop (EN)
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 |
---|---|---|
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 |
---|---|---|
OrderData | The actual data of the order in XML format. The format and content of the order data is described in the separate documentation | 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. | 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>
<xmlorderv2>


<Header>

<FormatID>WEBSALE-8</FormatID>

<VersionNumber>8</VersionNumber>

<Generator>WEBSALE 8</Generator>

<Copyright><ProductDiscount>0.00</ProductDiscount>

...
<Total>20.00</Total>

<Total_DValue>20,00 EUR</Total_DValue>

<Total_DName>Summe</Total_DName>

</Item>
</OrderList>


</xmlorderv2>

</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 |
---|---|---|
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. | yes |
Example of a GetInquiries request:
Sending the requests by WEBSALE (step 2, "GetInquiriesResponse")
Table of parameters
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 | 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. | 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
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 |
---|---|---|
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 |
---|---|---|
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. | 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
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 |
---|---|---|
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 |
---|---|---|
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. | 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
Format and content - WS-Gutscheindaten (from-Shop) (EN)
Error handling
If an error occurs, the interface returns a "SOAP Fault". The following errors can occur:
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
Please note that these URLs may change in the future. So make sure that they can be changed without much effort on your end.