WS-SOAP-Gutscheine erzeugen (DE)
- René Meyer
- Rainer Biedermann
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
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:
Übergabe der Antwort durch das WEBSALE-System (Schritt 2, “GetVoucherCodes-Response”)
Parameter | Übergeordnetes Element | Beschreibung | Pflicht-feld |
|---|---|---|---|
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 |
VoucherList |
| Enthält für jeden Code ein „VoucherData“ Unterelement | ja |
VoucherData | VoucherList | Enthält die Daten einer einzelnen Charge | ja |
Num | VoucherData | Der im Request angegebene oder aus der Vorlagen-Charge ermittelte Wert.
| ja |
Amount | VoucherData | ja | |
AmountType | VoucherData | ja | |
Currency | VoucherData | ja | |
MinOrderValue | VoucherData | nein | |
Subshop | VoucherData | nein | |
Type | VoucherData | ja | |
Type2 | VoucherData | ja | |
ValidFrom | VoucherData | nein | |
ValidUntil | VoucherData | nein | |
VATIndex | VoucherData | ja | |
CustomerFilter | VoucherData | nein | |
CatProdFilterSetBehavior | VoucherData | nein | |
CatProdFilter | VoucherData | nein | |
AmountMultiCurrency | VoucherData | nein | |
MinOrderValueMultiCurrency | VoucherData | nein | |
MaxDiscountValueMultiCurrency | VoucherData | nein | |
ChargeLabel | VoucherData | nein | |
NextPageToken |
| Falls die Anzahl der Codes größer als 1000 ist, 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 ein obligatorischer Parameter. | nein |
LastPage |
| Wert: true/false (Dieser Parameter zeigt, ob alle Codes gesendet wurden) | ja |
Beispiel für eine Antwort auf einen GetVoucherCodes-Request
Beispiel für NextPageToken
a) Request 1 – Get VoucherCodes mit ChargeId “testid3”, 2 Einträge pro Request (es gibt insgesamt 5 Einträge in der DB):
b) Response 1 – erste 2 Einträge aus der DB (alphabetisch sortiert) und NextPageToken (der Token muss in nächstem Request übergeben werden), Parameter “LastPage” ist “false”, weil wir noch 3 Einträge haben.
c) Request 2 – nächste 2 Einträge aus der DB, NextPageToken vom letzten Response muss übergeben werden.
d) Response 2 – Andere 2 Einträge aus der DB, und NextPageToken, “LastPage” ist immer noch “false”, weil es noch 1 Eintrag gibt.
e) Request 3 – letzte Einträge aus der DB
f) Response 3 – 1 letzter Eintrag, NextPageToken Parameter ist leer und “LastPage” ist “true”, weil alle Einträge geschickt wurden.
Abruf von Informationen über den Gutschein-Pool
Der „Gutschein-Pool“ enthält Gutscheinnummern bzw. Gutscheindaten, die nicht vom WEBSALE-Gutscheingenerator erzeugt wurden, sondern von einem externen System „auf Vorrat“ generiert werden.
Voraussetzung
Das externe System muss bei jedem Aufruf neben der ShopID und dem Passwort auch die ChargeId übergeben.
Senden des Request durch das externe System (Schritt 1, „GetVoucherPoolInfo“)
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, deren Anzahl zurückgegeben werden soll. | ja |
ChargeType | Optional, kann die Werte "all" und "template" enthalten (Standard). Wird hier der Wert "all" übergeben, werden alle Gutscheinchargen zurückgegeben. Der Wert "template" entspricht dem Standardverhalten: Es werden nur Chargen mit Vorlagen zurückgegeben. | nein |
SubShopValidity | Wird in diesem Feld eine Subshop-ID übergeben, so wird die Anzahl der Gutscheine in der Charge zurückgegeben, die sich in diesem Subshop einlösen lassen. (Die Angabe dieses Feldes ist nur sinnvoll, wenn es innerhalb einer Charge Gutscheine gibt, die für unterschiedliche Subshops einlösbar sind, was nicht empfohlen wird) | nein |
Beispiel für einen GetVoucherPoolInfo-Request
Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „GetVoucherPoolInfoResponse“)
Parameter | Beschreibung | Pflichtfeld |
|---|---|---|
MsgID | Die im Request übergebene MsgID | nein |
VoucherCount | Enthält die Anzahl der verfügbaren Gutscheine im Gutschein-Pool | ja |
Beispiel für eine Antwort auf einen GetVoucherPoolInfo-Request
Abruf von Informationen über eine bestimmte Gutschein-Charge
Voraussetzung
Das externe System muss bei jedem Aufruf neben der ShopID und dem Passwort auch die ChargeId übergeben.
Senden des Request durch das externe System (Schritt 1, „GetVoucherChargeInfo“)
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, die abgefragt werden soll. | ja |
Beispiel für einen GetVoucherChargeInfo-Request
Übergabe der Antwort durch das WEBSALE-System (Schritt 2, „GetVoucherChargeInfoResponse“)
Parameter | Beschreibung | Pflichtfeld |
|---|---|---|
MsgID | Die im Request übergebene MsgID | nein |
VoucherCount | Enthält die Anzahl der Gutscheine der Charge | ja |
HasTemplate | true: Die Charge enthält eine Vorlage, die beim Aufruf von CreateVouchers verwendet werden kann | ja |
Beispiel für eine Antwort auf einen GetVoucherChargeInfo-Request
Fehlerbehandlung
Tritt ein Fehler auf, so gibt die Schnittstelle einen „SOAP Fault“ zurück. Folgende Fehler können auftreten:
Fehlermeldung | Beschreibung |
|---|---|
ES001 Fehlende ShopID oder Passwort | In dem Request fehlt der Parameter „ShopID“ oder der Parameter „Password“. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert. |
ES002 Ungültige ShopID oder ungültiges Passwort | Der Request enthielt zwar „ShopID“ und „Password“, aber es existiert kein passender Shop, das Passwort ist falsch oder die Schnittstelle ist für den Shop gar nicht freigeschaltet. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert. |
ES005 Fehler bei Server-Initialisierung | Bei der Initialisierung des SOAP-Servers trat ein Fehler auf. Versuchen Sie es später nochmal. Sofern der Fehler länger als 30 Minuten anhält, setzen Sie sich mit der WEBSALE AG in Verbindung. |
ES007 SSL erforderlich | Der Aufruf des Programms muss über eine verschlüsselte Verbindung erfolgen. Ein Aufruf mit einer normalen “http”-URL ist nicht zulässig. |
ES008 Falsche Shop-Version | Es wurde das SOAP-Interface für die V8-Version eines Shops aufgerufen, aber es existiert kein V8-Shop. |
ES009 Fehlendes Pflichtfeld xxx | Das Pflichtfeld xxx in dem Request fehlt oder ist leer. |
ES012 Formatfehler | Ein Feld, für das ein bestimmtes Format vorgegeben ist (z. B. Date oder Time), hat einen falschen Aufbau. |
ES015 Ungültiger Request | Das SOAP-Framework konnte den eingehenden Request nicht verarbeiten. |
ES017 Max. VoucherCount-Wert (1000) überschritten | In dem Request wurden mehr als die maximal zulässigen 1000 Gutscheine angefordert |
ES018 ChargeId existiert bereits | Eine Gutschein-Charge, die neu angelegt werden sollte, existiert bereits |
ES019 ChargeId existiert nicht | Eine Gutschein-Charge, die als Vorlage verwendet werden sollte, existiert nicht |
ES020 Charge enthält keine Vorlage | Eine Gutschein-Charge, die als Vorlage verwendet werden sollte, existiert zwar, enthält aber keine Vorlage |
ES021 Ungültiger Wert | Ein Feld, für das nur bestimmte Werte zugelassen sind (Type), oder nur Werte aus einem bestimmten Wertebereich, (z.B. Amount), enthält einen ungültigen Wert |
ES022 Ungültiger Subshop für Anmeldegutschein | Für den angegebenen Subshop existiert kein Anmeldegutschein |
ES023 CreateCharge/ SubscribeVoucher und Pool können nicht gleichzeitig aktiv sein | Wenn Gutscheine aus dem Pool entnommen werden sollen, so kann keine neue Charge angelegt werden |
ES024 Ungenügende Zahl von Gutscheinen im Pool (25) | Die Zahl der im Pool vorhandenen Gutscheine ist kleiner als die Zahl der Gutscheine, die angefordert wurde (25) |
ES026 CreateNextPageToken failed | NextPageToken kann nicht generiert werden. Grund dafür ist meistens ein ungültiger NextPageToken. |
ES027 ParseNextPageToken failed | ParseNextPageToken ist nicht möglich. Grund dafür ist meistens ein ungültiger NextPageToken. |
ES028 ChargeId existiert nicht in DB. | ChargeId existiert nicht in DB. |
ES029 ChargeId fehlt. | ChargeId ist nicht vorhanden in Request. |
ES030 Token ist ungültig. | Token wurde geparst, aber ist ungültig. |
Beispiel für einen „SOAP-Fault“
WSDL-Datei
Auf der untergeordneten Seite finden Sie die WSDL-Datei „createvouchers.wsdl”, die Sie nutzen können, um den Code zur Anbindung der Schnittstelle automatisiert zu erstellen. Voraussetzung dafür ist, dass es für die von Ihnen verwendete Programmiersprache ein passendes Tool gibt, um die WSDLs einzulesen.
URL des SOAP-Servers
Für V8-Shops lautet die URL des SOAP-Servers derzeit:
https://soap-toshop.websale.net/createvouchers
Bitte beachten Sie, dass sich diese URL in Zukunft ändern kann. Stellen Sie also sicher, dass sie sich diese ohne größeren Aufwand bei Ihnen ändern lässt.