Allgemeines

Diese Dokumentation beschreibt das Format und den Inhalt der Importdateien um Kundenstammdaten in den Shop zu senden.

Ü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.

Ü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.

Alternative Übertragung per WSPManager (Vorgängerversion)

Auch mittels des von WEBSALE bereitgestellten Windows-Tools „WSPManager“ können Daten 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 „WSPManager-to-Shop“ beschrieben.

Format und Zeichensatz der Dateien

Die Importdateien müssen im CSV-Format (character separated values) geliefert werden.

Das Zeichen (Character) das als Feld-Trennzeichen verwendet wird, muss das Tabulator-Zeichen (ASCII 9) sein. Andere Feldtrenner sind nicht zulässig.

Durch die Verwendung des Tabulator-Trennzeichens ist eine zusätzliche Umkleidung von Textfeldern, z. B. durch Doppel-Anführungszeichen ("), nicht erforderlich und auch nicht zulässig. Alle Arten von Anführungszeichen sind reguläre, zulässige Zeichen in den Feldern und dürfen daher direkt und ohne weitere Markierung in den Daten enthalten sein.

Der Zeichensatz in dem die Daten codiert sind, richtet sich nach der Sprache des Landes für den der Shop betrieben wird. Es sind die im Internet normierten Länder- ISO-Codes (z. B. ISO 8859-1) zu verwenden. Die Verwendung von UTF-8 ist bei WEBSALE V8 nicht zulässig, da sonst viele Schnittstellen und Services intern und zu Drittanbietern fehlerhafte Ergebnisse liefern würden.

Adressierung der Datensätze

Um gezielt auf die Stammdaten eines Kunden zugreifen zu können, sind Schlüsselfelder in den Daten erforderlich. Hierbei gibt es verschiedene Schlüsselfelder deren Inhalt entweder der Shop, die Warenwirtschaft oder der Kunde verwaltet.

Zu jedem Kundendatensatz gehören nur ein Mal vorkommende Daten wie der Kundenname oder dessen Anschrift, aber auch mehrfach vorkommende Datensets (Multiple Kundenzusatzdaten) wie mehrere abweichende Lieferanschriften.

IDs mit Schlüsselfunktion

E-Mail

Die primäre Identifikation eines Kunden erfolgt im Shop stets über seine Mail-Adresse.

Ein Neukunde ist aus Sicht des Shops somit ein Kunde, der sich im Shop ein neues Konto anlegt mit einer neuen, d. h. bisher noch keinem Konto zugeordneten, E-Mail-Adresse.

UserIndex der Kundenstammdaten (vom Shop verwaltet)

Der UserIndex ist eine eindeutige, numerische ID, die ausschließlich vom Shop bei einer Neuanlage eines Kundendatensatzes in der Shop-Datenbank vergeben wird.

Mögliche Fälle der Neuanlage im Shop

1. Ein Neukunde registriert sich im Shop

2. Ein ERP-System übergibt an den Shop einen bisher im Shopsystem unbekannten Kundendatensatz.

Um vorhandene Datensätze im Shop zu aktualisieren adressiert ein ERP-System einen Kundendatensatz mittels UserIndex.

CustomerID der Kundenstammdaten (vom ERP verwaltet)

Die CustomerID ist aus Sicht des Shops lediglich ein String, den der Shopbetreiber vergeben hat. Üblicherweise ist die CustomerID die eindeutige Kundennummer die das ERP-System generiert hat und mit dem im ERP-System der Kunden referenziert wird.

Importiert ein ERP-System einen neuen Kundendatensatz aus dem Shopsystem und vergibt anschließend eine neue Kundennummer (CustomerID), so muss das ERP-System dem Shop diese neue Kundennummer mitteilen. Als Userindex muss in dem Fall der Wert übergeben werden, der dem ERP zusammen mit der Bestellung oder dem Kundendatensatz (beim Abholen von Kundendatenänderungen) übermittelt wurde. Existiert bereits eine gleiche Kundennummer im Shop, dann wird der Import als Dublette abgelehnt.

TableIndex und ExternalID der Multiplen Kundenzusatzdaten

Diese beiden IDs werden bei der Adressierung in Tabellen von sog. "Multiplen Kundenzusatzdaten" verwendet, d. h. bei Datensätzen die nicht nur ein Mal sondern auch mehrfach vorkommen können. Solche multiplen, auch mehrfach je Kunde vorkommenden Datensätze können bei 2 Datentypen vorkommen

• Lieferadressen

• Bankverbindungen

Für jeden dieser zwei Datentyp gibt es im Shop eine eigene Tabelle.

TableIndex

Der TableIndex wird ausschliesslich vom Shop bei einer Neuanlage eines Datensatzes in einer der Kundenzusatzdaten-Tabellen vergeben.

Der TableIndex ist eine innerhalb der Tabelle eindeutige numerische ID.

Da es sich um drei verschiedene Kundenzusatzdaten-Tabellen handelt, können und werden in jeder Tabelle die TableIndex-Werte für die darin befindlichen Datensätze teilweise auch gleiche Werte aufweisen.

Beispiel
Ein Datensatz in der Tabelle der Lieferadressen kann den TableIndex "123" aufweisen, ebenso wie ein Datensatz eines ganz anderen Kunden in der Tabelle der Bankverbindungen ebenfalls den TableIndex "123" haben kann.

ExternalID

Die ExternalID ist aus Sicht des Shops lediglich ein String, den der Shopbetreiber vergeben hat. Üblicherweise ist dies ein Index den das ERP-System generiert hat und mit dem im ERP-System z. B. eine vom mehreren (multiplen) Lieferadressen eines Kunden referenziert wird.

Regeln der Datenübergabe vom ERP an den Shop

Neuanlage eines Kundenstammdatensatzes

Ein ERP-System übergibt an das Shopsystem einen Datensatz mit vom ERP vergebener neuer CustomerID und einer im Shop noch nicht bekannten Mail-Adresse.

Das Kennzeichen einer Neuanlage ist, dass das Feld "UserIndex" in den Kundenstammdaten leer ist.

Im Zuge des Imports der neuen Kundenstammdaten in die Shopdatenbank wird der UserIndex neu vergeben und anschließend vom Shop über eine Export-Schnittstelle an das ERP-System mitgeteilt (siehe Dokumentation der Schnittstelle „SOAP-from-shop“).

Der Import einer Kundendatensatz-Dublette wird als Fehler abgelehnt und der Datensatz wird verworfen. Eine Dublette wird erkannt, wenn in der Shopdatenbank die CustomerID oder die Mail-Adresse bereits vorhanden ist. Sowohl CustomerID als auch Mail-Adresse dürfen also im Shop nicht vorhanden sein. Die übrigen Daten wie Name oder Anschrift spielen für die Dublettenprüfung des Shops beim Kundendatenimport keine Rolle!

Hinweis:
Bei einem B2B-Shop könnte es eventuell eine Ausnahme von der Regel "Neuanlage nur bei nicht vorhandener Mail-Adresse" geben. Und zwar bei Verwendung sog. "Mehrfachkonten" (siehe dazu weiter unten das Kapitel "Mehrfachkonten"). In dieser Dokumentation wird jedoch im Zusammenhang mit der Mailadresse stets der Standardfall "eine Mailadresse darf nur ein Mal vorhanden sein" behandelt.

Update eines Kundenstammdatensatzes

Ein ERP-System aktualisiert einen bereits im Shop vorhandenen Datensatz, indem sämtliche Felder des gewünschten Kundenstammdatensatzes übergeben werden.

Das Kennzeichen eines Updates ist, dass das Feld "UserIndex" einen im Shop vorhandenen UserIndex beinhaltet.

Neuanlage eines Multiplen Kundenzusatzdatensatzes

Bei einer Neuanlage können dem Shop gleiche E-Mail-Adressen für unterschiedliche Konten übergeben werden. Die CustomerID muss jedoch eindeutig sein und darf noch nicht im Shop existieren. Sollte die CustomerID bereits existieren, so wird der Datensatz verworfen.

Update eines Multiplen Kundenzusatzdatensatzes

Ein Update eines multiplen Kundendatensatzes erfolgt über den UserIndex, wie es im Abschnitt oben “Update eines Kundenstammdatensatzes” beschrieben ist.

Beispiele der Adressierung

Zuweisung der IDs von Neukunden, die sich selbst im Shop registrieren

In der Shopdatenbank wird bei der Neuanlage des Kundenstammdatensatzes ein neuer UserIndex, z. B. „123456“generiert .

Der Shop übergibt nach der Neuanlage diesen UserIndex zusammen mit den anderen Kundenstammdaten an das ERP-System.

Die Übergabe der Kundenstammdaten des Neukunden erfolgt nach seiner Registrierung. Es werden dabei zwei Fälle unterschieden:

1. Übergabe gemeinsam mit den Bestelldaten
   wenn der Kunde nach der Neuanlage des Kontos eine Bestellung aufgegeben hat

2. Übergabe per Adressänderungsdaten
   wenn der Kunde nach der Neuanlage des Kontos nichts bestellt hat

Bei der Übergabe der Kundenstammdaten bleibt das Feld CustomerID (Kundennummer) leer, da der Shop ja noch keine ERP-Kundennummer kennt (siehe Dokumentation der Schnittstelle „SOAP-from-Shop“).

Das ERP-System muss nun beim Einlesen der Bestellung bzw. Adressänderungsdaten das Feld CustomerID prüfen und aufgrund der nicht vorhandenen Kundennummer erkennen, dass es sich um einen neuen Shopkunden handelt. Es muss dann eine neue ERP-Kundennummer vergeben, z. B. „777888“. Diese wird umgehend an den Shop zurück repliziert, indem das ERP-System in der Importdatei den Kunden mit dem Shop-UserIndex „123456“ adressiert und die neu vergebene ERP-Kundennummer „777888“ übergibt.

Zuweisung der IDs von Neukunden, die im ERP-System angelegt werden

Im ERP-System wird ein neuer Kunde (z. B. durch Mitarbeiter im Callcenter des Händlers) angelegt.
Für den Import eines Neukunden in den Shop sind mindestens 2 Felder notwendig:

1. eine neue Kundennummer

2. eine neue Mail-Adresse

Beide Felder sind Pflichtfelder. Der UserIndex hingegen muss in diesem Fall leer oder 0 sein.

Der Shop erkennt aufgrund des fehlenden UserIndex, dass es sich um eine Neuanlage handeln soll und prüft, ob CustomerID oder E-Mail bereits existieren. Falls nicht, wird ein neuer Datensatz mit einem neuen UserIndex in der Shopdatenbank angelegt. Die Userindizes der angelegten Neukunden lassen sich über die SOAP-Funktion “GetAddedCustomers” abfragen (siehe Dokumentation Übertragung per SFTP-SOAP-to-Shop).

Ausnahmen und Optionen

eMarketingManager-Anlagen

Neben dem Shop, legt auch der WEBSALE-eMarketingManager (eMM), ein Newslettersystem mit erweitertem Funktionsumfang, Datensätze an. Diese sind

• Mail-Adresse

• optionale Adressdaten

Da für einen Newsletter meist nur die Angabe einer Mail-Adresse erforderlich ist, sind die vom eMarketingManager (eMM) angelegten Kundendatensätze üblicherweise ohne Passwort.

Als Folge davon dass ein ERP-System einen Kundendatensatz aus dem Shop, der allein aus einer Mail-Adresse besteht, in der Regel verwirft, hat der Datensatz auch keine Kundennummer in der Kundendatenbank.

Hierbei ist zu beachten, wenn später ein Datensatz aus dem ERP-System mit einer vom der gleichen Mail-Adresse importiert werden soll:

• Viele ERP-Systeme kennen den UserIndex dieser Datensätze nicht, da sie entweder keine Adressdatenänderungen aus dem Shop einlesen oder die unvollständigen Adressdaten, die der eMarketingManager anlegt verworfen haben.

• Wenn diese Systeme dann versuchen einen neuen Datensatz mit der gleichen Mail-Adresse anzulegen, so wird dieser beim Import mit einer Fehlermeldung abgewiesen, da eine Mail-Adresse nicht doppelt in der Datenbank vorkommen darf.

Aus diesem Grund wird unter folgenden Bedingung zusätzlich die Mail-Adresse zu Adressierung herangezogen:

• In den Importdaten vom ERP ist kein UserIndex angegeben (d. h. es handelt sich aus Sicht des ERP um die Anlage eines Neukunden)

• In der Shop-Kundendatenbank existiert ein Kunde mit der Mail-Adresse in den Importdaten und ohne angelegtes Passwort und ohne Kundennummer in der Shopdatenbank.

Wenn diese Bedingungen erfüllt sind, so werden die Kundendaten aus den Importdaten in den Shop-Datensatz geschrieben, der die angegebene Mail-Adresse hat.

Hinweis:
Dies ist auch unter Datensicherheits-Aspekten aus Sicht des Shops tolerierbar, denn der Besitzer der Mailadresse musste sich bei der Newsletter-Registrierung einem Double-Opt-In-Verfahren unterziehen und damit eindeutig die Berechtigung zur Nutzung der Mail-Adresse beweisen.

Mehrfachkonten (eMail)

Mehrfachkonten sind ein Feature das vom Versandhändler für einen B2B Shop gewünscht sein kann.

Standardmäßig kann in einem WEBSALE Shop je Mail-Adresse immer nur ein einziges Konto angelegt werden. Sind jedoch in einem Shop Mehrfachkonten erlaubt, so ist es möglich, abweichend vom Standard, mehrere Kundenkonten mit der gleichen Mail-Adresse anzulegen. Jedes dieser Mehrfachkonten hat dann ein eigenes Passwort für den Login.

Mehrfachkonten sollten in einem Shop nur in absoluten Ausnahmefällen eingesetzt werden, da Mail-Dubletten einige Funktionen im Shop einschränken oder gar unmöglich machen.

Beispiel für eine Anwendung
Eine Einkaufsabteilung mit mehreren Einkäufern wickelt nicht mit individuellen Mail-Adressen je Einkäufer sondern mit einer einzigen zentralen Einkaufs-Mail-Adresse (z. B. einkaufsteam@firma.de) sämtliche einkaufsbezogene Kommunikation ab. Dennoch soll aber jede Bestellung im Shop nachvollziehbar dem einzelnen Einkäufer zugeordnet werden. In diesem Fall findet das Login in den Shop mit der jeweils gleichen Mail-Adresse statt, jeder Einkäufer hat aber sein eigenes Passwort. Durch die Kombination Mail / Passwort wird die Zuordnung zum richtigen Stammdatensatz des jeweiligen Einkäufers gewährleistet.

Bei Mehrfachkonten existieren somit mehrere Kundenstammdatensätze mit der gleichen Mail-Adresse im Shop.

Voraussetzung für die Nutzung
Um dieses Feature zu nutzen, muss der Shop speziell konfiguriert werden. Bitte kontaktieren Sie die WEBSALE AG, falls Mehrfachkonten erforderlich sein sollten.

Mehrfachkonten (CustomerID)

Normalerweise ist es über den Import nicht möglich mehrere Kundendatensätze mit der gleichen Kundennummer (CustomerID) anzulegen, da diese als Duplikate abgelehnt werden.

Bei Nutzung des Features „Mehrfachkonten (CustomerID)“ ist diese Beschränkung aufgehoben.

Im Vergleich zu dem Feature „Mehrfachkonten (eMail)“ ergibt sich die zusätzliche Komplikation, dass die Datensätze in den einzelnen Importdateien (z. B. custupdate.csv und billcomplete.csv) über UserIndex oder CustomerID verknüpft werden. Bei einer Neuanlage muss nun aber der UserIndex den Wert „0“ haben, so dass bei mehrdeutigen CustomerIDs keine eindeutige Zuordnung der Zeilen in den einzelnen Importdateien mehr möglich ist.

Aus diesem Grund muss bei Verwendung von „Mehrfachkonten (CustomerID)“ in jeder Importdatei das Feld „Email“ angegeben werden.

Eine Kombination von „Mehrfachkonten (CustomerID)“ mit „Mehrfachkonten (eMail)“ ist aus dem gleichen Grund nicht möglich.

Voraussetzung für die Nutzung
Um dieses Feature zu nutzen, muss der Shop speziell konfiguriert werden. Bitte kontaktieren Sie die WEBSALE AG, falls Mehrfachkonten erforderlich sein sollten.

Mail-Adressierung

Normalerweise wird ein Importdatensatz mit leerem Userindex (oder Userindex = 0) als Dublette abgelehnt, wenn die dort angegebene Mail-Adresse bereits für einen Kundendatensatz im Shop verwendet wird.

Bei aktivierter “Mail-Adressierung” wird in diesem Fall stattdessen der Datensatz mit der angegebenen Mail-Adresse überschrieben.
Das gleiche wird gemacht, wenn der in den Importdaten angegebene Userindex nicht in der Shopdatenbank existiert, d. h. es wird nach einem Datensatz mit übereinstimmender Mail gesucht und dieser wird überschrieben.

Vorteile

Es wird eine gewisse “Fehlertoleranz” erreicht. Wenn im ERP-System ein Kunde angelegt wird, der sich bereits selbst im Shop registriert hat, dann schlägt der Import normalerweise fehl, denn der Importdatensatz ist als “Neuanlage” gekennzeichnet und die Mail ist schon vergeben.

Zu diesem Fall kann es kommen, wenn das ERP den im Shop angelegten Kunden (noch) nicht eingelesen hat. Das kann passieren, wenn die Anlage im Shop und im ERP quasi gleichzeitig erfolgt ist oder wenn das ERP das Einlesen des Kundendatensatzes explizit abgelehnt hat (z. B. wegen einer unvollständigen Adresse).

Weiterhin kann auch dann noch ein Import eines Kundendatensatzes erfolgen, wenn in der ERP-Datenbank ein falscher Userindex steht, z. B. weil sich der Kunde im Shop gelöscht und wieder neu registriert hat und dieser Vorgang nicht im ERP angekommen ist.

Nachteile

Die “Fehlertoleranz” ist auch gleichzeitig ein Nachteil, weil sie Abweichungen zwischen ERP-Datenbank und Shop-Datenbank verschleiert.

So kann ein Sachbearbeiter durch die Neuanlage eines Kunden im ERP einen bereits vorhandenen Kundendatensatz im Shop überschreiben, ohne dass er in irgendeiner Form darauf hingewiesen wird.

Etwas ähnliches kann passieren, wenn der Userindex im ERP nicht mehr stimmt, auch dadurch können unbewusst Daten eines Shopkunden überschrieben werden, für den die Änderungen nicht gedacht waren.

Weiterhin können “Mehrfachkonten (eMail)” natürlich nicht in Kombination mit der “E-Mail-Adressierung“ verwendet werden.

Voraussetzung für die Nutzung
Um dieses Feature zu nutzen, muss der Shop speziell konfiguriert werden. Bitte kontaktieren Sie die WEBSALE AG, falls E-Mail-Adressierung erforderlich sein sollten.

Import-Dateien

Beschränkung der Feldlängen

Die Voreinstellung und gleichzeitig maximal zulässige Länge aller Kundendatenfelder ist 256 Zeichen.

Im Abschnitt “AddressMaxInputLen” der Shopkonfiguration „shop.config“ kann bei Bedarf die maximale Länge der einzelnen Felder, für die der Kunde im Shop Inhalte eingeben kann, herabgesetzt werden. Von dieser Möglichkeit sollten Sie Gebrauch machen, wenn die jeweilige Feldlänge in Ihrem System kleiner als 256 Zeichen ist.

Beschränkung der Dateigröße

• Import per SFTP: 4 GB je Datei

• Import per WSPManager: 1 GB je Datei

Übersicht über die Importdateien

Reihenfolge des Imports

Die Dateien werden in folgender Reihenfolge importiert:

1. *delete Dateien

2. custupdate.csv

3. Alle anderen *update Dateien

4. *complete Dateien

Es könnten also innerhalb eines Imports zuerst Datensätze eines Kunden gelöscht und danach wieder eingefügt werden, falls das aus Sicht des exportierenden Systems sinnvoll ist.

Aufgrund der Verarbeitung als letztes hat ein Komplett-Import aller Datensätze stets "die Oberhand". Werden mit einer update-Datei und in der zugehörigen complete-Datei also Datensätze für den gleichen Kunden übergeben, so überschreiben die Daten der complete-Datei die vorher importierten Daten der update-Datei.

Aufbau und Inhalt der Datei custupdate.csv

Über diese Datei können neue Datensätze im Shop angelegt und diverse Optionen für die Kunden gesetzt werden. Damit für einen Kunden Rechnungsadressen, Lieferadressen usw. importiert werden können muss immer auch zunächst ein Datensatz mit Hilfe der custupdate.csv angelegt werden.

Werden Pflichtfelder in der Datei nicht geliefert (d. h. fehlt die Spalte komplett), so bleiben die ursprünglich für diese Felder im Kundendatensatz gespeicherten Werte erhalten.

Die Datei enthält folgende Felder:

Aufbau und Inhalt der Datei custdelete.csv

Über diese Datei können Datensätze aus dem Shop gelöscht werden. Wird ein Datensatz mit der custdelete.csv gelöscht, so werden alle Daten des Kunden gelöscht, d. h. seine Rechnungsadressen, Lieferadressen usw.

Die Datei enthält folgende Felder:

Aufbau und Inhalt der Datei billupdate.csv/billcomplete.csv

Diese Dateien enthalten die einzufügenden oder zu aktualisierenden Rechnungsadressen. Der Aufbau der beiden Dateien ist identisch. Die enthaltenen Daten werden jedoch beim Import unterschiedlich behandelt:
Datensätze eines Kunden die in der billupdate.csv nicht enthalten sind bleiben in der Kundendatenbank des Shops erhalten, während sie beim Import der identischen Daten in einer billcomplete.csv gelöscht werden.

Beispiel

Die Kundendatenbank des Shops enthält zwei Kunden mit den Kundennummern “123” und “ABC”. Für den Kunde “123” sind in der Kundendatenbank 5 Rechnungsadressen gespeichert. In der billupdate.csv/billcomplete.csv sind für den gleichen Kunden 3 Rechnungsadressen vorhanden. Der Kunde “ABC” taucht in den Importdateien nicht auf.

Beim Import der Daten als “billcomplete.csv” würden die 5 Rechnungsadressen des Kunden “123” aus der Datenbank durch die 3 Rechnungsadressen aus der Importdatei ersetzt.

Beim Import der Daten als “billupdate.csv” werden die 3 Adressen aus den Importdaten zu den bereits in der Kundendatenbank vorhandenen Adressen hinzugefügt bzw. die vorhandenen Adressen aktualisiert.

Die Daten des Kunden “ABC” bleiben in beiden Fällen unverändert in der Kundendatenbank erhalten.

Bitte beachten Sie, dass der Shop bisher nur eine Rechnungsadresse je Kunde unterstützt.

Die Dateien enthalten folgende Felder:

Aufbau und Inhalt der Datei billdelete.csv

Über diese Datei können einzelne Rechnungsadressen aus dem Shop gelöscht werden. Sollen alle Daten eines Kunden gelöscht werden, so genügt es den Datensatz mit der custdelete.csv zu löschen, ein Löschen der einzelnen Rechnungsadressen mit der billdelete.csv ist in diesem Fall nicht nötig.

Die Datei enthält folgende Felder:

Aufbau und Inhalt der Datei delivupdate.csv/delivcomplete.csv

Diese Dateien enthalten die einzufügenden oder zu aktualisierenden Lieferadressen. Diese werden analog zu den Dateien billupdate.csv bzw. billcomplete.csv behandelt. Lieferadressen müssen für einen Kunden nur dann importiert werden, wenn sie von den Rechnungsadressen abweichen.

Die Dateien enthalten folgende Felder:

Aufbau und Inhalt der Datei delivdelete.csv

Über diese Datei können einzelne Lieferadressen aus dem Shop gelöscht werden, sie wird analog zu der Datei billdelete.csv behandelt.

Die Datei enthält folgende Felder:

Aufbau und Inhalt der Datei bankupdate.csv/bankcomplete.csv

Diese Dateien enthalten die einzufügenden oder zu aktualisierenden Daten der Bankverbindung, sie werden analog zu den Dateien billupdate.csv bzw. billcomplete.csv behandelt.

Die Dateien enthalten folgende Felder:

Aufbau und Inhalt der Datei bankdelete.csv

Über diese Datei können einzelne Bankverbindungen aus dem Shop gelöscht werden, sie wird analog zu der Datei billdelete.csv behandelt.

Die Datei enthält folgende Felder:

Zeichensatzkonvertierung

Wenn die Adressdaten nicht in dem Zeichensatz geliefert werden können, der vom Shop verwendet wird, so kann der Zeichensatz beim Import konvertiert werden. Dafür stehen zwei Möglichkeiten zur Verfügung:

1) Verwendung der Felder „CharsetImport“ und „CharsetShop“

