SFTP-SOAP-to-Shop (DE)
- René Meyer
- Rainer Biedermann
Allgemeines
Diese Dokumentation beschreibt die Übertragungsweise der SOAP-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 SFTP-Account. Einen gemeinsamen SFTP-Account für Kunden- und Gutscheindaten. Einen separaten SFTP-Account für Produktdaten.
Import von Produktdaten
Übertragen Sie die Importdateien in das Unterverzeichnis „directimport“ auf dem Shop-Server und starten Sie dann den Import über das SOAP-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 Format und Inhalt - WS-SFTP-Produkte PRO (DE) beschrieben.
Bitte beachten Sie:
Bevor Produkt- oder Kategoriedaten importiert werden können, müssen die benötigten Subshops und freien Felder mit Hilfe des WSPManagers angelegt werden.
Import von Kundendaten
Übertragen Sie die Importdateien in das Unterverzeichnis „customerimport“ auf dem Shop-Server und starten Sie dann den Import über das SOAP-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 Format und Inhalt - WS-SFTP-Kunden PRO (DE) beschrieben.
Import von Gutscheindaten
Übertragen Sie die Importdateien in das Unterverzeichnis „voucherimport“ auf dem Shop-Server und starten Sie dann den Import über das SOAP-Interface. Als „Scope“ (siehe unten) wird „Vouchers“ gesendet. Format und Inhalt der Importdateien werden in der Dokumentation Format und Inhalt - WS-SFTP-Gutscheindaten (to-Shop) (DE) beschrieben.
Starten des Imports (StartImport)
Das Kommando „StartImport“ startet den Import und liefert eine SessionID zurück, die für Folgeaufrufe dient. Der Import startet asynchron. Mittels der Funktion „GetProgress“ fragen Sie den Fortschritt des Importes ab. Mittels „GetResult“ wird eine Fehlerliste gesendet.
Der Import läuft noch, wenn GetProgress „Finished=false“ liefert.
Der Import ist beendet, wenn GetProgress „Finished=true“ liefert. Anschließend wird mit „GetResult“ eine Fehlerliste angefordert um zu prüfen, ob alle Datensätze korrekt importiert wurden.
Anfrageparameter
Name | Beschreibung |
|---|---|
ShopID | Die ID des Shops für den der Import gestartet werden soll |
Password | Das Passwort für den Dienst |
Scope | Erlaubt es den Import auf bestimmte Dateien einzuschränken „All“ oder leer: Alle auf dem Server liegende Dateien „Products“: Nur Produkte importieren „Customers“: Nur Kundendaten importieren „Vouchers“: Nur Gutscheindaten importieren Es können mehrere Angaben in einer kommagetrennten Liste kombiniert werden, z.B. „Products,Vouchers“ |
Beispiel:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:StartImport>
<request>
<ShopID>testshop</ShopID>
<Password>xyz</Password>
<Scope>All</Scope>
</request>
</ns:StartImport>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Ausgabeparameter
Name | Beschreibung |
|---|---|
SessionID | Die Session-ID für Folgeaufrufe. |
Beispiel für Antwort des Servers:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:StartImportResponse>
<response>
<SessionID>123</SessionID>
</response>
</ns:StartImportResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Abfrage des Fortschritts (GetProgress)
Dieses Kommando erlaubt es abzufragen, ob der Importprozess noch läuft und wie weit er fortgeschritten ist.
Eingabeparameter
Name | Beschreibung |
|---|---|
ShopID | Die ID des Shops |
Password | Das Passwort für den Dienst |
SessionID | Die von „StartImport“ gelieferte SessionID |
Beispiel:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns="http://www.websale-ag.com/AIPController">
<SOAP-ENV:Body>
<ns:GetProgress>
<request>
<ShopID>testshop</ShopID>
<Password>xyz</Password>
<SessionID>123</SessionID>
</request>
</ns:GetProgress>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Ausgabeparameter
Name | Beschreibung |
Finished | „true“ wenn der Import beendet ist, ansonsten „false“. |
Progress | Eine Zahl von 0 bis 100 die den Fortschritt des Imports angibt. „Progress“ kann den Wert „100“ haben, obwohl der Import noch läuft, fragen Sie deshalb „Finished“ ab, wenn Sie wissen wollen ob der Prozess beendet ist. |
Beispiel:
Abfrage von importierten Neukunden (GetAddedCustomers)
Mit diesem Kommando können die Key-Felder UserIndex, CustomerId und EMail für die erfolgreich angelegten Neukundendatensätze abgefragt werden. Besonders die Abfrage des UserIndexes ist wichtig, da dieses Key-Feld für die Adressierung bei allen folgenden Updates verwendet werden muss.
Eingabeparameter
Name | Beschreibung |
|---|---|
ShopID | Die ID des Shops |
Password | Das Passwort für den Dienst |
SessionID | Die von „StartImport“ gelieferte SessionID |
Beispiel:
Ausgabeparameter
Name | Beschreibung |
|---|---|
Customers | Eine Liste der neu angelegten Kundendatensätze |
Customer | Ein Datensatz mit den Daten eines Kunden |
UserIndex | Der vom Shopsystem vergebene UserIndex |
CustomerID | Die in den Importdaten angegebene Kundennummer |
Die in den Importdaten angegebene eMail-Adresse |
Beispiel:
Abfrage von Fehlern und Warnungen (GetResult)
Mit diesem Kommando können die während des Imports aufgetretenen Warnungen und Fehler abgefragt werden. Dieses Kommando sollte erst aufgerufen werden, nachdem der Prozess beendet ist, also GetProgress „Finished=true“ zurückgeliefert hat.
Als Antwort auf dieses Kommando liefert der Server eine Liste von Fehlern und Warnungen. Werden Fehler zurückgeliefert, so wurde der Import abgebrochen. Werden Warnungen geliefert, aber keine Fehler, so konnte der Import zwar abgeschlossen werden, aber Teile der Daten konnten nicht fehlerfrei importiert werden.
Eingabeparameter
Name | Beschreibung |
|---|---|
ShopID | Die ID des Shops |
Password | Das Passwort für den Dienst |
SessionID | Die von „StartImport“ gelieferte SessionID |
Beispiel:
Ausgabeparameter
Name | Beschreibung |
|---|---|
Errors | Eine Liste der aufgetretenen Fehler |
Warnings | Eine Liste der aufgetretenen Warnungen |
Beispiel:
Fehlerbehandlung
Bei dieser SOAP-Schnittstelle ist zwischen zwei Typen von Fehlern zu unterscheiden:
Fehler die beim Import auftreten
Fehler beim Aufruf von SOAP-Kommandos
Fehler der Kategorie (1) fragen Sie nach Ende des Imports mit „GetResult“ ab.
Bei Nutzung der SOAP-Schnittstelle können zusätzlich zu den „normalen“ Importfehlern folgende Fehler auftreten:
Fehlermeldung | Beschreibung |
|---|---|
EI001 Keine Importdaten vorhanden | Auf dem Shop-Server sind keine Importdaten vorhanden. |
EI002 Import läuft bereits | Für den Shop läuft bereits ein Importprozess. |
EI003 Ein anderer Prozess greift bereits auf die Shopdaten zu | Ein anderer Prozess schreibt oder liest bereits Produktdaten des Shops. Um Inkonsistenzen bei den Daten zu vermeiden kann deshalb kein Import gestartet werden. Folgende Prozesse können diese Meldung verursachen: Export von Daten durch den PricePush Feed Engine Datenübertragung durch den WSPManager Aktualisierung von Glossardaten |
EI004 Artikelimport Pro nicht freigeschaltet | Für den Shop ist der Artikelimport Pro nicht freigeschaltet |
EI005 Ungueltige Shop Version (VX erforderlich) | Der Import ist zwar freigeschaltet, aber das aufgerufene SOAP-Interface passt nicht zur Version des Shops (z.B. V7 statt V8) |
EI006 Kundendatenübertragung nicht freigeschaltet | Der Import ist zwar freigeschaltet, aber die Übertragung von Kundendaten ist nicht eingerichtet. |
EI007 Interner Fehler | Der Import wurde aufgrund eines Ausnahmefehlers abgebrochen. Versuchen Sie es später nochmal oder setzen Sie sich mit der WEBSALE AG in Verbindung. |
Fehler der Kategorie (2) werden als „SOAP Faults“ in der Antwort des Servers zurückgegeben. Folgende Fehler der zweiten Kategorie können auftreten:
Fehlermeldung | Beschreibung |
|---|---|
ES001 Fehlende ShopID oder Passwort | In dem geschickten Kommando fehlt der Parameter „ShopID“ oder der Parameter „Password“ |
ES002 Ungültige ShopID oder ungültiges Passwort | Das Kommando enthielt zwar „ShopID“ und „Password“ Parameter, aber es existiert kein passender Shop oder das Passwort ist falsch. |
ES003 Fehlende SessionID | Ein „GetProgress“ oder „GetResult“ Kommando wurde mit leerer SessionID geschickt. |
ES004 Ungültige SessionID | Die mit einem „GetProgress“ oder „GetResult“ Kommando geschickte SessionID ist ungültig, z.B. weil vorher kein „StartImport“ aufgerufen wurde. |
ES005 Fehler bei Server-Initialisierung | Bei der Initialisierung des Soap-Servers trat ein Fehler auf. Versuchen Sie es später nochmal oder setzen Sie sich mit der WEBSALE AG in Verbindung. |
ES006 Import läuft noch | Beim Aufruf von “GetResult” war der Import noch nicht beendet. |
ES007 SSL erforderlich | Der Aufruf des Programms muss über eine verschlüsselte Verbindung erfolgen, ein Aufruf mit einer normalen “http” URL ist nicht zulässig. |
ES008 Falsche Shop-Version | Es wurde das SOAP-Interface für die V8-Version eines Shops aufgerufen, aber es existiert kein V8-Shop. |
ES009 Ungültiger Scope | In dem Scope-Feld wurde ein ungültiger Wert übergeben |
Fehler beim Kundendatenimport:
Fehlermeldung | Beschreibung |
|---|---|
EC001 | Weder 'UserIndex' noch 'CustomerID' vorhanden |
EC002 | Weder 'TableIndex' noch 'ExternalID' vorhanden |
EC003 | Sowohl 'CustomerID' als auch 'UserIndex' sind leer |
EC004 | Sowohl 'ExternalID' als auch 'TableIndex' sind leer |
EC005 | 'CustomerID' und 'UserIndex' leer oder nicht in der Datenbank vorhanden |
EC006 | Der angegebene TableIndex ist bereits vergeben |
EC007 | Datensatz ohne eMail-Adresse |
EC008 | eMail-Adresse wird bereits verwendet |
EC009 | 'CustomerID' wird bereits verwendet |
EC010 | CharsetImport ohne CharsetShop wird ignoriert |
EC011 | CharsetShop ohne CharsetImport wird ignoriert |
EC012 | Datensatz konnten nicht fehlerfrei in den Zielzeichensatz konvertiert werden |
EC013 | Ungültiger Zeichensatz |
EC014 | Es sind sowohl verschlüsselte als auch mit SFTP übertragene Daten vorhanden |
EC015 | Feld 'UserIndex' nicht vorhanden |
EC016 | UserIndex ... existiert nicht |
EC017 | TableIndex wurde ersetzt |
EC018 | Mehr als eine Rechnungsadresse vorhanden |
EC019 | In der Datei fehlt das Pflichtfeld ... |
EC020 | Das Pflichtfeld ... ist leer |
EC021 | Ungueltiger Datentyp ... im Feld ... |
Beispieldateien
Folgende Beispieldateien sind Teil dieser Dokumentation, die Sie auf der untergeordneten Seite zum Download finden.
Dateiname | Beschreibung |
|---|---|
startrequest.xml | Beispiel für ein „StartImport“ Kommando |
startresponse.xml | Antwort des Servers auf ein „Startimport“ Kommando |
getprogressrequest.xml | Beispiel für ein „GetProgress“ Kommando |
getprogressresponse.xml | Antwort des Servers auf ein „GetProgress“ Kommando |
getresultrequest.xml | Beispiel für ein „GetResult“ Kommando |
getresultresponse.xml | Antwort des Servers auf ein „GetResult“ Kommando |
getaddedcustomersrequest.xml | Beispiel für ein „GetAddedCustomers“ Kommando |
getaddedcustomersresponse.xml | Antwort des Servers auf ein „GetAddedCustomers“ Kommando |
fault.xml | Beispiel für eine Fehlermeldung als Antwort auf ein „StartImport“ Kommando mit ungültigen Zugangsdaten |
WSDL (Web Services Description Language)
Auf der untergeordneten Seite finden Sie eine WSDL Datei (AIPController.wsdl) zum Download, die Sie nutzen können, um den Code zur Anbindung der Schnittstelle (zumindest teilweise) automatisiert zu erstellen. Voraussetzung dafür ist, dass es für die von Ihnen verwendete Programmiersprache ein passendes Tool gibt.
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 erfolgt. 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 URL zum Aufruf der SOAP-Schnittstelle für den Import lautet
https://secure.c1.websale.net/cgi/aipsoaptrigger/aipsoaptrigger.cgi
Die URL kann sich in Zukunft ändern, stellen Sie also sicher, dass sie sich bei Ihnen ohne größeren Aufwand ändern lässt.