WS-SOAP-Gutscheine erzeugen

Diese Schnittstelle erzeugt und liest Gutscheine aus einem Drittsystem heraus, beispielsweise aus einem Kassensystem oder aus einer Filialanwendung. Anders als beim Dateiimport entstehen die Gutscheine hier im direkten Dialog und die Nummern kommen sofort zurück.

Eigenschaft	Wert
Übertragungsrichtung	Externes System ↔ WEBSALE Shop (bidirektional)
Übertragungsart	SOAP
Formate	XML, WSDL
Zeichensatz	UTF-8

Der Webservice ist ausschließlich über SSL erreichbar. Die Funktionen im Überblick:

Funktion	Wofür
`CreateVouchers`	Gutscheine generieren, auf Basis einer Vorlagen-Charge oder mit eigenen Werten
`GetVoucherCharges`	Liste der vorhandenen Chargen mit ihren Daten abrufen
`GetVoucherCodes`	Alle Codes einer bestimmten Charge abrufen, seitenweise
`GetVoucherChargeInfo`	Daten einer bestimmten Charge abrufen
`GetVoucherPoolInfo`	Anzahl der im Pool verfügbaren Gutscheine einer Charge abrufen

Jeder Aufruf übergibt ShopID und Password. Optional lässt sich eine MsgID mitgeben, die unverändert in der Antwort zurückkommt und beim Zuordnen in Protokollen hilft.

Das Prinzip der Vorlagen-Charge

Gutscheine entstehen nicht aus dem Nichts, sondern aus einer Vorlagen-Charge, die Sie zuvor mit dem Gutschein-Generator im Online-Servicebereich anlegen. Felder, die Sie im Request nicht übergeben, übernimmt der Shop aus dieser Charge. Fehlt beispielsweise Amount, gilt der in der Charge hinterlegte Betrag. Lässt sich ein Feld in Ihrem System nicht weglassen, Sie wollen aber trotzdem den Wert der Charge verwenden, übergeben Sie einen Spezialwert:

Feldtyp	Spezialwert
String	$ChargeVal$
Integer	`-999999999`
Float	`-999999999` oder kleiner

CreateVouchers

Pro Aufruf lassen sich maximal 1000 Gutscheine generieren.

Steuerung des Aufrufs

Parameter	Beschreibung	Pflichtfeld
`VoucherCount`	Anzahl der zu generierenden Gutscheine, höchstens 1000	ja
`ChargeId`	ID der Vorlagen-Charge oder der neu anzulegenden Charge	ja, außer bei Anmeldegutscheinen
`CreateCharge`	`true` legt eine neue Charge mit der angegebenen ID an, `false` verwendet die vorhandene Charge und fügt die Gutscheine hinzu. Standard ist `false`.	nein
`SubscribeVoucher`	`true` erzeugt einen Anmeldegutschein. `ChargeId` wird dann ignoriert. Standard ist `false`.	nein
`SubscribeSubshopID`	Bei Anmeldegutscheinen die ID des Subshops, in dem die Newsletter-Anmeldung erfolgte	bei Anmeldegutscheinen
`Pool`	`true` nimmt die Nummer aus einem vorhandenen Gutschein-Pool und schaltet sie aktiv, `false` generiert eine neue Nummer. Standard ist `false`.	nein
`SubShopValidity`	Liefert beim Abruf aus dem Pool nur Gutscheine zurück, die in diesem Subshop einlösbar sind	nein

Pool: true schließt CreateCharge und SubscribeVoucher aus. Die Kombination endet mit ES023. Anmeldegutscheine sind für den Versand bei einer Newsletter-Anmeldung gedacht. Ihre Daten stammen aus einem speziellen Anmeldegutschein, den Sie im Online-Servicebereich anlegen müssen.

Gutscheindaten

Diese Felder entsprechen denen des Dateiimports und sind unter WS-SFTP-Gutscheindaten (to-Shop) ausführlich beschrieben. Alle sind optional, weil sie sonst aus der Vorlagen-Charge kommen.

