WS-SFTP-Kunden PRO - WEBSALE Dokumentation

Mit WS-SFTP-Kunden PRO übertragen Sie Kundenstammdaten aus Ihrer Warenwirtschaft in den Shop: Stammdaten, Rechnungs- und Lieferadressen, Bankverbindungen und eine Reihe weiterer kundenbezogener Daten.

Eigenschaft	Wert
Übertragungsrichtung	Warenwirtschaft → WEBSALE Shop (Data-to-Shop)
Übertragungsart	Dateien per SFTP, Import per REST oder SOAP
Dateiformate	CSV beziehungsweise DAT

Die Dokumentation zu dieser Schnittstelle ist auf vier Seiten verteilt:

Seite	Inhalt
Diese Seite	Übertragungswege, Dateiformat und Zeichensatz
Adressierung der Datensätze	Die Schlüsselfelder und die Regeln, nach denen Shop und Warenwirtschaft Datensätze einander zuordnen
Import-Dateien	Aufbau und Felder der Kerndateien für Stammdaten, Adressen und Bankverbindungen
Weitere Import-Dateien	Produktkundengruppen, Kundenkonten und Bonuspunkte, Angebote, kundenabhängige Bestellmengen und Prime-Pakete

Die drei Übertragungswege

Weg	Ablauf
SFTP und REST	Dateien per SFTP übertragen, Import per SFTP-REST-to-Shop starten
SFTP und SOAP	Dateien per SFTP übertragen, Import per SFTP-SOAP-to-Shop starten
WSPManager	Übertragung und Import über das Windows-Tool WSPManager

Der WSPManager ist die Vorgängerversion. Er kommt infrage, wenn sich auf Ihrem System weder ein SFTP-Transfer noch ein REST- oder SOAP-Trigger umsetzen lässt.

Format und Zeichensatz

Die Importdateien liegen im CSV-Format vor. Als Feldtrennzeichen ist ausschließlich der Tabulator zulässig, ASCII 9. Andere Trennzeichen akzeptiert der Import nicht. Daraus folgt eine Besonderheit, die Ihnen Arbeit spart: Weil der Tabulator in den Daten nicht vorkommt, brauchen Textfelder keine Umkleidung durch Anführungszeichen. Sie ist sogar unzulässig. Alle Arten von Anführungszeichen sind reguläre Zeichen und dürfen ohne Maskierung in den Feldern stehen. Der Zeichensatz richtet sich nach der Sprache des Landes, für das der Shop betrieben wird. Verwenden Sie die genormten ISO-Codes, beispielsweise ISO 8859-1. UTF-8 ist bei WEBSALE V8s nicht zulässig. Viele Schnittstellen und Dienste würden intern und gegenüber Drittanbietern sonst fehlerhafte Ergebnisse liefern.

Zeichensatzkonvertierung

Lassen sich die Adressdaten nicht im Zeichensatz des Shops liefern, konvertiert der Import sie. Dafür gibt es zwei Wege. Über die Felder in der custupdate.csv. Sie geben je Datensatz CharsetImport und CharsetShop an. Beide gehören zusammen, eines allein wird ignoriert. Über die global.config. In der Datei global.config im Verzeichnis konfiguration legen Sie fest, in welchem Zeichensatz die Kundendaten kommen. Diese Datei ist optional und muss gegebenenfalls erst angelegt werden. Den Zeichensatz des Shops liest der Import aus der shop.config. Damit er den richtigen Subshop findet, muss bei dieser Methode in jedem Datensatz das Feld MainSubshop gefüllt sein.

<CustomerImportPro>
  ConvertCharset     = yes         # [yes|no], standard = no
  ImportCharset      = UTF-8       # standard = UTF-8
  UnknownCharacters  = mapreplace  # standard = ignore
</CustomerImportPro>

<+ImportCharsetConvertMap>
  Charset = ISO-8859-1
  a       = %c4%83
  $delete = %c3%8d
  %56     = %c3%8e
  s       = %c5%9f
</+ImportCharsetConvertMap>

Parameter	Bedeutung
`ConvertCharset`	Einziger Pflichtparameter. Nur bei `yes` wird überhaupt konvertiert.
`ImportCharset`	Zeichensatz der Importdatei. Fehlt der Parameter oder ist er leer, gilt UTF-8.
`UnknownCharacters`	Verhalten bei Zeichen, die im Zeichensatz des Shops fehlen