Diese beiden Felder müssen in der Datei custupdate.csv für jeden importierten Datensatz angegeben werden und enthalten den Zeichensatz des Datensatzes in den Importdaten und den Zeichensatz der im Shop verwendet werden soll.

2) Konfiguration der Konvertierung in der Datei global.config

Hierbei wird in der Datei „global.config“ im Verzeichnis „konfiguration“ eingestellt in welchem Zeichensatz die Kundendaten geliefert werden. Die Datei „global.config“ ist im Shop optional und muss deshalb eventuell erst angelegt werden.

Der Zeichensatz des Shops wird aus der „shop.config“ gelesen. Damit der Subshop (und damit die zu verwendende shop.config) bestimmt werden kann, muss bei dieser Methode bei jedem Datensatz das Feld „MainSubhop“ gefüllt sein.

Beispiel für die Konfiguration in der global.config

Einziger Pflichtparameter ist „ConvertCharset“, denn nur wenn dieser Parameter den Wert „yes“ hat wird der Zeichensatz überhaupt konvertiert. „ImportCharset“ gibt den Zeichensatz der Importdatei an. Fehlt der Parameter oder ist er leer, so wird der Zeichensatz „UTF-8“ verwendet.
„UnknownCharacters“ regelt das Verhalten, wenn die Importdatei Zeichen enthält die im Zeichensatz des Shops nicht vorhanden sind. Der Default-Wert ist „ignore“. Dabei werden Zeichen, die sich nicht konvertieren lassen, komplett weggelassen. Bei „stdreplace“ wird versucht, unbekannte Zeichen durch ein oder mehrere ähnlich aussehende Zeichen zu ersetzen. Der Wert „mapreplace“ bewirkt, dass vor der eigentlichen Konvertierung konfigurierbare Ersetzungen vorgenommen werden. Wenn sich Zeichen auch nach diesen Ersetzungen nicht konvertieren lassen, so werden sie (wie bei „ignore“) weggelassen.

