- Confidential -

Transfer to third parties only allowed with written permission of WEBSALE AG.

General

This document describes the SOAP-based generation and retrieval of vouchers through an external system.

Exclusively encrypted retrieval

The web service must be accessed over SSL. Non-encrypted connections will be rejected.

UTF-8 encoding

All data must be sent in UTF-8 format.

Requirements

The external system must transfer the ShopID and password with every call. This applies to all requests described in this document.

Generation and retrieval of vouchers

The generation and retrieval of vouchers takes place in two steps

The external system sends the request with the voucher data.
The WEBSALE Shop system returns the voucher data.

The external system sends the request (Step 1,"CreateVouchers")

With this request, the external system transfers the voucher data or the ID of the template batch from which the coupon data is to be transferred, as well as the number of vouchers that are to be generated.

If voucher data fields are not explicitly transferred in the request, they are taken from the specified template batch. If, for example, the field "Amount" with the value of the voucher is missing in the request, the value of the voucher entered for the specified batch is used for the generation.

If it is not possible to completely remove a field from the request, but the corresponding value of the batch is still to be used, this can be achieved by transferring the following special values as the field value:

String value: $ChargeVal$
Integer value: -999999999
Float value: -999999999 or smaller

The template batch used for generation must itself be put in the voucher generator in the online service area.

If the flag "SubscribeVoucher" is set, then vouchers will be generated that are intended to be sent with a newsletter registration. In this instance, it is not necessary to enter a ChargeID because the data will in this case be taken from a special "registration voucher" that must be placed in the online service area for this purpose. Instead of the ChargeID, the request must include the Subshop ID in which the newsletter registration takes place.

