WS-SOAP-Gutscheine erzeugen (DE)
Allgemeines
Diese Dokumentation beschreibt die SOAP-basierte Schnittstelle zum Generieren und Abrufen von Gutscheinen durch ein externes System.
Eine Anwendung wäre das Anbinden von Drittsystemen, z. B. Kassensystemen.
Ausschließlich verschlüsselter Abruf
Der Webservice muss über SSL aufgerufen werden. Unverschlüsselte Verbindungen werden abgelehnt.
UTF-8 Codierung
Alle Daten müssen im UTF-8 Format gesendet werden.
Generieren und Abrufen von Gutscheinen
Das Generieren und Abrufen von Gutscheinen erfolgt in zwei Schritten:
Senden des Request mit den Daten der Gutscheine durch das externe System
Rückgabe der Gutscheindaten durch das WEBSALE-System
Voraussetzung
Das externe System muss bei jedem Aufruf die ShopID und das Passwort übergeben.
Senden des Request durch das externe System (Schritt 1, „CreateVouchers“)
Bei diesem Request übergibt das externe System die Daten der Gutscheine bzw. die ID der Vorlagen-Charge aus der die Gutscheindaten übernommen werden sollen, sowie die Anzahl der Gutscheine, die generiert werden sollen.
Werden Gutscheindatenfelder nicht explizit in dem Request übergeben, so werden sie aus der angegebenen Vorlagen-Charge übernommen. Fehlt z. B. das Feld „Amount“ mit dem Wert des Gutscheins in dem Request, so wird für die Generierung der Wert des Gutscheins verwendet, der bei der angegebenen Charge eingetragen ist.
Wenn es nicht möglich ist, ein Feld komplett aus dem Request zu entfernen, aber dennoch der entsprechende Wert der Charge verwendet werden soll, so kann dies erreicht werden, indem die folgenden Spezialwerte als Feldwert übergeben werden:
String-Werte: $ChargeVal$Integer-Werte: -999999999Float-Werte: -999999999 oder kleiner
Die für die Generierung verwendete Vorlagen-Charge selbst muss mit dem Gutscheingenerator im Online-Servicebereich angelegt werden.
Wenn das Flag „SubscribeVoucher“ gesetzt ist, so werden Gutscheine generiert, die dafür gedacht sind, bei einer Newsletter-Anmeldung verschickt zu werden. In diesem Fall ist es nicht nötig, eine Chargen-ID anzugeben, denn die Daten werden in diesem Fall von einem speziellen „Anmeldegutschein“ übernommen, der für diesen Zweck im Online-Servicebereich angelegt werden muss. Statt der Chargen-ID muss der Request die ID des Subshops enthalten, in dem die Anmeldung zum Newsletter erfolgte.
Parameter | Beschreibung | Pflichtfeld |
|---|---|---|
ShopID | Die Shop-ID | ja |
Password | Das Passwort für die SOAP-Schnittstelle. Das Passwort erhalten Sie von der WEBSALE AG. | ja |
MsgID | Optional kann das externe System eine MsgID mitgeben, die vom WEBSALE-System in der Antwort zurückgegeben wird. Für die Verarbeitung des Requests hat die MsgID keine Bedeutung. | nein |
VoucherCount | Die Anzahl der Gutscheine, die generiert werden soll. Pro Aufruf ist diese Anzahl auf maximal 1000 beschränkt. | ja |
SubscribeVoucher | „true“: Es wird ein „Anmeldegutschein“ generiert, das Feld „ChargeId“ wird ignoriert und stattdessen das Feld „SubscribeSubshopID“ verwendet. Default-Wert: false | nein |
SubscribeSubshopID | Im Fall SubscribeVoucher = true muss hier die ID des Subshops eingetragen werden, in der die Anmeldung zu dem Newsletter erfolgte. | Bei Anmelde-gutscheinen |
ChargeId | Die ID der Vorlagen-Charge, aus der die Daten des Gutscheins übernommen werden sollen oder die ID der Charge, die angelegt werden soll. | ja, außer bei Anmelde-gutscheinen |
CreateCharge | „true“: Es wird eine neue Charge mit der unter ChargeId angegebenen ID angelegt. „false“: Die unter ChargeId angegebene Charge wird verwendet, um die Daten der zu generierenden Gutscheine zu bestimmen. Die generierten Gutscheine werden dieser Charge hinzugefügt. Default-Wert: false | nein |
Amount | Der Betrag des Gutscheins z.B. „25.50“ | nein |
AmountType | 0: Amount enthält einen absoluten Betrag 1: Amount enthält einen Prozentsatz 2: Amount enthält einen prozentualen und gedeckelten Wert. Dieser Typ kann nur für Set-Unterartikel verwendet werden. Die Produktnummern bzw. -indizes dieser Set-Unterartikel müssen im Feld CatProdFilter geliefert werden. Gesamtsumme der Position wird (unabhängig von der Menge) auf den im Feld Amount/AmountMultiCurrency angegebenen Betrag gedeckelt. Bei Gutscheinen mit diesem Typ kann kein „normaler“ Maximalbetrag angegeben werden. Default-Wert: 0 | nein |
AmountMultiCurrency | Dieses Feld wird bei MultiCurrency-Gutscheinen statt Amount verwendet. Bei einem MultiCurrency-Gutschein wird der Betrag des Gutscheins in mehreren Währungen angegeben. Format: Bsp: | nein |
Currency | Die Währung der Gutscheine, z.B. „EUR“ | nein |
MinOrderValue | Mindestbestellwert, ab dem der Gutschein eingelöst werden kann. | nein |
MinOrderValueMultiCurrency | Dieses Feld wird bei MultiCurrency-Gutscheinen statt MinOrderValue verwendet. Format: | nein |
MaxDiscountValue | Nur bei prozentualem Rabatt: Der maximale Wert des Gutscheins, der eingelöst werden kann | nein |
MaxDiscountValueMultiCurrency | Nur bei prozentualem Rabatt: Der maximale Wert des Gutscheins, der eingelöst werden kann | nein |
Subshop | Subshops, für die der Gutschein gelten soll. Bleibt dieses Feld leer, so kann der Gutschein in allen Subshops eingelöst werden. Es können mehrere Subshops in einer kommagetrennten Liste angegeben werden. | nein |
Type | Der Typ der Gutscheine. Folgende Typen werden unterstützt: 0: Restbetrag kann wiederverwendet werden 1: Restbetrag verfällt 2: Universalgutschein 3: Universalgutschein (kundenspezifisch) 4: Universalgutschein (nur für Neukunden) 5: Restbetrag kann wiederverwendet werden (nur für Neukunden) 6: Restbetrag verfällt (nur für Neukunden) 7: Individueller Mehrfachgutschein (mit automatischer Kundenbindung, d.h. sobald ein Kunde den Gutschein eingelöst hat, kann nur noch dieser Kunde ihn einlösen, das aber beliebig oft) Default-Wert: 0 | nein |
Type2 | Werbegutschein/Kaufgutschein 1: Werbegutschein 2: Kaufgutschein Default-Wert: 1 | nein |
ValidFrom | Datum, ab dem der Gutschein gültig ist, im Format „YYYY-MM-DD“, z.B. „2018-06-30“ | nein |
ValidUntil | Datum, bis zu dem der Gutschein gültig ist im Format „YYYY-MM-DD“ | nein |
VATIndex | Die MwSt-Kennung der Gutscheine. Es muss dies entweder einer der in der shop.config unter "<VATRates>" konfigurierten Werte sein oder einer der Spezialwerte "-1" oder "0". "-1" bedeutet "Standard", für den Gutschein wird in diesem Fall die unter DeliveryVATRate konfigurierte Kennung verwendet. "0" steht für "Keine Mehrwertsteuer". Default-Wert: -1 | nein |
Pool | „true“: Die Gutscheinnummer wird aus einem vorhandenen Gutschein-Pool genommen und aktiv geschaltet. Der Gutschein-Pool wird über eine Import-Datei verwaltet. Wenn für Pool „true“ übermittelt wird, so schließt das die Verwendung von CreateCharge und SubscribeVoucher aus. „false“: Die Gutscheinnummer wird neu generiert. Default-Wert: „false“ | nein |
SubShopValidity | Wird in diesem Feld eine Subshop-ID übergeben, so werden nur Gutscheine aus dem Pool zurückgegeben, die sich in diesem Subshop einlösen lassen. (Die Angabe dieses Feldes ist nur beim Abruf von Pool-Gutscheinen sinnvoll, wenn es innerhalb einer Charge Gutscheine gibt, die für unterschiedliche Subshops einlösbar sind, was nicht empfohlen wird) | nein |
CustomerFilter | Einschränkung der Gültigkeit auf bestimmte Kunden. Die Kunden können entweder über den Userindex (<i></i>) oder über die Kundennummer (<n></n>) identifiziert werden. Es können entweder Userindizes oder Kundennummern für einen Gutschein verwendet werden, aber nicht beides gleichzeitig. Beispiel 2: | nein |
CatProdFilterSetBehavior | 0: Produktnummer bzw. -index des Oberprodukts bestimmt, ob der Gutschein für einen Setartikel verwendet wird. 1: Produktnummer bzw. -index der Unterprodukte bestimmen, ob der Gutschein für einen Setartikel verwendet wird. Default-Wert: 0 | nein |
CatProdFilter | Mit diesem Feld kann die Gültigkeit des Gutscheins auf bestimmte Produkte oder Kategorien beschränkt werden. Die Beschränkung kann durch die Angabe von Kategorieindizes (<ci></ci>), Produktindizes (<pi></pi>) oder Produktnummern (<pn></pn>) erfolgen. Beispiel 1, Beschränkung auf die Kategorien mit den Indizes „543“ und „345“: Beispiel 2, Beschränkung auf die Produkte mit den Nummern „abc“ und „xyz“ | nein |
ChargeDescr | Beschreibung der Charge, so wie sie im Online-Servicebereich angezeigt wird | nein |
ChargeLabel | „Label“ des Gutscheins, das in den Bestelldaten mit übergeben wird und für Auswertungen durch nachgelagerte Systeme genutzt werden kann. | nein |
Beispiel für einen 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>geheim</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>Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „CreateVouchersResponse“)
Als Antwort übermittelt das WEBSALE-System die für die Generierung verwendeten Gutscheindaten (unabhängig davon, ob sie im Request explizit übergeben oder aus einer Vorlagen-Charge gelesen wurden).
Parameter | Übergeordnetes | Beschreibung | Pflichtfeld |
|---|---|---|---|
MsgID |
| Die im Request übergebene MsgID | nein |
Amount | Der im Request angegebene oder aus der Vorlagen-Charge ermittelte Wert.
| ja | |
AmountType | ja | ||
Currency | ja | ||
MinOrderValue | nein | ||
Subshop | nein | ||
Type | ja | ||
Type2 | ja | ||
ValidFrom | nein | ||
ValidUntil | nein | ||
VATIndex | ja | ||
CustomerFilter | nein | ||
CatProdFilterSetBehavior | nein | ||
CatProdFilter | nein | ||
AmountMultiCurrency | nein | ||
MinOrderValueMultiCurrency | nein | ||
MaxDiscountValueMultiCurrency | nein | ||
VoucherNumbers |
| Enthält für jeden generierten Gutschein ein VoucherNumber-Element | ja |
VoucherNumber | VoucherNumbers | Enthält eine generierte Gutschein-Nummer | ja |
Beispiel für eine Antwort auf einen 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>Abrufen von Informationen über Gutschein-Chargen
Mit dieser Funktion lässt sich eine Liste der vorhandenen Chargen und der zugehörigen Daten abrufen. Das Generieren und Abrufen von Gutscheinen erfolgt in zwei Schritten
Senden des Request mit den Daten der Gutscheine durch das externe System
Rückgabe der Gutscheindaten durch das WEBSALE-System
Voraussetzung
Das externe System muss bei jedem Aufruf die ShopID und das Passwort übergeben.
Senden des Request durch das externe System (Schritt 1, „GetVoucherCharges“)
Parameter | Beschreibung | Pflichtfeld |
|---|---|---|
ShopID | Die Shop-ID | ja |
Password | Das Passwort für die SOAP-Schnittstelle. Das Passwort erhalten Sie von der WEBSALE AG. | ja |
MsgID | Optional kann das externe System eine MsgID mitgeben, die vom WEBSALE-System in der Antwort zurückgegeben wird. Für die Verarbeitung des Requests hat die MsgID keine Bedeutung. | nein |
ChargeType | Optional, kann die Werte „all“ und „template“ (default) enthalten. Wenn hier der Wert „all“ übergeben wird, dann werden alle Gutschein-Chargen zurückgegeben. | nein |
Beispiel für einen 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>Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „GetVoucherChargesResponse“)
Parameter | Übergeordnetes | Beschreibung | Pflichtfeld |
|---|---|---|---|
MsgID |
| Die im Request übergebene MsgID | nein |
ChargeList |
| Enthält für jede Charge ein „ChargeData“ Unterelement | ja |
ChargeData | ChargeList | Enthält die Daten einer einzelnen Charge | nein |
ChargeId | ChargeData | Die ID der Charge | nein |
Amount | ChargeData | Siehe „CreateVouchers“ Request | ja |
AmountType | ChargeData | ja | |
Currency | ChargeData | ja | |
MinOrderValue | ChargeData | nein | |
SubscribeSubshopID | ChargeData | nein | |
Subshop | ChargeData | nein | |
Type | ChargeData | ja | |
Type2 | ChargeData | ja | |
ValidFrom | ChargeData | nein | |
ValidUntil | ChargeData | nein | |
VATIndex | ChargeData | ja | |
ValidFromDays | ChargeData | Dieses Element kann alternativ zu ValidFrom geliefert werden. Bei Gutschein-Vorlagen kann hier angegeben werden, nach wie viel Tagen (ab dem Generierungszeitpunkt) ein generierter Gutschein gültig sein soll. | nein |
ValidUntilDays | ChargeData | Dieses Element kann alternativ zu ValidUntil geliefert werden. Bei Gutschein-Vorlagen kann hier angegeben werden, wie viele Tage (ab dem Generierungszeitpunkt) ein generierter Gutschein gültig sein soll. | nein |
Beispiel für eine Antwort auf einen 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>Abruf aller Informationen einer bestimmten Gutschein-Charge
Voraussetzung
Das externe System muss bei diesem Aufruf neben der ShopID und dem Passwort auch die ChargeId übergeben.
Senden des Request durch das externe System (Schritt 1, “GetVoucherCodes-Request”)
Parameter | Beschreibung | Pflichtfeld |
|---|---|---|
ShopID | Die Shop-ID | ja |
Password | Das Passwort für die SOAP-Schnittstelle. Das Passwort erhalten Sie von der WEBSALE AG. | ja |
MsgID | Optional kann das externe System eine MsgID mitgeben, die vom WEBSALE-System in der Antwort zurückgegeben wird. Für die Verarbeitung des Requests hat die MsgID keine Bedeutung. | nein |
ChargeId | Die ID der Charge, aus der die Daten des Gutscheins (Code) übernommen werden sollen. | ja |
PageSize | Bestimmt die Anzahl der Voucher-Codes pro Request (maximaler und Default-Wert ist 1000) | nein |
NextPageToken | Falls die Anzahl der Codes größer ist als 1000, sendet Response nur die ersten 1000 Codes (alphabetisch sortiert) und den Parameter NextPageToken. Um die nächsten 1000 Codes zu bekommen, muss ein weiterer Request ausgeführt werden, in diesem Request ist NextPageToken vom Response ein obligatorischer Parameter. | nein |
Beispiel für einen GetVoucherCodes-Request
GetVoucherCodes mit ChargeId „testid3“, 10 Einträge pro 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>