Parameter	Kurzbeschreibung	Standard
`Amount`	Betrag oder Prozentsatz, beispielsweise `25.50`
`AmountType`	`0` absoluter Betrag, `1` Prozentsatz, `2` prozentual und gedeckelt	`0`
`Currency`	Währung, beispielsweise `EUR`
`Type`	Gutscheintyp `0` bis `7`	`0`
`Type2`	`1` Werbegutschein, `2` Kaufgutschein	`1`
`MinOrderValue`	Mindestbestellwert
`MaxDiscountValue`	Nur bei prozentualem Rabatt: maximaler einlösbarer Wert
`ValidFrom`, `ValidUntil`	Gültigkeitszeitraum im Format `YYYY-MM-DD`
`VATIndex`	Mehrwertsteuerkennung, `-1` für Standard, `0` für keine	`-1`
`Subshop`	Kommagetrennte Liste der Subshops
`CustomerFilter`	Einschränkung auf Kunden über `<i></i>` oder `<n></n>`
`CatProdFilter`	Einschränkung auf Kategorien, Produktindizes oder Produktnummern
`CatProdFilterSetBehavior`	`0` Oberprodukt entscheidet, `1` Unterprodukte entscheiden	`0`
`ChargeDescr`	Beschreibung der Charge im Online-Servicebereich
`ChargeLabel`	Label, das in den Bestelldaten mitläuft

Für Gutscheine in mehreren Währungen treten AmountMultiCurrency, MinOrderValueMultiCurrency und MaxDiscountValueMultiCurrency an die Stelle ihrer einfachen Varianten, im Format <g><c>EUR</c><a>10.00</a></g>. Beim CustomerFilter dieser Schnittstelle gilt eine Einschränkung, die beim Dateiimport nicht besteht: Userindizes und Kundennummern lassen sich nicht mischen, Sie verwenden je Gutschein entweder <i> oder <n>.

Antwort

Die Antwort enthält die tatsächlich verwendeten Gutscheindaten, unabhängig davon, ob sie aus dem Request oder aus der Vorlagen-Charge stammen. So sehen Sie unmittelbar, mit welchen Werten der Shop gearbeitet hat. Dazu kommt das Element VoucherNumbers mit je einem VoucherNumber-Element pro generiertem Gutschein.

GetVoucherCharges

Liefert die Liste der vorhandenen Chargen.

Parameter	Beschreibung	Pflichtfeld
`ChargeType`	`template` liefert nur Chargen mit Vorlagen (Standard), `all` liefert alle Chargen	nein

Die Antwort enthält ChargeList mit je einem ChargeData-Element pro Charge, darin die ChargeId und die Gutscheindaten der Charge.

<ns:GetVoucherCharges>
  <request>
    <ShopID>TestShop</ShopID>
    <Password>geheim</Password>
    <MsgID>123</MsgID>
  </request>
</ns:GetVoucherCharges>

GetVoucherCodes

Liefert alle Codes einer bestimmten Charge. Weil eine Charge sehr groß sein kann, arbeitet diese Funktion seitenweise.

Parameter	Beschreibung	Pflichtfeld
`ChargeId`	ID der Charge	ja
`PageSize`	Anzahl Codes pro Request, Standard und Maximum sind 1000	nein
`NextPageToken`	Token aus der vorherigen Antwort, um die nächste Seite zu holen	nein

Die Antwort enthält VoucherList mit je einem VoucherData-Element pro Code. Darin steht die Nummer im Feld Num, dazu die Gutscheindaten. Für das Blättern zählen zwei Felder:

Feld	Bedeutung
`LastPage`	`true`, wenn alle Codes gesendet wurden
`NextPageToken`	Token für den nächsten Request, wenn noch Codes ausstehen

Die Codes kommen alphabetisch sortiert. Wiederholen Sie den Request mit dem erhaltenen NextPageToken, bis LastPage auf true steht.

GetVoucherChargeInfo

Liefert die Daten einer bestimmten Charge. Pflichtfeld ist neben ShopID und Password die ChargeId.

GetVoucherPoolInfo

Der Gutschein-Pool enthält Gutscheinnummern, die nicht der WEBSALE-Gutschein-Generator erzeugt hat, sondern ein externes System auf Vorrat. Diese Funktion liefert, wie viele davon noch verfügbar sind.

Parameter	Beschreibung	Pflichtfeld
`ChargeId`	ID der Charge, deren Anzahl zurückgegeben werden soll	ja
`ChargeType`	`template` liefert nur Chargen mit Vorlagen (Standard), `all` alle Chargen	nein
`SubShopValidity`	Liefert die Anzahl der Gutscheine, die in diesem Subshop einlösbar sind	nein

Fragen Sie den Pool-Bestand ab, bevor Sie Gutscheine daraus anfordern. Reicht der Vorrat nicht, scheitert CreateVouchers mit ES024.

Fehlerbehandlung

Tritt ein Fehler auf, antwortet die Schnittstelle mit einem SOAP Fault:

<SOAP-ENV:Fault>
  <faultcode>SOAP-ENV:Client</faultcode>
  <faultstring>ES007 SSL erforderlich</faultstring>
</SOAP-ENV:Fault>

Allgemeine Fehler

Fehlermeldung	Beschreibung
`ES001 Fehlende ShopID oder Passwort`	`ShopID` oder `Password` fehlt. Aus Sicherheitsgründen wird nicht genauer unterschieden.
`ES002 Ungültige ShopID oder ungültiges Passwort`	Kein passender Shop, falsches Passwort oder Schnittstelle nicht freigeschaltet.
`ES005 Fehler bei Server-Initialisierung`	Fehler bei der Initialisierung des SOAP-Servers. Hält er länger als 30 Minuten an, wenden Sie sich an die WEBSALE AG.
`ES007 SSL erforderlich`	Der Aufruf muss über eine verschlüsselte Verbindung erfolgen.
`ES008 Falsche Shop-Version`	Das aufgerufene SOAP-Interface passt nicht zur Version des Shops.
`ES009 Fehlendes Pflichtfeld`	Ein Pflichtfeld fehlt oder ist leer.
`ES012 Formatfehler`	Ein Feld mit vorgegebenem Format hat einen falschen Aufbau.
`ES015 Ungültiger Request`	Das SOAP-Framework konnte den Request nicht verarbeiten.

Fehler beim Generieren

Fehlermeldung	Beschreibung
`ES017 Max. VoucherCount-Wert (1000) überschritten`	Es wurden mehr als 1000 Gutscheine angefordert.
`ES018 ChargeId existiert bereits`	Die neu anzulegende Charge existiert schon.
`ES019 ChargeId existiert nicht`	Die als Vorlage angegebene Charge existiert nicht.
`ES020 Charge enthält keine Vorlage`	Die Charge existiert, enthält aber keine Vorlage.
`ES021 Ungültiger Wert`	Ein Feld mit begrenztem Wertebereich 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`	Beim Entnehmen aus dem Pool lässt sich keine neue Charge anlegen.
`ES024 Ungenügende Zahl von Gutscheinen im Pool`	Im Pool liegen weniger Gutscheine als angefordert.

Fehler beim seitenweisen Abruf

Fehlermeldung	Beschreibung
`ES026 CreateNextPageToken failed`	Das Token konnte nicht erzeugt werden, meist wegen eines ungültigen `NextPageToken`.
`ES027 ParseNextPageToken failed`	Das Token konnte nicht gelesen werden, meist wegen eines ungültigen `NextPageToken`.
`ES028 ChargeId existiert nicht in DB`	Die angegebene Charge existiert nicht in der Datenbank.
`ES029 ChargeId fehlt`	Im Request fehlt die `ChargeId`.
`ES030 Token ist ungültig`	Das Token wurde gelesen, ist aber ungültig.

WSDL-Datei und Server-URL

Zur Schnittstelle gehört die WSDL-Datei createvouchers.wsdl. Sie und die URL des SOAP-Servers erhalten Sie von Ihrem WEBSALE-Ansprechpartner.

Schnittstellen

Das Prinzip der Vorlagen-Charge

CreateVouchers

Steuerung des Aufrufs

Gutscheindaten

Antwort

GetVoucherCharges

GetVoucherCodes

GetVoucherChargeInfo

GetVoucherPoolInfo

Fehlerbehandlung

Allgemeine Fehler

Fehler beim Generieren

Fehler beim seitenweisen Abruf

WSDL-Datei und Server-URL

Verwandte Themen

​Das Prinzip der Vorlagen-Charge

​CreateVouchers

​Steuerung des Aufrufs

​Gutscheindaten

​Antwort

​GetVoucherCharges

​GetVoucherCodes

​GetVoucherChargeInfo

​GetVoucherPoolInfo

​Fehlerbehandlung

​Allgemeine Fehler

​Fehler beim Generieren

​Fehler beim seitenweisen Abruf

​WSDL-Datei und Server-URL

​Verwandte Themen

Das Prinzip der Vorlagen-Charge

CreateVouchers

Steuerung des Aufrufs

Gutscheindaten

Antwort

GetVoucherCharges

GetVoucherCodes

GetVoucherChargeInfo

GetVoucherPoolInfo

Fehlerbehandlung

Allgemeine Fehler

Fehler beim Generieren

Fehler beim seitenweisen Abruf

WSDL-Datei und Server-URL

Verwandte Themen