Parameter	Description	Required field
ShopID	The ID of the Shop	Yes
Password	The password for the SOAP interface. The password is obtained from WEBSALE AG.	Yes
MsgID	The external system can optionally give a MsgID that will be returned in the answer from the WEBSALE system. The MsgID has no significance for processing the request.	No
VoucherCount	The number of vouchers that are to be generated. This number is limited to a maximum of 1,000 per each access.	Yes
SubscribeVoucher	"true": a "registration voucher" will be generated, the field "ChargeId" will be ignored and instead the field "SubscribeSubshopID" will be used. Default value: false	No
SubscribeSubshopID	If SubscribeVoucher = true, then the ID of the Subshop in which the newsletter registration takes place must be entered here.	With registration- vouchers
ChargeId	The template batch ID from which the voucher data is to be adopted or the ID of the batch that is to be applied.	yes, except for registration- vouchers
CreateCharge	"true": A new batch is created with the ID given by ChargeId. "false”: The batch specified under ChargeId is used to determine the data of the vouchers to be generated. The generated coupons are added to this batch. Default value: false	No
Amount	The amount of the voucher, for example, "25.50"	No
AmountType	0: Amount contains an absolute amount 1: Amount contains a percentage 2: Amount contains a percentage and a capped value. This type can only be used for set sub-items. The product numbers or indices of these set sub-items must be supplied in the CatProdFilter field. The total of the item is capped (regardless of the quantity) to the amount specified in the Amount/AmountMultiCurrency field. For vouchers of this type, no "normal" maximum amount can be specified. Default value: 0	No
AmountMultiCurrency	This field is used for MultiCurrency vouchers instead of Amount. For a MultiCurrency voucher, the amount of the voucher is displayed in multiple currencies. Format: `<g>` `<c>ISO-Code of the currency</c>` `<a>Amount</a>` `</g>...` Example `<g><c>EUR</c><a>10.00</a></g>` `<g><c>GBP</c>a>8.00</a></g>`	No
Currency	Currency of voucher, for example, "EUR"	No
MinOrderValue	Minimum order value from which the voucher is redeemed can be	No
MinOrderValueMultiCurrency	This field is used for MultiCurrency vouchers instead of MinOrderValue. Format: `<g><c>ISO code of currency</c><a>amount</a></g>...`	No
MaxDiscountValue	Only for percentage discount: The maximum value of the voucher that can be redeemed.	No
MaxDiscountValueMultiCurrency	Only for percentage discount: The maximum value of the voucher that can be redeemed.	No
SubShop	Subshops where the voucher is valid. If this field is empty, then the voucher can be used in all subshops. Multiple subshops can be specified in a comma-separated list.	No
Type	The type of vouchers. The following types are supported. 0: Remaining amount can be reused 1: Balance forfeited 2: Universal voucher 3: Universal voucher (customer-specific) 4: Universal voucher (only for new customers) 5: Remaining amount can be reused (for new customers only) 6: Remaining amount forfeited (for new customers only) 7: Individual multiple voucher (with automatic customer retention, i.e. as soon as a customer has redeemed the voucher, only this customer can redeem it - as often as desired) Default value: 0	No
Type2	Promotional voucher/Purchase voucher 1: Promotional voucher 2: Purchase voucher Default value: 1	No
ValidFrom	Date from which the voucher is valid, in the format "YYYY-MM-DD", e.g. "2018-06-30"	No
ValidUntil	Date through which the voucher is valid, in the format "YYYY-MM-DD"	No
VATIndex	The VAT ID of the voucher. This can either be a value configured in the shop.config in the "<VATRates>" section or one of the special values "-1" or "0". "-1" means "Standard", in this case the voucher will be identified by the code configured under DeliveryVATRate. "0" indicates "No VAT". Default-Value: -1	No
Pool	"true": The voucher number is taken from an existing voucher pool and activated. The voucher pool is managed via an import file. If "true" is transferred for the pool, this excludes the use of CreateCharge and SubscribeVoucher. "false": The voucher number is regenerated. Default value: "false".	No
SubShopValidity	If a subshop ID is transferred in this field, only vouchers from the pool that can be redeemed in this subshop are returned. (It only makes sense to specify this field when calling up pool vouchers if there are vouchers within a batch that can be redeemed for different subshops, which is not recommended.)	No
CustomerFilter	Limitation of validity to certain customers. Customers can be identified either by the user index (<i></i>) or by the customer number (<n></n>). Either user indices or customer numbers can be used for a voucher, but not both at the same time. Example 1: `<i>123</i>` Example 2: `<n>abc</n><n>xyz</n>`	No
CatProdFilterSetBehavior	0: Product number or index of the top product determines whether the voucher is used for a set item. 1: Product number or index of the sub-products determine whether the voucher is used for a set article. Default value: 0	No
CatProdFilter	With this field the validity of the voucher can be limited to certain products or categories. The restriction can be made by specifying category indices (<ci></ci>), product indices (<pi></pi>) or product numbers (<pn></pn>). For each voucher, the field can contain either <pi> or <pn> entries, but no combinations of these two tags. Example 1, restriction to the categories with the indices "543" and "345": `<ci>543</ci><ci>345</ci>` Example 2, restriction to the products with the numbers "abc" and "xyz" `<pn>abc</pn><pn>xyz</pn>`	No
ChargeDescr	Description of the batch as displayed by the online service area	No
ChargeLabel	"Label" of the voucher which is included in the order data and can be used for evaluations by downstream systems. Several "labels" can be specified as comma-separated list.	No

Example of a CreateVouchers 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:CreateVouchers>
      <request>
        <ShopID>TestShop</ShopID>
        <Password>secret</Password>
        <MsgID>123</MsgID>
        <VoucherCount>2</VoucherCount>
        <ChargeId>TestCharge</ChargeId>
        <Amount>10.00</Amount>
        <AmountType>0</AmountType>
      </request>
    </ns:CreateVouchers>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (Step 2, "CreateVouchersResponse")

As an answer the WEBSALE system delivers the voucher data to be used for generation (independent of whether it is explicitly given in the request or whether it is read from a template batch)

Parameter	Superior element	Description	Required field
MsgID		The MsgID given in the request	No
Amount	The value given in the request or determined from the template-batch.		Yes
AmountType			Yes
Currency			Yes
MinOrderValue			No
Subshop			No
Type			Yes
Type2			Yes
ValidFrom			No
ValidUntil			No
VATIndex			Yes
CustomerFilter			No
CatProdFilterSetBehavior			No
CatProdFilter			No
AmountMultiCurrency			No
MinOrderValueMultiCurrency			No
MaxDiscountValueMultiCurrency			No
VoucherNumbers		Contains a VoucherNumber element for each voucher generated	Yes
Voucher Number	VoucherNumbers	Contains a generated voucher number	Yes