Welche Zeichen durch was ersetzt werden, wird in den „<+ImportCharsetConvertMap>“ Sektionen festgelegt.

In der Datei global.config kann es mehrere dieser Sektionen geben. Für jeden benötigten Zeichensatz eine. Der Parameter „Charset“ gibt den Zeichensatz an für den die Sektion verwendet werden soll, alle anderen Parameter stellen Ersetzungsregeln dar. Links vom „=“ steht dabei ein Zeichen oder eine Zeichenfolge aus der Importdatei, rechts davon die gewünschte Ersetzung. Da sich der Zeichensatz der Importdatei im allgemeinen vom Zeichensatz der global.config unterscheidet, können die Zeichen URL-kodiert angegeben werden. Bei dieser Kodierung wird ein Zeichen im wesentlichen durch seinen hexadezimalen Code ersetzt und dem Code ein „%“ vorangestellt.

Ausgenommen von der Zeichensatzkonvertierung sind die Felder „CustomerID“, „Mail“, „Subshop“ und „MainSubshop“.

Begrüßungsmails für Neukunden

Es besteht die Möglichkeit jedem Neukunden, dessen Daten über die Datei „custupdate.csv“ importiert wurden, eine „Begrüßungsmail“ zu senden. Ein Kunde in der „custupdate.csv“ gilt als Neukunde, wenn eine der beiden folgenden Bedingungen erfüllt ist:

