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:

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.