Allgemeines

Diese Dokumentation beschreibt die Übertragungsweise der REST-Schnittstelle für den Import von

• Produkt- und Kategoriedaten

• Kundendaten

• Gutscheindaten

SFTP-Übertragung

Die Importdateien selbst müssen zuvor per SFTP auf den Shop-Server übertragen werden. Sie erhalten hierzu von der WEBSALE AG einen gemeinsamen SFTP-Account für Produkt-, Kunden- und Gutscheindaten.

Import von Produktdaten

Übertragen Sie die Importdateien in das Unterverzeichnis „directimport“ auf dem Shop-Server und in entsprechende Unterverzeichnisse.

Beispiel für die PRD-Datei “100721.prd“, die sich im Verzeichnis “Deutsch_184.prd“ des Subshop-Verzeichnisses “Deutsch“ befindet:
../directimport/Deutsch/Deutsch_184.prd/100721.prd

Starten Sie dann den Import über das REST-Interface. Wenn das Verzeichnis nicht existiert, dann müssen Sie es anlegen. Als „scope“ (siehe unten) wird „products“ gesendet. Format und Inhalt der Importdateien werden in der Dokumentation WS-SFTP-Produkte PRO beschrieben.

Import von Kundendaten

Übertragen Sie die Importdateien in das Unterverzeichnis „customerimport“ auf dem Shop-Server und starten Sie dann den Import über das REST-Interface. Wenn das Verzeichnis nicht existiert, dann müssen Sie es anlegen. Als „scope“ (siehe unten) wird „customers“ gesendet. Format und Inhalt der Importdateien werden in der Dokumentation WS-SFTP-Kunden PRO beschrieben.

Import von Gutscheindaten

Übertragen Sie die Importdateien in das Unterverzeichnis „voucherimport“ auf dem Shop-Server und starten Sie dann den Import über das REST-Interface. Als „scope“ (siehe unten) wird „vouchers“ gesendet. Format und Inhalt der Importdateien werden in der Dokumentation WS-SFTP-Gutscheindaten (to-Shop) beschrieben.

Authentifizierung

Die Authentifizierung bei den Funktionen dieser API erfolgt durch ein „Web Token“, das bei jedem Aufruf im HTTP-Header übergeben werden muss.

Um dieses Token zu erhalten, muss man sich mit dem folgenden Aufruf authentifizieren:

Action: POST
URL: https://www.websale.de/api/authent/login/<Shop-ID>
Request-Body: Login-ID und Passwort als JSON-Objekt
Beispiel:

Die Antwort auf diesen Request enthält im Erfolgsfall ein JSON-Objekt mit dem benötigten Token:

Dieser Token muss bei allen folgenden Aufrufen im HTTP-Header mitgeschickt werden:
X-Authorization: Bearer TOKEN

Starten des Imports (start)

Das Kommando „Start“ startet den Import und liefert eine Import-ID zurück, mit der sich danach der Status des Imports abfragen lässt.

Action: POST
URL: https://www.websale.de/api/import/start
Folgende Parameter werden im Body als JSON-Objekt übergeben:

Beispiel-Request-Body:

Beispiel-Response:

Im Erfolgsfall gibt die Funktion ein JSON-Objekt mit der Import-ID zurück, die für die Abfrage des Import-Status nötig ist.

Dass der Import erfolgreich gestartet wurde bedeutet nicht, dass auch erfolgreich Daten importiert wurden. Der Start des Imports erfolgt asynchron, d. h. die REST-Funktion kehrt zurück, bevor sich der Import beendet hat. Ob die Importdaten erfolgreich verarbeitet werden konnten, lässt sich zu diesem Zeitpunkt noch nicht feststellen.

Abfrage des Import-Status (status)

Dieses Kommando erlaubt es abzufragen, ob der Importprozess noch läuft, wie weit er fortgeschritten ist und welches Ergebnis (erfolgreich/abgebrochen) der Import hatte.

Action: GET
URL: https://www.websale.de/api/import/status/<Import-ID>
Im Erfolgsfall werden die Status-Informationen als JSON-Objekt im Body der Response übermittelt.

Felder, die in jedem Fall zurück geliefert werden:

Felder die nur zurück geliefert werden, wenn der Import beendet ist:

Beispiel 1:

Beispiel 2:

Fehlerbehandlung

Fehler bei der Authentifizierung