• Der Kunde stand vor dem Import noch nicht in der Datenbank

• Der Kunde hatte vorher keine Kundennummer und ihm wird über die „custupdate.csv“ eine neue zugewiesen

Der Text der Mail, die an den Kunden gesendet wird, wird aus einem Template gebildet, das in der shop.config konfiguriert wird:

Die Template-Datei liegt in dem Verzeichnis ".../benutzter/templates/<subshop>/"

Das Template, das für den Versand der Begrüßungsmail verwendet wird, hängt also vom Inhalt des „MainSubshop“ Feldes in der Importdatei ab. Fehlt dieses Feld oder ist es leer, so kann keine Begrüßungsmail versendet werden.

Der Absendername, die Absenderadresse und der Betreff der Begrüßungsmail werden ebenfalls in der shop.config festgelegt:

Ist das Absenden einer Begrüßungsmail nicht erwünscht, so kann dies verhindert werden in dem der Parameter "Allow" auf "no" gesetzt wird:

Alternativ oder zusätzlich kann das Template gelöscht oder umbenannt werden.

Folgende Platzhalter stehen in dem Mail-Template zur Verfügung:

Alle Adressdaten (A-CompleteSalutation, A-Salutation, A-FirstName, A-LastName) werden aus der ersten Rechnungsadresse des Kunden gelesen.