Für UnknownCharacters gibt es drei Werte:

Wert	Verhalten
`ignore`	Standard. Nicht konvertierbare Zeichen werden weggelassen.
`stdreplace`	Unbekannte Zeichen werden durch ähnlich aussehende ersetzt.
`mapreplace`	Vor der Konvertierung greifen die konfigurierten Ersetzungen. Was danach immer noch nicht konvertierbar ist, wird weggelassen.

Die Ersetzungen stehen in <+ImportCharsetConvertMap>-Sektionen, je eine pro benötigtem Zeichensatz. Charset nennt den Zeichensatz, alle weiteren Parameter sind Ersetzungsregeln: links das Zeichen aus der Importdatei, rechts die Ersetzung. Weil sich der Zeichensatz der Importdatei meist von dem der global.config unterscheidet, lassen sich Zeichen URL-kodiert angeben, also als hexadezimaler Code mit vorangestelltem Prozentzeichen. Von der Konvertierung ausgenommen sind die Felder CustomerID, Mail, Subshop und MainSubshop.

Begrüßungsmails für Neukunden

Jeder über custupdate.csv importierte Neukunde kann eine Begrüßungsmail erhalten. Als Neukunde gilt dabei, wer eine von zwei Bedingungen erfüllt: Er stand vor dem Import nicht in der Datenbank, oder er hatte bisher keine Kundennummer und bekommt über die custupdate.csv eine zugewiesen. Den Text bildet ein Template, das Sie in der shop.config konfigurieren. Ein über den Import angelegter Kunde kann verpflichtet werden, sein Passwort nach der ersten Anmeldung zu ändern. Setzen Sie dafür in der shop.config im Abschnitt UserData:

<UserData>
  NewUserPWChangeRequired = yes    # [yes|no], standard = no
</UserData>

Gelöschte Zugänge

Löscht oder deaktiviert ein Kunde seinen Zugang, bleibt der Datensatz zunächst in der Datenbank und wird nur als gelöscht markiert. Für solche Datensätze ignoriert der Import alle Änderungen. Ein tatsächliches Entfernen ist nur über custdelete.csv möglich und dort auch nötig. Der Grund dafür ist praktisch: Warenwirtschaftssysteme können Kundendaten meist nicht löschen. Würde der Shop die Daten vollständig entfernen, bestünde die Gefahr, dass die Warenwirtschaft sie beim nächsten Lauf wieder importiert. Der Kunde, der seinen Zugang gelöscht hat, fände ihn dann unversehens wieder aktiv vor.

Fehlercodes