Example of an answer to a CreateVouchers 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:CreateVouchersResponse>
      <response>  
        <MsgID>123</MsgID>
        <Amount>10.00</Amount>
        <AmountType>0</AmountType>
        <Currency>EUR</Currency>
        <Subshop>B2c,B2B</Subshop>
        <Type>0</Type>
        <Type2>1</Type2>
        <VATIndex>-1</VATIndex>
        <VoucherNumbers>
        <VoucherNumber>1234-1234-1234-1234</VoucherNumber>
        <VoucherNumber>1235-1235-1235-1235</VoucherNumber>
        </VoucherNumbers>
      </response>
    </ns:CreateVouchersResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieving information about voucher batches

This function is used to call up a list of the available batches and the associated data.
The generation and retrieval of vouchers takes place in two steps

the external system sends the request with the voucher data
return of the voucher data by the WEBSALE system

Sending the Request by the External System (Step 1, "GetVoucherCharges")

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
MsgID	Optionally, the external system can specify an MsgID, which is returned by the WEBSALE system in the response. The MsgID has no meaning for processing the request.	No
ChargeType	Optional, can contain the values "all" and "template" (default). If the value "all" is passed here, then all voucher batches are returned. The value "template" corresponds to the default behavior, only batches containing templates are returned.	No

Example of a GetVoucherCharges 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:GetVoucherCharges>   
      <request>    
        <ShopID>TestShop</ShopID>    
        <Password>geheim</Password>    
        <MsgID>123</MsgID>   
      </request>  
    </ns:GetVoucherCharges> 
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherChargesResponse")

Parameter	Superior element	Description	Required field
MsgID		The MsgID transferred in the request	No
ChargeList		Contains a "ChargeData" sub-element for each batch.	Yes
ChargeData	ChargeList	Contains the data of a single batch.	No
ChargeId	ChargeData	The ID of the batch	No
Amount	ChargeData	See "CreateVouchers" Request	Yes
AmountType	ChargeData		Yes
Currency	ChargeData		Yes
MinOrderValue	ChargeData		No
SubscribeSubshopID	ChargeData		No
Subshop	ChargeData		No
Type	ChargeData		Yes
Type2	ChargeData		Yes
ValidFrom	ChargeData		No
ValidUntil	ChargeData		No
VATIndex	ChargeData		Yes
ValidFromDays	ChargeData	This element can be supplied as an alternative to ValidFrom. For voucher templates, you can specify after how many days (from the generation time) a generated voucher should be valid.	No
ValidUntilDays	ChargeData	This element can be supplied as an alternative to ValidUntil. For voucher templates, you can specify here how many days (from the generation time) a generated voucher should be valid.	No

Example of a response to a GetVoucherCharges 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:GetVoucherChargesResponse>
   <response>
    <MsgID>123</MsgID>
    <ChargeList>
     <ChargeData>
      <ChargeId>Charge1</ChargeId>
      <Amount>10.0</Amount>
      <AmountType>0</AmountType>
      <Currency>EUR</Currency>
      <Type>0</Type>
      <Type2>1</Type2>
     </ChargeData>
     <ChargeData>
      <ChargeId>Charge2</ChargeId>
      <Amount>5.0</Amount>
      <AmountType>0</AmountType>
      <Currency>EUR</Currency>
      <MinOrderValue>50.00</MinOrderValue>
      <Subshop>Subshop1</Subshop>
      <Type>0</Type>
      <Type2>1</Type2>
     </ChargeData>
    </ChargeList>
   </response>
  </ns:GetVoucherChargesResponse>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieving information about a specific voucher batch

Requirements

In addition to the ShopID and the password, the external system must also transfer the ChargeId with this call.

Sending the Request by the External System (Step 1, "GetVoucherCodes-Request")

Parameter	Description	Required field
ShopID	The Shop-ID	Yes
Password	The password for the SOAP interface. The password can be obtained from WEBSALE AG.	Yes
MsgID	Optionally, the external system can enter an MsgID, which the WEBSALE system has entered in the response is returned. For processing the request the MsgID has no meaning.	No
ChargeId	The ID of the batch from which the data of the voucher (code) should be transferred.	Yes
PageSize	Determines the number of voucher codes per request (maximum and default value is 1000).	No
NextPageToken	If the number of codes is greater than 1000, Response only sends the first 1000 codes (sorted alphabetically) and the NextPageToken parameter. To get the next 1000 codes, another request must be executed, in this request NextPageToken of Response is a required parameter.	No

Example of a GetVoucherCodes request