Zwangsänderung Passwort

Mit diesem Feature lässt sich erreichen, dass ein über den Import angelegter Kunde nach dem ersten Login sein Passwort ändern muss. Setzen Sie dazu in der shop.config den Parameter "NewUserPWChangeRequired" im Abschnitt "UserData" auf "yes".

Behandlung von gelöschten Zugängen

Kunden haben die Möglichkeit ihre Zugänge zum Shop zu löschen bzw. zu deaktivieren. Diese "gelöschten" Datensätze bleiben zunächst in der Datenbank und werden dort nur als gelöscht geflaggt.

Wenn sie versuchen für gelöschte Datensätze Daten zu importieren, so werden die Änderungen ignoriert. Ein Löschen der Daten über die custdelete.csv ist jedoch möglich bzw. sogar erforderlich um die Daten tatsächlich aus der Datenbank zu entfernen.

Hintergrund dieses Verhaltens ist, dass Warenwirtschaftssysteme Kundendaten normalerweise nicht löschen können. Würden die Kundendaten komplett aus der Shop-Datenbank gelöscht so bestünde die Gefahr, dass die Warenwirtschaft die im Shop gelöschten Daten wieder in den Shop importiert. Der Kunde, der seinen Zugang im Shop gelöscht hat würde sich dann zurecht wundern, warum sein gelöschter Zugang auf einmal wieder aktiv ist.

