Allgemeines

Diese Dokumentation beschreibt das Format und den Inhalt von Gutscheindaten, welche an den Shop gesendet werden können.

Übertragung der Importdateien

Die nachfolgend beschriebenen Importdateien können dabei auf 3 Arten übertragen werden:

Übertragung per SFTP-REST

Schritt 1: Übertragen der Importdateien mittels SFTP
Schritt 2: Starten des Imports der Daten mittels REST-Trigger

Da das Triggerverfahren in ähnlicher Weise für verschiedene Schnittstellen verwendet wird, ist es in der separaten Dokumentation „SFTP-REST-to-Shop“ beschrieben:

SFTP-REST-to-Shop

Verwenden Sie bei diesem Verfahren die Dateinamen voucherupdate.csv bzw. voucherdelete.csv.

Übertragung per SFTP-SOAP

Schritt 1: Übertragen der Importdateien mittels SFTP
Schritt 2: Starten des Imports der Daten mittels SOAP-Trigger

Da das Triggerverfahren in ähnlicher Weise für verschiedene Schnittstellen verwendet wird, ist es in der separaten Dokumentation „SFTP-SOAP-to-Shop“ beschrieben:

SFTP-SOAP-to-Shop

Verwenden Sie bei diesem Verfahren die Dateinamen voucherupdate.csv bzw. voucherdelete.csv.

Alternative Übertragung per WSPManager (Vorgängerversion)

Auch mittels des von WEBSALE bereitgestellten Windows-Tools „WSPManager“ können Importdaten auf den Shop-Server übertragen und importiert werden. Diese Methode sollte benutzt werden, wenn z. B. auf dem System des Händlers kein SFTP-Transfer bzw. kein REST/SOAP-Trigger implementiert werden kann.

Die Übertragung per WSPManager wird in der separaten Dokumentation „WSPManger-to-Shop“ beschrieben: WSPManager-to-Shop

Verwenden Sie bei diesem Verfahren die Dateinamen voucherupdate.dat bzw. voucherdelete.dat, diese Dateien müssen im Verzeichnis „data-exchange“ abgelegt werden.

Namen und Format der Importdateien

Aufbau der Datei voucherupdate.dat/voucherupdate.csv

Die Datei dient dazu, neue Gutscheine anzulegen oder vorhandene Gutscheine zu ändern. Sie enthält folgende Felder:

Name	Bedeutung	Pflichtfeld