Get VoucherCodes with ChargeId "testid3", 10 entries per 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:GetVoucherCodes>
   <request>
    <ShopID>TestShop</ShopID>
    <Password>geheim</Password>
    <ChargeId>testid3</ChargeId>
    <MsgID>123</MsgID>
    <PageSize>10</PageSize>
   </request>
  </ns:GetVoucherCodes>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherCodes-Response")

Parameter	Description	Required field
MsgID	As an option, the external system can specify an MsgID, which the WEBSALE system uses in the response is returned. For processing the request the MsgID has no meaning.	No
VoucherList	Contains a "VoucherData" sub-element for each code.	Yes
VoucherData	Contains the data of a single charge	Yes
Num	The value given in the request or determined from the template-batch.	Yes
Amount		Yes
AmountType		Yes
Currency		Yes
MinOrderValue		No
Subshop		No
Type		Yes
Type2		Yes
ValidFrom		No
ValidUntil		No
VATIndex		Yes
CustomerFilter		No
CatProdFilterSetBehavior		No
CatProdFilter		No
AmountMultiCurrency		No
MinOrderValueMultiCurrency		No
MaxDiscountValueMultiCurrency		No
ChargeLabel		No
NextPageToken	If the number of codes is greater than 1000, Response sends only the first 1000 codes (sorted alphabetically) and the NextPageToken parameter. To get the next 1000 codes, another request must be executed; NextPageToken is a required parameter in this request.	No
LastPage	Value: true/false (This parameter shows whether all codes have been sent)	Yes

Example of a response to a GetVoucherCodes 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:GetVoucherCodesResponse>
      <response>
        <MsgID>123</MsgID>
        <VoucherList>
          <VoucherData>
            <Num>1CM1-CBAK-B96N-P7Z9</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
          <VoucherData>
            <Num>2PT6-QQ8S-UY93-3Z5G</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
        </VoucherList>
        <NextPageToken></NextPageToken>
        <LastPage>true</LastPage>
      </response>
    </ns:GetVoucherCodesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example for NextPageToken

a) Request 1 - Get VoucherCodes with ChargeId testid3, 2 entries per request (there are a total of 5 entries in the database):

<?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:GetVoucherCodes>
   <request>
    <ShopID>TestShop</ShopID>
    <Password>secret</Password>
    <ChargeId>testid3</ChargeId>
    <MsgID>123</MsgID>
    <PageSize>2</PageSize>
   </request>
  </ns:GetVoucherCodes>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

b) Response 1 - first 2 entries from the database (sorted alphabetically) and NextPageToken (the token must be passed in the next request), parameter LastPage is false, because we still have 3 entries.

<?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:GetVoucherCodesResponse>
      <response>
        <MsgID>123</MsgID>
         <VoucherList>
          <VoucherData>
            <Num>ACM1-CBAK-B96N-P7Z9</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>          			     
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
          <VoucherData>
            <Num>BPT6-QQ8S-UY93-3Z5G</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
        </VoucherList>
        <NextPageToken>a123456789</NextPageToken>
        <LastPage>false</LastPage>
      </response>
    </ns:GetVoucherCodesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

c) Request 2 - next 2 entries from the database, NextPageToken from the last response must be transferred.

<?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:GetVoucherCodes>
   <request>
    <ShopID>TestShop</ShopID>
    <Password>secret</Password>
    <ChargeId>testid3</ChargeId>
    <MsgID>123</MsgID>
    <PageSize>2</PageSize>
    <NextPageToken>a123456789</NextPageToken>
   </request>
  </ns:GetVoucherCodes>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

d) Response 2 - Other 2 entries from the database, and NextPageToken, LastPage is still false because there is still 1 entry.

<?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:GetVoucherCodesResponse>
      <response>
        <MsgID>123</MsgID>
         <VoucherList>
          <VoucherData>
            <Num>G4F1-CBAK-B96N-P7Z9</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
          <VoucherData>
            <Num>Z1L1-QQ8S-UY93-3Z5G</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
        </VoucherList>
        <NextPageToken>b123456789</NextPageToken>
        <LastPage>false</LastPage>
      </response>
    </ns:GetVoucherCodesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

e) Request 3 - last entries from the database.

<?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:GetVoucherCodes>
   <request>
    <ShopID>TestShop</ShopID>
    <Password>geheim</Password>
    <ChargeId>testid3</ChargeId>
    <MsgID>123</MsgID>
    <PageSize>2</PageSize>
    <NextPageToken>b123456789</NextPageToken>
   </request>
  </ns:GetVoucherCodes>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