Beispieldateien

Teil dieser Dokumentation sind folgende Beispieldateien, die Sie auf der untergeordneten Seite zum Download finden:

Fehlercodes

Fehler-Mails beim Import über den WSPManager

Bei Übertragung der Kundenimportdateien mit dem WSPManager wird die Liste der aufgetretenen Fehler und Warnungen gekürzt, wenn sie eine bestimmte Länge überschreitet.

Die vollständige Liste der aufgetretenen Fehler und Warnungen können Sie sich per Mail zuschicken lassen, konfigurieren Sie dazu die folgenden Sektionen in der shop.config des ersten Subshops:

Weitere Importdateien

Übersicht der „weiteren Importdateien“

Import von Produktkundengruppen

Mit Produktkundengruppen lassen sich Kategorien im Shop ein- oder ausblenden, je nachdem welcher Kunde sich im Shop eingeloggt hat.

Die Zuordnung von Kunden zu Produktkundengruppen erfolgt über zwei zusätzliche Dateien im „customerimport“ Verzeichnis: „groupproductupdate.csv“ und „groupproductdelete.csv“.

Mit der Datei „groupproductupdate.csv“ können Kunden Produktkundengruppen zugewiesen werden, mit der Datei „groupproductdelete.csv“ können diese Zuweisungen wieder gelöscht werden.

Aufbau der Datei „groupproductupdate.csv“

Um dem Kunden mit der Kundennummer „1234“ z. B. die Produktkundengruppen 1 und 2 zuzuweisen könnte man folgende Datei verwenden:

CustomerID<TAB>GroupIdx

1234<TAB>1

1234<TAB>2

(„<TAB>“ steht in diesem Beispiel für das Tabulator-Zeichen/den ASCII-Code 9. Wenn dem Kunden vor dem Import bereits andere Produktkundengruppen zugeordnet waren, so bleiben diese erhalten)

Aufbau der Datei „groupproductdelete.csv“

