> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # WS-SOAP-Gutscheine erzeugen > Gutscheine aus einem Drittsystem heraus generieren und abrufen, über CreateVouchers, GetVoucherCharges, GetVoucherCodes, GetVoucherChargeInfo und GetVoucherPoolInfo. 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)](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale/ws-sftp-gutscheindaten-to-shop.md) 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 `` oder `` | | | `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 `EUR10.00`. 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 `` oder ``. ### 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. ```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} TestShop geheim 123 ``` ## 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: ```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} SOAP-ENV:Client ES007 SSL erforderlich ``` ### 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. ## Verwandte Themen * Wegweiser: [Marketing, SEO und externe Portale](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale.md) * Wegweiser: [WS-SFTP-Gutscheindaten (to-Shop)](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale/ws-sftp-gutscheindaten-to-shop.md) * Wegweiser: [Gutscheine anlegen oder importieren](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anlegen-oder-importieren.md) ## Related topics - [Marketing, SEO und externe Portale](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale.md) - [WS-SOAP-InfoMails](https://dokumentation.websale.de/v8s/schnittstellen/service-und-app/ws-soap-infomails.md) - [SOAP-from-Shop](https://dokumentation.websale.de/v8s/schnittstellen/uebertragung/soap-from-shop.md) - [WS-Gutscheindaten (from-Shop)](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale/ws-gutscheindaten-from-shop.md) - [SFTP-SOAP-to-Shop](https://dokumentation.websale.de/v8s/schnittstellen/uebertragung/sftp-soap-to-shop.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.