WS-SOAP-Gutscheine erzeugen (EN)
- Rainer Biedermann
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.
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.
Requirements
The external system must transfer the ShopID and password with every call.
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: -999999999Float 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: Example
| 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:
| 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: Example 2: | 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": Example 2, restriction to the products with the numbers "abc" and "xyz" | 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
Requirements
The external system must transfer the ShopID and password with every call.
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
Retrieve all information of a specific voucher batch
Requirements
The external system must transfer the ShopID, password and ChargeId for each call.
The external system sends the request (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:
Transfer of the response by the WEBSALE system (Step 2, "GetVoucherCodes-Response")
Parameter | Superior element | 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 | VoucherList | Contains the data of a single charge | Yes |
Num | VoucherData | The value given in the request or determined from the template-batch. | Yes |
Amount | VoucherData | Yes | |
AmountType | VoucherData | Yes | |
Currency | VoucherData | Yes | |
MinOrderValue | VoucherData | No | |
Subshop | VoucherData | No | |
Type | VoucherData | Yes | |
Type2 | VoucherData | Yes | |
ValidFrom | VoucherData | No | |
ValidUntil | VoucherData | No | |
VATIndex | VoucherData | Yes | |
CustomerFilter | VoucherData | No | |
CatProdFilterSetBehavior | VoucherData | No | |
CatProdFilter | VoucherData | No | |
AmountMultiCurrency | VoucherData | No | |
MinOrderValueMultiCurrency | VoucherData | No | |
MaxDiscountValueMultiCurrency | VoucherData | No | |
ChargeLabel | VoucherData | 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
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):
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.
c) Request 2 - next 2 entries from the database, NextPageToken from the last response must be transferred.
d) Response 2 - Other 2 entries from the database, and NextPageToken, LastPage is still false because there is still 1 entry.
e) Request 3 - last entries from the database.
f) Response 3 - 1 last entry, NextPageToken parameter is empty and LastPage is true because all entries were sent.
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".
Requirements
The external system must transfer the ShopID, password and ChargeId for each call.
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
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
Retrieving information about a specific voucher batch
Requirements
The external system must transfer the ShopID, password and ChargeId for each call.
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
Transfer of the response by the WEBSALE system (Step 2, "GetVoucherChargeInfoResponse")
Parameter | Superior element | 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
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"
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.