f) Response 3 - 1 last entry, NextPageToken parameter is empty and LastPage is true because all entries were sent.

<?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:GetVoucherCodesResponse>
      <response>
        <MsgID>123</MsgID>
         <VoucherList>
          <VoucherData>
            <Num>Z256-CBAK-B96N-P7Z9</Num>
            <Amount>10</Amount>
            <AmountType>0</AmountType>
            <Currency>EUR</Currency>
            <MinOrderValue>6</MinOrderValue>
            <Subshop></Subshop>
            <Type>0</Type>
            <Type2>2</Type2>
            <ValidFrom>2019-11-13</ValidFrom>
            <ValidUntil>2019-12-31</ValidUntil>
            <VATIndex>-1</VATIndex>
            <MaxDiscountValue>0</MaxDiscountValue>
            <CustomerFilter></CustomerFilter>
            <CatProdFilterSetBehavior>0</CatProdFilterSetBehavior>          			     
            <CatProdFilter></CatProdFilter>
            <AmountMultiCurrency></AmountMultiCurrency>
            <MinOrderValueMultiCurrency></MinOrderValueMultiCurrency>
            <MaxDiscountValueMultiCurrency></MaxDiscountValueMultiCurrency>
            <ChargeLabel></ChargeLabel>
          </VoucherData>
        </VoucherList>
        <NextPageToken></NextPageToken>
        <LastPage>true</LastPage>
      </response>
    </ns:GetVoucherCodesResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Accessing information via the Voucher-Pool

The "voucher pool" contains voucher numbers or voucher data that were not generated by the WEBSALE voucher generator, but are generated by an external system "in stock".

The external system sends the request (Step 1, "GetVoucherPoolInfo")

Parameter	Description	Required field
ShopID	The ID of the Shop	Yes
Password	The password for the SOAP interface. The password is obtained from WEBSALE AG.	Yes
MsgID	Optionally, the external system can specify an MsgID, which is returned by the WEBSALE system in the response. The MsgID has no effect on the processing of the request.	No
ChargeId	The ID of the batch whose number is to be returned.	Yes
ChargeType	Optional, can contain the values "all" and "template" (default). If the value "all" is passed here, then all voucher batches are returned. The value "template" corresponds to the default behavior: only batches containing templates are returned.	No
SubShopValidity	If a subshop ID is transferred in this field, the number of vouchers in the batch that can be redeemed in this subshop is returned. (Specifying this field only makes sense if there are vouchers within a batch that can be redeemed for different subshops, which is not recommended.)	No

Example of a GetVoucherPoolInfo request

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAPENC="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:GetVoucherPoolInfo>
      <request>
        <ShopID>TestShop</ShopID>
        <Password>secret</Password>
        <MsgID>123</MsgID>
      </request>
    </ns:GetVoucherPoolInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherPoolInfoResponse")

Parameter	Superior element	Description	Required field
MsgID		The MsgID given in the request	No
VoucherCount		Contains the number of available vouchers in the voucher pool	Yes

Example of a response to a GetVoucherPoolInfo 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:GetVoucherPoolInfoResponse>
      <response>  
        <MsgID>123</MsgID>
        <VoucherCount>99999</VoucherCount>  
      </response>
    </ns:GetVoucherPoolInfoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Retrieving information about a specific voucher batch

The external system sends the request (Step 1, “GetVoucherChargeInfo”)

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
MsgID	Optionally, the external system can specify an MsgID, which is returned by the WEBSALE system in the response. The MsgID has no effect on the processing of the request.	no
ChargeId	The ID of the batch to be queried.	yes

Example of a GetVoucherChargeInfo 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:GetVoucherChargeInfo>
      <request>
        <ShopID>TestShop</ShopID>
        <Password>geheim</Password>
        <MsgID>123</MsgID>
        <ChargeId>TestCharge</ChargeId>
      </request>
    </ns:GetVoucherChargeInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherChargeInfoResponse")

Parameter	Description	Required field
MsgID	The MsgID transferred in the request	no
VoucherCount	Contains the number of vouchers in the batch.	yes
HasTemplate	true: The batch contains a template that can be used when calling CreateVouchers.	yes

Example of a response to a GetVoucherChargeInfo 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:GetVoucherChargeInfoResponse>
   <response>
    <MsgID>123</MsgID>
    <VoucherCount>88888</VoucherCount>
    <HasTemplate>false</HasTemplate>
   </response>
  </ns:GetVoucherChargeInfoResponse>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Error handling

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

Error code	Description
ES001 Missing ShopID or Password	In the request the parameter "ShopID" or the parameter "Password" is missing. For security reasons the error is not specified.
ES002 Invalid ShopID or invalid password	The request contains ShopID and Password, but there is no suitable Shop, the password is false, or the interface is not activated for the Shop. For security reasons the error is not specified.
ES005 Server error- initialization	When the SOAP server was initialized an error occurred. Try again later. If the error lasts longer than 30 minutes, contact WEBSALE AG.
ES007 SSL required	The program must be accessed over a secure connection. Access via a normal "http" URL is not allowed.
ES008 Wrong Shop version	The SOAP interface for the V8 version is accessed, but there is no V8 Shop.
ES009 Missing required field xxx	The required field xxx is missing or empty in the request.
ES012 Format error	A field for which a certain format is specified (e.g. Date or Time) has a wrong structure.
ES015 Invalid request	The SOAP framework could not process the incoming request.
ES017 Max. VoucherCount value (1000) exceeded	More than the maximum allowed 1,000 vouchers are requested in the request
ES018 ChargeId already exists	A voucher batch that is newly created already exists
ES019 ChargeId does not exist	A voucher batch to be used as a template does not exist
ES020 Batch does not contain a template	A voucher batch that is to be used as a template exists but contains no template
ES021 Invalid value	A field that is only allowed for specific values (Type) or only values from a certain range of values (e.g. Amount) contains an invalid value
ES022 Invalid subshop for registration voucher	There is no registration voucher for the specified subshop.
ES023 CreateCharge/ SubscribeVoucher and Pool cannot be active at the same time	If vouchers are to be withdrawn from the pool, no new batch can be created.
ES024 Unsufficient number of vouchers in the pool (25)	The number of vouchers available in the pool is less than the number of vouchers requested (25)
ES026 CreateNextPageToken failed	NextPageToken cannot be generated. The reason for this is usually an invalid NextPageToken.
ES027 ParseNextPageToken failed	ParseNextPageToken is not possible. The reason for this is usually an invalid NextPageToken.
ES028 ChargeId does not exist in database.	ChargeId does not exist in database.
ES029 ChargeId missing.	ChargeId does not exist in Request
ES030 Token is invalid	Token has been parsed, but is invalid.

Example for 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>

WSDL file

On the subordinate page you will find the WSDL file "createvouchers.wsdl", which you can use to automatically create the code for connecting the interface. The prerequisite for this is that there is a suitable tool for the programming language you use to read in the WSDLs.

URL of the SOAP servers

For V8 Shops, the URL of the SOAP server is currently:

https://soap-toshop.websale.net/createvouchers

Please note that this URL may change in the future. So make sure that you can change it without much effort.

Copy of SOAP-based interface for the creation and retrieval of vouchers

General

Exclusively encrypted retrieval

UTF-8 encoding

Requirements

Generation and retrieval of vouchers

The external system sends the request (Step 1,"CreateVouchers")

Example of a CreateVouchers request

Transfer of the response by the WEBSALE system (Step 2, "CreateVouchersResponse")

Example of an answer to a CreateVouchers request

Retrieving information about voucher batches

Sending the Request by the External System (Step 1, "GetVoucherCharges")

Example of a GetVoucherCharges request

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherChargesResponse")

Example of a response to a GetVoucherCharges request

Retrieving information about a specific voucher batch

Requirements

Sending the Request by the External System (Step 1, "GetVoucherCodes-Request")

Example of a GetVoucherCodes request

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherCodes-Response")

Example of a response to a GetVoucherCodes request

Example for NextPageToken

Accessing information via the Voucher-Pool

The external system sends the request (Step 1, "GetVoucherPoolInfo")

Example of a GetVoucherPoolInfo request

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherPoolInfoResponse")

Example of a response to a GetVoucherPoolInfo request

Retrieving information about a specific voucher batch

The external system sends the request (Step 1, “GetVoucherChargeInfo”)

Example of a GetVoucherChargeInfo Request

Transfer of the response by the WEBSALE system (Step 2, "GetVoucherChargeInfoResponse")

Example of a response to a GetVoucherChargeInfo request

Error handling

Example for a "SOAP fault"

WSDL file

URL of the SOAP servers