Format und Inhalt - WS-SFTP-Gutscheindaten (to-Shop) (DE)
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:
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:
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 |
---|---|---|
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. | Nein |
Currency | Die Währung der Gutscheine | Ja |
Type | Der Typ der Gutscheine. Folgende Typen werden unterstützt: | Ja |
Type2 | Werbegutschein/Kaufgutschein 1: Werbegutschein | Ja |
Amount | Betrag oder Prozentsatz des Gutscheins | Ja |
AmountType | 0: Amount enthält einen absoluten Betrag (Default) | 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: Beispiel: | 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: | Nein |
State | Der Status des Gutscheins, folgende zwei Werte sind möglich: | Nein |
MinOrderValue | Mindestbestellwert, ab dem der Gutschein eingelöst werden kann | Nein |
MinOrderValueMultiCurrency | Dieses Feld wird bei MultiCurrency-Gutscheinen statt MinOrderValue verwendet. Format: | 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) | 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. | 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: Beispiel 2: Beispiel 3: | 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 |
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:
| 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 |
---|---|---|
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.