Fehler beim Starten des Imports oder bei der Abfrage des Status

Zusätzlich zum HTTP-Statuscode kann bei diesen Fehlern im Body ein JSON-Objekt mit weiteren Informationen zum Fehler mitgeschickt werden.

Beispiel für Zusatzinformationen im Body der Response:

„error“ enthält einen „Fehler-Code“, der für die Auswertung durch das aufrufende Programm gedacht ist. Für einen HTTP-Statuscode kann es mehrere „error“ Codes geben.

„detail“ enthält eine Fehlermeldung, die etwas ausführlicher ist als „error“ und die für einen menschlichen Leser gedacht ist.

„paramErrors“ ist ein Spezialparameter, der nur bei dem Fehler „invalidParams“ zurückgegeben wird. Der Wert des Parameters ist ein Objekt, jedes Feld innerhalb dieses Objektes entspricht einem ungültigen Parameter, der an die REST-Schnittstelle geschickt wurde. Für jedes Feld kann es mehrere Fehler geben, deshalb ist der Wert dieses Feldes ein Array. Jeder Eintrag des Arrays hat mindestens das Feld „kind“, das die Art des Fehlers angibt. Je nach „kind“ kann es noch weitere Felder mit zusätzlichen Informationen zu dem Fehler geben.

Fehler, die über die „status“-Funktion zurückgegeben werden

Allgemeine Bemerkungen zu „Fehlern“ und „Warnungen“

(Schwere) Fehler haben zur Folge, dass es keine andere Möglichkeit gibt, als den Import abzubrechen bzw. er gar nicht erst gestartet werden kann.
So ein Fall liegt z. B. vor, wenn in einer Produkt-Importdatei die Spalte mit dem Pflichtfeld „ProdIndex“ komplett fehlt.
(Minder schwere) Fehler führen dazu, dass einzelne Datensätze nicht importiert werden können.

Das passiert z. B., wenn in einer Produkt-Importdatei die Spalte „ProdIndex“ zwar vorhanden ist, aber für einzelne Produkte keinen Wert enthält.
Es gäbe auch in diesem Fall im Prinzip gute Argumente dafür, den Import abzubrechen und die Daten gar nicht einzulesen, schließlich wird das Ergebnis des Imports offensichtlich nicht dem beabsichtigten Ergebnis entsprechen. Die Erfahrung hat aber gezeigt, dass es den meisten Kunden wichtiger ist, dass der Import durchläuft, als dass 100 % aller Produkte/Kunden importiert wurden.

Warnungen treten auf, wenn Importdaten nicht der Spezifikation entsprechen, der Import sie aber trotzdem mit hoher Wahrscheinlichkeit richtig interpretiert und eingelesen hat.

Beispiel: Als Produktpreis wird der Wert „0,99“ importiert. Dieser Wert entspricht nicht der Spezifikation, weil statt eines Punktes ein Komma als Dezimaltrenner verwendet wird. Der Import wird in diesem Fall das Komma durch einen Punkt ersetzen und eine Warnung loggen.

Fehler beim Kundendatenimport:

Datenimport aus verschiedenen Systemen

Im Prinzip ist es möglich, z. B. die Produktdaten von einem System aus zu importieren und Kundendaten von einem anderen System aus. Es muss dabei jedoch sichergestellt sein, dass Übertragung und Import nicht gleichzeitig erfolgen. Jeder Versuch, einen Import zu starten, während bereits ein anderer Import läuft, führt zu einem "EI002 Import läuft bereits"-Fehler.

Kritischer als der Start des Imports ist die Übertragung der Daten, da diese per SFTP erfolgt und keine Trennung der Importverzeichnisse für verschiedene Systeme vorgesehen ist. Dass die Übertragung per SFTP erfolgt bedeutet, dass eine gleichzeitige Übertragung von verschiedenen Systemen aus durch die Import-Software nicht verhindert werden kann.

Dass die Importverzeichnisse nicht getrennt sind bedeutet, dass ein System eventuell den Import von Daten startet, die ein anderes System übertragen hat.

URL

Die derzeitige Basis-URL zum Aufruf der REST-Schnittstelle für den Import lautet

https://www.websale.de/api/...

Die URL kann sich in Zukunft ändern, stellen Sie also sicher, dass sie sich bei Ihnen ohne größeren Aufwand ändern lässt.