Code	Bedeutung
`EC001`	In der Importdatei fehlen die Headerfelder `UserIndex` und `CustomerID`. Der Import wurde abgebrochen.
`EC002`	In der Importdatei fehlen die Headerfelder `TableIndex` und `ExternalID`. Der Import wurde abgebrochen.
`EC003`	`CustomerID` und `UserIndex` sind beide leer. Der Datensatz wurde ignoriert.
`EC004`	`ExternalID` und `TableIndex` sind beide leer. Der Datensatz wurde ignoriert.
`EC005`	Weder die `CustomerID` noch der `UserIndex` existiert in der Datenbank.
`EC006`	Der angegebene `TableIndex` existiert für diesen Kunden nicht, wird aber bei einem anderen bereits verwendet. Weil er tabellenweit eindeutig sein muss, konnte der Datensatz nicht angelegt werden.
`EC007`	Der Datensatz enthält keine E-Mail-Adresse. Weil V8s-Shops sie für die Anmeldung brauchen, wird er ignoriert.
`EC008`	Der Datensatz existiert noch nicht, die E-Mail-Adresse wird aber bereits verwendet. Mehrere Datensätze mit derselben Adresse sind nur mit eingerichteten Mehrfachkonten zulässig.
`EC009`	Einem vorhandenen Kunden sollte eine Kundennummer zugewiesen werden, die bereits für einen anderen verwendet wird.
`EC010`	`CharsetImport` ohne `CharsetShop` wird ignoriert.
`EC011`	`CharsetShop` ohne `CharsetImport` wird ignoriert.
`EC012`	Zeichenketten konnten nicht fehlerfrei in den Zielzeichensatz konvertiert werden.
`EC013`	Ungültiger Zeichensatz. Einer der angegebenen Zeichensätze wird nicht unterstützt.
`EC014`	Es liegen sowohl verschlüsselte als auch per SFTP übertragene Daten vor.
`EC015`	Das Feld `UserIndex` fehlt, obwohl es bei den konfigurierten Importoptionen Pflicht ist.
`EC016`	Der angegebene `UserIndex` existiert nicht in der Shop-Datenbank.
`EC017`	Der `TableIndex` wurde ersetzt. Es kam eine Rechnungsadresse mit einem TableIndex, obwohl für den Kunden schon eine mit einem anderen existierte.
`EC018`	Mehr als eine Rechnungsadresse vorhanden. Derzeit wird nur eine je Kunde unterstützt.
`EC019`	In der Datei fehlt ein Pflichtfeld.
`EC020`	Ein Pflichtfeld ist leer.
`EC021`	Ungültiger Datentyp in einem Feld.
`EC022`	`UserIndex` ist leer.
`EC023`	Ungültiger Wert für `TableIndex`. Er ist keine Zahl oder überschreitet den Maximalwert 2147483647.
`EC024`	Ungültige Indizes für eine Produktkundengruppe in `groupproductupdate.csv`. Gemeint ist das Feld `GroupIdx`.
`EC025`	Keine Kundendatenbank vorhanden. Interner Fehler, der auftritt, wenn beim Anlegen des Shops keine Kundendatenbank entstanden ist.
`EC026`	`CustomerID` nicht in der Datenbank vorhanden. Tritt nur bei Importdateien für Prime-Pakete auf.
`EC027`	Die maximale Zahl von zehn Prime-Paketen für einen Kunden wurde überschritten.
`EC028`	Ungültiges Format für `ValidFrom` oder `ValidUntil`.
`EC029`	Mehrfachkonten und Mail-Adressierung lassen sich nicht gleichzeitig verwenden.
`EC030`	Der angegebene `UserIndex` existiert nicht in der Datenbank. Tritt nur bei Importdateien für Prime-Pakete auf.

Bei EC006 lohnt sich eine Verhaltensregel: Lassen Sie den TableIndex beim Anlegen neuer Datensätze leer und überlassen Sie die Vergabe der Datenbank. Ein selbst gewählter TableIndex kollidiert früher oder später mit einem bestehenden. Bei EC024 protokolliert der Import nur die Summe der Zeilen mit ungültigen Indizes, nicht jede einzelne Zeile.

Fehler-Mails beim Import über den WSPManager

Überträgt der WSPManager die Kundenimportdateien, kürzt er die Liste der Fehler und Warnungen ab einer bestimmten Länge. Die vollständige Liste lässt sich per Mail zuschicken. Konfigurieren Sie das in der shop.config des ersten Subshops.

Beispieldateien

Zur Dokumentation gehören mehrere Beispielverzeichnisse:

Verzeichnis	Inhalt
`Complete`	Legt die Kunden Müller und Maier neu in der Kundendatenbank an
`Update`	Weist dem Kunden Schulze, der sich selbst im Shop registriert und den UserIndex 123 erhalten hat, eine Kundennummer zu und vergibt ExternalIDs für Adressen und Bankverbindung. Das ist das einzige Beispiel, in dem das Feld `TableIndex` verwendet wird.
`Delta`	Fügt dem Kunden Müller eine Lieferadresse hinzu, löscht eine Bankverbindung und ändert die Rechnungsadresse
`Delete`	Löscht den Kunden Müller samt Adressen und Bankverbindungen
`Orderquantity`	Anlegen und Löschen kundenabhängiger minimaler und maximaler Bestellmengen

Die Beispieldateien erhalten Sie von Ihrem WEBSALE-Ansprechpartner.

​Die drei Übertragungswege

​Format und Zeichensatz

​Zeichensatzkonvertierung

​Begrüßungsmails für Neukunden

​Passwortänderung beim ersten Login erzwingen

​Gelöschte Zugänge

​Fehlercodes

​Fehler-Mails beim Import über den WSPManager

​Beispieldateien

​Verwandte Themen