Mit der folgenden Datei würde der Kunde mit der Kundennummer „1234“ aus der Produktkundengruppe „1“ entfernt, sowie die komplette Produktkundengruppe „2“ gelöscht:

CustomerID<TAB>GroupIDx

1234<TAB>1

*<TAB>2

Import von Daten für Kundenkonten, Bonuspunkte, Zuschüsse

Kundenkonten, Bonuspunkte und Zuschüsse sind vorgesehen für die Realisierung von Bonus-Systemen und Guthaben, die im Shop eingelöst werden können.

Bonuspunkte:
Ein Kunde bekommt z. B. für den Kauf eines Produkts eine Anzahl Bonuspunkte gutgeschrieben. Hat er genug Bonuspunkte zusammen, so kann er diese im Shop einlösen.

Wenn Sie keine Bonuspunkte anbieten, dann können Sie die Spalte "BonusPoints" in der Importdatei weglassen.

Kundenkonto:
Hier können Sie Kunden beliebige Guthaben gutschreiben. Beim Kauf wählt der Kunde dann die Zahlungsart "Kundenkonto" aus und bezahlt mit seinem Guthaben. WEBSALE reduziert automatisch das Guthaben nach einem Kauf.

Wenn Sie kein Kundenkonto anbieten, dann können Sie die Spalte "Credit" in der Importdatei weglassen.

Zuschuss:
Hier können Sie Kunden beliebige Zuschüsse gutschreiben. Der gewährte Zuschuss wird im Warenkorb von der Gesamtsumme abgezogen. Bei Bestellaufgabe wird der gewährte Zuschuss vom Zuschuss-Konto automatisch vom Shop abgezogen. Ein evtl. Restbetrag wird bei Folgebestellungen berücksichtigt, solange bis der Zuschuss aufgebraucht wurde.

Das Einlesen der Kundenkonto-Daten erfolgt über eine zusätzliche Datei mit Namen „accountupdate.csv“ im „customerimport“ Verzeichnis.

Aufbau der Datei „accountupdate.csv“

Bemerkungen:

• Für die Adressierung der Datensätze wird der UserIndex verwendet, das bedeutet somit indirekt, dass Kundenkontodaten nur für Kunden importiert werden können, die bereits in der Datenbank existieren, denn ansonsten ist der UserIndex nicht bekannt.

• Bei den Bonuspunkten, Guthaben und Zuschüssen, können neben absoluten Werten auch Differenzen angegeben werden. Zu diesem Zweck wird dem Wert ein „+“ oder ein „-“ vorangestellt.
  Hat ein Kunde z. B. 100 Bonuspunkte auf seinem Konto und Sie importieren den Wert „10“ in der Spalte „BonusPoints“ so wird der Wert in der Datenbank auf 10 gesetzt. Geben Sie stattdessen den Wert „+10“ an so wird der Wert auf 110 erhöht, bei „-10“ würde er auf 90 verringert.
  Wenn möglich sollten beim Import Differenzen angegeben werden, da es auf diese Weise nie passieren kann, dass durch den Import Änderungen rückgängig gemacht werden die durch den Online-Shop vorgenommen wurden. Bsp.: Sie wollen die Zahl der Bonuspunkte eines Kunden von 150 auf 100 heruntersetzen, weil er über eine telefonische Bestellung 50 Punkte eingelöst hat. Derselbe Kunde war kurz bevor Sie den Import gestartet haben im Shop und hat eine Bestellung abgeschickt, durch die ihm zusätzliche 77 Punkte gutgeschrieben wurden. Importieren Sie nun „100“ so löschen Sie damit die Gutschrift von 77 Punkten. Importieren Sie dagegen „-50“, so wird die Zahl der Bonuspunkte auf den korrekten Wert (177) gesetzt.

• Ein explizites Löschen von Einträgen aus der Kundenkonto-Tabelle ist nicht möglich, Einträge werden dann gelöscht, wenn (durch Übertragen der Datei „custdelete.csv”) die allgemeinen Kundendaten gelöscht werden. Sie können natürlich die Werte auf "0" setzen.

• Bei einem Import können mehrere Dateien mit Kundenkonten, Bonuspunkte und Zuschüsse importiert werden. In diesem Fall müssen die Namen mit einem „Suffix“ versehen werden, der Name einer Importdatei könnte dann z. B. „accountupdate_1.csv“ lauten.
  Der Suffix beginnt mit einem Unterstrich, gefolgt von einer oder mehreren Ziffern.
  Die Importdateien werden vor dem Import alphanumerisch sortiert, d. h. „accountupdate_10.csv“ wird vor „accountupdate_2.csv“ importiert.

Angebotsdaten

Mit dieser Funktion können Sie ein Angebot, das Sie einem bestimmten Kunden gemacht haben, in den Online-Shop übertragen, der Kunde kann die entsprechenden Produkte dann online bestellen.

Für den Import von Angebotsdaten müssen Sie zwei Dateien erstellen, die Datei „offerheadupd.dat“ und die Datei „offerprodupd.dat“. Die erste Datei enthält Daten die das gesamte Angebot betreffen, z. B. die Versandkosten. In der zweiten Datei sind die einzelnen Produkte des Angebots enthalten.

Löschen können Sie Angebote mit der Datei „offerdel.dat“.

Alle drei Dateien müssen im „data-exchange“ Verzeichnis abgelegt werden. Alternativ können die Dateien auch „offerheadupd.csv“, „offerprodupd.csv“ und „offerdel.csv“ benannt werden, in diesem Fall müssen sie im Verzeichnis der Kunden-Importdateien („customerimport“) gespeichert werden.

