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:

  1. Sending of the request by the external system

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

  1. Sending of the request by the external system

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

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:

  1. Sending of the request by the external system

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

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:

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:

  1. Sending of the request by the external system

  1. 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

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

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:

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