Name	Bedeutung	Pflichtfeld
Number	Die (eindeutige) Gutscheinnummer. Die Länge der Nummer darf 200 Zeichen nicht überschreiten. Die “Nummer” darf im Prinzip beliebige Zeichen enthalten. Umlaute und ähnliche “Sonderzeichen” (d. h. Zeichen die nicht Teil des ASCII-Codes sind) sollten jedoch vermieden werden, da sie sich die zugehörigen Gutscheine im Shop nicht einlösen lassen, wenn die Zeichensatz-Kodierung im Shop von der Kodierung der Gutscheindaten abweicht.	Ja
ChargeId	Die Chargen-ID der Gutscheine. Dieser Wert ist zum Bearbeiten bzw. Anzeigen der Gutscheindaten im Servicebereich erforderlich.	Ja
ChargeDescr	Beschreibung der Charge, so wie sie im OSB angezeigt wird	Nein
ChargeLabel	„Label“ des Gutscheins, das in den Bestelldaten mit übergeben wird und für Auswertungen durch nachgelagerte Systeme genutzt werden kann. Es können mehrere „Label“ als kommagetrennte Liste angegeben werden.	Nein
Currency	Die Währung der Gutscheine	Ja
Type	Der Typ der Gutscheine. Folgende Typen werden unterstützt: 0: Restbetrag kann wiederverwendet werden 1: Restbetrag verfällt 2: Universalgutschein 3: Universalgutschein (kundenspezifisch, d. h. jeder Kunde kann den Gutschein nur einmal verwenden) 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 (Universalgutschein 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)	Ja
Type2	Werbegutschein/Kaufgutschein 1: Werbegutschein 2: Kaufgutschein	Ja
Amount	Betrag oder Prozentsatz des Gutscheins	Ja
AmountType	0: Amount enthält einen absoluten Betrag (Default) 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.	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: `<g><c>ISO-Code der Währung</c><a>Betrag</a></g>...` Beispiel: `<g><c>EUR</c><a>10.00</a></g>` `<g><c>GBP</c><a>8.00</a></g>`	Ja (nur bei Gutscheinen mit mehreren Währungen)
UsedAmount	Der bereits eingelöste Betrag des Gutscheins	Nein
UsedAmountMultiCurrency	Dieses Feld wird bei MultiCurrency-Gutscheinen statt UsedAmount verwendet. Format: `<g><c>ISO-Code der Währung</c><a>Betrag</a></g>`...	Nein
State	Der Status des Gutscheins, folgende zwei Werte sind möglich: 1: Aktiv 0: Nicht aktiv Dieses Feld ist optional, default: ein Gutschein ist aktiv.	Nein
MinOrderValue	Mindestbestellwert, ab dem der Gutschein eingelöst werden kann	Nein
MinOrderValueMultiCurrency	Dieses Feld wird bei MultiCurrency-Gutscheinen statt MinOrderValue verwendet. Format: `<g><c>ISO-Code der Währung</c><a>Betrag</a></g>`...	Nein
ValidFrom	Datum, ab dem der Gutschein gültig ist, im Format „YYYYMMDD“	Nein
ValidUntil	Datum, bis zu dem der Gutschein gültig ist, im Format „YYYYMMDD“	Nein
MaxUseCount	Maximale Anzahl der Einlösungen (nur für Universalgutscheine) Fehlt dieses Feld, oder ist es leer, so ist der Gutschein beliebig oft einlösbar.	Nein
MaxDiscountValue	Nur bei prozentualem Rabatt: Der maximale Wert des Gutscheins, der eingelöst werden kann	Nein
MaxDiscountValueMultiCurrency	Dieses Feld wird bei MultiCurrency-Gutscheinen statt MaxDiscountValue verwendet. Format: `<g><c>ISO-Code der Währung</c><a>Betrag</a></g>...`	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
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". Dieses Feld ist optional, per Default wird es auf "-1"/Standard" gesetzt.	Nein
VoucherProds	Die Nummern der Produkte, die automatisch in den Warenkorb gelegt werden sollen, wenn dieser Gutschein eingelöst wird (kommagetrennte Liste).	Nein
Pool	„y“: Der Gutschein wird in den „Gutschein-Pool“ geschrieben und lässt sich erst im Shop einlösen, wenn er über die SOAP-Gutschein-Schnittstelle aktiviert wurde. Bei jedem anderen Wert, oder wenn das Feld komplett fehlt, wird ein normaler Gutschein angelegt, der sofort einlösbar ist. Es ist nicht möglich, einen bereits aktivierten Gutschein erneut in den Pool zu importieren.	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. Analog können mit den negativen Tags <!i></!i> und <!n></!n> Kunden angegeben werden, für die der Gutschein nicht gilt. Sobald dieses Feld gefüllt ist, muss ein Kunde im Shop eingeloggt sein, um den Gutschein verwenden zu können. Beispiel 1: <i>123</i> (Gutschein gilt nur für den Kunden mit dem Userindex 123) Beispiel 2: <n>abc</n><n>xyz</n> (Gutschein gilt nur für die Kunden mit den Nummern abc und xyz) Beispiel 3: <!i>456</!i> (Gutschein gilt nicht für den Kunden mit dem Userindex 456)	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. Je Gutschein kann das Feld entweder <pi>- oder <pn>- Einträge enthalten, aber keine Kombinationen dieser beiden Tags. Beispiel 1, Beschränkung auf die Kategorien mit den Indizes „543“ und „345“: `<ci>543</ci><ci>345</ci>` Beispiel 2, Beschränkung auf die Produkte mit den Nummern „abc“ und „xyz“ `<pn>abc</pn><pn>xyz</pn>`	Nein
CatProdFilterSetBehavior	0: Produktnummer bzw. -index des Oberprodukts bestimmt, ob der Gutschein für einen Setartikel verwendet wird. 1: Produktnummer bzw. -index der Unterprodukte bestimmt, ob der Gutschein für einen Setartikel verwendet wird.	Nein
SpecialFeatures	Ein Tag-getrenntes Feld, das Angaben für kundenspezifische Spezialfeatures enthält. Beispiel: `<g><t>AdditionalProductFieldsFilter</t><setbehavior>asUnit\|single</setbehavior><filter><fieldname>tech. Feldname</fieldname><valueInList>a,b,c,d,e</valueInList></filter></g>`	Nein

Bemerkung:
Wenn die gleiche Gutscheinnummer mehrfach in der gleichen Importdatei vorkommt, so überschreiben die später in der Importdatei vorkommenden Datensätze normalerweise die früher vorkommenden.

Optional (d. h. wenn dies für Ihren Shop freigeschaltet wurde) kann der Import aber auch die Subshop-Felder der Gutschein-Datensätze zusammenfassen.

In diesem Fall wird vom Import geprüft, ob die Daten der mehrfach importierten Gutscheine (mit Ausnahme des „Subshop“ Feldes) in allen Zeilen gleich sind.
Ist dies der Fall, so werden die Subshop-Einträge aller Gutscheine mit gleichen Nummern zusammengefasst.
Gibt es Abweichungen, so werden nur die Daten des ersten Gutscheins mit dieser Nummer importiert und alle weiteren Vorkommen ignoriert.

Beispieldatei: Teil dieser Dokumentation ist die Beispieldatei „voucherupdate.dat“, die Sie auf der untergeordneten Seite zum Download finden.

Aufbau der Datei voucherdelete.dat/voucherdelete.csv

Die Datei dient dazu, Gutscheine zu löschen. Sie enthält folgende Felder:

Name	Bedeutung	Pflichtfeld

Name	Bedeutung	Pflichtfeld
Number	Die (eindeutige) Gutscheinnummer	Ja
Pool	y“: Der Gutschein wird aus dem „Gutschein-Pool“ gelöscht (siehe voucherupdate.dat)	Nein

Beispieldatei: Teil dieser Dokumentation ist die Beispieldatei „voucherdelete.dat“, die Sie auf der untergeordneten Seite zum Download finden.