Bei einem Import über die SFTP-SOAP-Schnittstelle müssen die *.csv Dateien verwendet werden, bei einer Übertragung mit dem WSPManager können die *.dat oder die *.csv Dateien benutzt werden.

Aufbau der Datei offerheadupd.dat/offerheadupd.csv

Aufbau der Datei offerprodupd.dat/ offerprodupd.csv

Aufbau der Datei offerdel.dat/ offerdel.csv

Import von kundenabhängigen Bestellmengen

Für jedes Produkt und jeden Kunden kann eine maximale und/oder eine minimale Bestellmenge importiert werden.

Das Anlegen und Ändern von Bestellmengen erfolgt über die Importdatei „orderquantityupdate.csv“, das Löschen über die Datei „orderquantitydelete.csv“. Beide Dateien dürfen eine maximale Größe von 1 GB nicht überschreiten und beide müssen (wie die übrigen Kundenimportdateien) im Verzeichnis „customerimport“ angelegt werden.

Die Datei „orderquantitydelete.csv“ wird vor der Datei „orderquantityupdate.csv“ eingelesen, so dass es möglich ist bei einem Import Einträge zu löschen und wieder neu anzulegen.

Aufbau und Inhalt der Datei orderquantityupdate.csv

Die Datei dient zum Anlegen und Ändern von Einträgen und enthält folgende Felder:

Bemerkungen:

• Der Wert "-" in den Feldern "MaxOrderQuantity" und "MinOrderQuantity" bewirkt, dass der im Shop gesetzte Wert nicht verändert wird. Das Feld komplett leer zu lassen, hat den gleichen Effekt.

• Der Wert "$NoLimit$" in den Feldern "MaxOrderQuantity" oder "MinOrderQuantity" bewirkt, dass ein gesetztes Limit für das Produkt/den Kunden aufgehoben wird. D. h. der Kunde kann danach beliebig viel oder beliebig wenig von dem Produkt bestellen.

• Wenn für ein Produkt/einen Kunden noch nie explizit ein Wert für MinOrderQuantity oder MaxOrderQuantity gesetzt wurde, so entspricht der Wert "$NoLimit$".
  "$NoLimit$" ist also der Wert, mit dem die Felder "MaxOrderQuantity" und "MinOrderQuantity" initialisiert werden.

• Wenn für kein Produkt/keinen Kunden eine maximale/minimale Bestellmenge gesetzt werden soll, so kann die Spalte MaxOrderQuantity/MinOrderQuantity komplett weggelassen werden. Der Effekt ist der gleiche, als ob die Spalte mit dem Wert "-" gefüllt wäre.

• Beim Löschen von Produkten oder Kunden werden die zugehörigen Bestellmengen nicht automatisch gelöscht. Ein Automatismus ist problematisch, wenn Produkte oder Kunden gelöscht und danach wieder neu angelegt werden, weil danach auch die Bestellmengen neu importiert werden müssten.

• Es erfolgt keine Prüfung, ob ein Kunde oder ein Produkt in der Importdatei tatsächlich im Shop existiert. Dies hat den Vorteil, dass Bestellmengen vor den Produkten oder Kunden importiert werden können.

• Bei Produkten mit abhängigen Variationen reicht es nicht, für den Stammartikel eine Bestellmenge anzugeben. Stattdessen muss die Bestellmenge für jede einzelne abhängige Variation angegeben werden.

• Wenn ein Kunde im Shop bestellt, so wird der Wert von MaxOrderQuantity um die bestellte Menge verringert.

Aufbau und Inhalt der Datei orderquantitydelete.csv

Die Datei dient zum Löschen von Einträgen und enthält folgende Felder:

Bemerkungen:

Für jede Spalte kann der Spezialwert "*" angegeben werden. Dieser bewirkt, dass der Wert in dieser Spalte beim Löschen nicht berücksichtigt wird. Steht z. B. in der Spalte "ProdIndex" der Wert "123", in der Spalte "Subshop" der Wert "deutsch" und in der Spalte CustomerID der Wert "*", so würden die Bestellmengen des Produkts "123" für alle Kunden gelöscht werden

Import von Prime-Paketen

Die einem Kunden zugewiesenen Prime-Pakete werden über die Dateien primeupdate.csv und primedelete.csv importiert.

Aufbau der Datei primeupdate.csv

Die Datei primeupdate.csv dient zum Anlegen und Aktualisieren der einem Kunden zugewiesenen Prime-Pakete. Jedem Kunden können maximal 10 unterschiedliche Prime-Pakete zugewiesen werden.

Wird für einen Kunden ein Prime-Paket importiert, das diesem bereits zugewiesen ist, so werden die Daten des vorhandenen Prime-Paketes aktualisiert. Ist ihm das Prime-Paket noch nicht zugewiesen, so wird es hinzugefügt.

Prime-Pakete, die dem Kunden zugewiesen sind, aber nicht importiert werden, bleiben unverändert erhalten.

Jede Zeile der Import-Datei entspricht einem Prime-Paket, d. h. wenn einem Kunden 10 Prime-Pakete zugewiesen werden sollen, dann muss die Datei 10 Zeilen für diesen Kunden enthalten.

Die Datei primeupdate.csv enthält folgende Felder:

Aufbau der Datei primedelete.csv

Die Datei primedelete.csv dient zum Löschen von Prime-Paketen, die einem Kunden zugewiesen sind. Sie enthält folgende Felder:

Beispieldateien

Teil dieser Dokumentation sind folgende Beispieldateien, die Sie auf der untergeordneten Seite zum Download finden: