SFTP-SOAP-to-Shop

SFTP-SOAP-to-Shop importiert Produkte und Kategorien, Kundendaten und Gutscheindaten in den Shop. Der Ablauf gleicht dem von SFTP-REST-to-Shop: Die Dateien gehen per SFTP auf den Shop-Server, der Import wird anschließend über die Schnittstelle gestartet. Der Unterschied liegt in der Technik des Aufrufs und in einem Detail, das für die Praxis zählt: Der Scope lässt sich hier kombinieren.

Eigenschaft	Wert
Übertragungsrichtung	Warenwirtschaft → WEBSALE Shop (Data-to-Shop)
Übertragungsart	SFTP, SOAP
Formate	CSV für die Importdateien, XML für die SOAP-Kommandos

Dateien per SFTP übertragen

Für diese Schnittstelle erhalten Sie von der WEBSALE AG zwei SFTP-Accounts: einen gemeinsamen für Kunden- und Gutscheindaten und einen separaten für Produktdaten.

Datenart	Verzeichnis	Wert für `Scope`	Format und Inhalt
Produkte und Kategorien	`directimport`	`Products`	WS-SFTP-Produkte PRO
Kundendaten	`customerimport`	`Customers`	WS-SFTP-Kunden PRO
Gutscheindaten	`voucherimport`	`Vouchers`	WS-SFTP-Gutscheindaten (to-Shop)

Existiert ein Verzeichnis nicht, legen Sie es an. Bevor Produkt- oder Kategoriedaten importiert werden können, müssen die benötigten Subshops und freien Felder mit dem WSPManager angelegt sein.

Der Ablauf in vier Kommandos

StartImport startet den Import und liefert eine SessionID. Der Import läuft asynchron weiter, das Kommando kehrt also sofort zurück. Danach fragen Sie mit GetProgress den Fortschritt ab. Solange Finished den Wert false hat, läuft der Import noch. Erst wenn Finished auf true steht, fordern Sie mit GetResult die Fehlerliste an und prüfen, ob alle Datensätze korrekt importiert wurden. Haben Sie Kundendaten importiert, holen Sie mit GetAddedCustomers zusätzlich die Schlüsselfelder der neu angelegten Kunden ab.

StartImport

Anfrageparameter:

Name	Beschreibung
`ShopID`	ID des Shops, für den der Import gestartet werden soll
`Password`	Passwort für den Dienst
`Scope`	Schränkt den Import auf bestimmte Dateien ein. `All` oder leer importiert alle auf dem Server liegenden Dateien, `Products`, `Customers` und `Vouchers` jeweils nur diese Datenart. Mehrere Angaben lassen sich kommagetrennt kombinieren, beispielsweise `Products,Vouchers`.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 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 ist die SessionID für alle Folgeaufrufe:

<ns:StartImportResponse>
 <response>
  <SessionID>123</SessionID>
 </response>
</ns:StartImportResponse>

GetProgress

Eingabeparameter sind ShopID, Password und die SessionID aus StartImport.

Ausgabeparameter	Beschreibung
`Finished`	`true`, wenn der Import beendet ist, sonst `false`
`Progress`	Zahl von 0 bis 100 für den Fortschritt

Progress kann bereits 100 erreichen, während der Import noch läuft. Für die Frage, ob der Prozess beendet ist, zählt deshalb ausschließlich Finished. Wer stattdessen auf Progress pollt, ruft GetResult zu früh auf und erhält den Fehler ES006 Import läuft noch.

<ns:GetProgressResponse>
 <response>
  <Finished>true</Finished>
  <Progress>100</Progress>
 </response>
</ns:GetProgressResponse>

GetAddedCustomers

Liefert für jeden erfolgreich angelegten Neukunden die Schlüsselfelder. Eingabeparameter sind ShopID, Password und SessionID.

Ausgabeparameter	Beschreibung
`Customers`	Liste der neu angelegten Kundendatensätze
`Customer`	Ein einzelner Kundendatensatz
`UserIndex`	Der vom Shopsystem vergebene UserIndex
`CustomerID`	Die in den Importdaten angegebene Kundennummer
`EMail`	Die in den Importdaten angegebene E-Mail-Adresse

Den UserIndex sollten Sie in jedem Fall abholen und in Ihrem System speichern, denn er ist das Schlüsselfeld für die Adressierung bei allen folgenden Updates.

<ns:GetAddedCustomersResponse>
 <response>
  <Customers>
   <Customer>
    <UserIndex>12345</UserIndex>
    <CustomerID>Kundennummer1</CustomerID>
    <EMail>kunde1@irgendwo.de</EMail>
   </Customer>
  </Customers>
 </response>
</ns:GetAddedCustomersResponse>

GetResult

Liefert die während des Imports aufgetretenen Fehler und Warnungen. Rufen Sie das Kommando erst auf, nachdem GetProgress den Wert Finished=true geliefert hat.

Ausgabeparameter	Beschreibung
`Errors`	Liste der aufgetretenen Fehler
`Warnings`	Liste der aufgetretenen Warnungen

Kommen Fehler zurück, wurde der Import abgebrochen. Kommen nur Warnungen zurück, lief der Import durch, einzelne Daten konnten aber nicht fehlerfrei übernommen werden.

<ns:GetResultResponse>
 <response>
  <Errors>Fehler 1</Errors>
  <Warnings>Warnung 1</Warnings>
  <Warnings>Warnung 2</Warnings>
 </response>
</ns:GetResultResponse>

Fehlerbehandlung

Zu unterscheiden sind zwei Arten von Fehlern: solche, die beim Import auftreten, und solche beim Aufruf der SOAP-Kommandos. Die erste Art fragen Sie nach Ende des Imports mit GetResult ab, die zweite kommt als SOAP Fault in der Antwort des Servers zurück.

Fehler beim Import

Fehlermeldung	Beschreibung
`EI001 Keine Importdaten vorhanden`	Auf dem Shop-Server liegen keine Importdaten.
`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 liest oder schreibt bereits Produktdaten. Auslöser können sein: Export durch die 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`	Der Import ist freigeschaltet, aber die aufgerufene Schnittstelle passt nicht zur Version des Shops.
`EI006 Kundendatenübertragung nicht freigeschaltet`	Der Import ist freigeschaltet, aber die Übertragung von Kundendaten ist nicht eingerichtet.
`EI007 Interner Fehler`	Der Import wurde wegen eines Ausnahmefehlers abgebrochen.

Beim Kundendatenimport kommen dieselben Meldungen EC001 bis EC021 hinzu wie bei der REST-Variante. Die Liste steht unter SFTP-REST-to-Shop.

Fehler beim Aufruf der Kommandos

Fehlermeldung	Beschreibung
`ES001 Fehlende ShopID oder Passwort`	Im Kommando fehlt `ShopID` oder `Password`.
`ES002 Ungültige ShopID oder ungültiges Passwort`	Beide Parameter waren vorhanden, es existiert aber kein passender Shop oder das Passwort ist falsch.
`ES003 Fehlende SessionID`	`GetProgress` oder `GetResult` wurde mit leerer SessionID geschickt.
`ES004 Ungültige SessionID`	Die SessionID ist ungültig, beispielsweise weil vorher kein `StartImport` aufgerufen wurde.
`ES005 Fehler bei Server-Initialisierung`	Bei der Initialisierung des SOAP-Servers trat ein Fehler auf.
`ES006 Import läuft noch`	Beim Aufruf von `GetResult` war der Import noch nicht beendet.
`ES007 SSL erforderlich`	Der Aufruf muss über eine verschlüsselte Verbindung erfolgen. Ein Aufruf über `http` ist nicht zulässig.
`ES008 Falsche Shop-Version`	Es wurde das SOAP-Interface für eine Shop-Version aufgerufen, die nicht existiert.
`ES009 Ungültiger Scope`	Im Feld `Scope` wurde ein ungültiger Wert übergeben.

WSDL und Beispieldateien

Zur Schnittstelle gehört eine WSDL-Datei AIPController.wsdl, mit der sich der Anbindungscode je nach Programmiersprache teilweise automatisch erzeugen lässt. Dazu kommen Beispieldateien für jedes Kommando:

Dateiname	Beschreibung
`startrequest.xml`	Beispiel für ein `StartImport`-Kommando
`startresponse.xml`	Antwort des Servers darauf
`getprogressrequest.xml`	Beispiel für ein `GetProgress`-Kommando
`getprogressresponse.xml`	Antwort des Servers darauf
`getresultrequest.xml`	Beispiel für ein `GetResult`-Kommando
`getresultresponse.xml`	Antwort des Servers darauf
`getaddedcustomersrequest.xml`	Beispiel für ein `GetAddedCustomers`-Kommando
`getaddedcustomersresponse.xml`	Antwort des Servers darauf
`fault.xml`	Beispiel für eine Fehlermeldung bei ungültigen Zugangsdaten

WSDL und Beispieldateien erhalten Sie von Ihrem WEBSALE-Ansprechpartner.

Import aus mehreren Systemen

Produktdaten aus einem System und Kundendaten aus einem anderen zu importieren, ist möglich. Übertragung und Import dürfen dabei jedoch nicht gleichzeitig laufen, sonst endet der zweite Start mit EI002 Import läuft bereits. Kritischer als der Start ist die Übertragung selbst. Sie läuft über SFTP, und die Importverzeichnisse sind nicht nach Quellsystem getrennt. Die Import-Software kann deshalb weder eine gleichzeitige Übertragung aus mehreren Systemen verhindern noch erkennen, welches System welche Dateien abgelegt hat. Die Reihenfolge müssen Sie außerhalb des Shops koordinieren.

Schnittstellen

Dateien per SFTP übertragen

Der Ablauf in vier Kommandos

StartImport

GetProgress

GetAddedCustomers

GetResult

Fehlerbehandlung

Fehler beim Import

Fehler beim Aufruf der Kommandos

WSDL und Beispieldateien

Import aus mehreren Systemen

Verwandte Themen

​Dateien per SFTP übertragen

​Der Ablauf in vier Kommandos

​StartImport

​GetProgress

​GetAddedCustomers

​GetResult

​Fehlerbehandlung

​Fehler beim Import

​Fehler beim Aufruf der Kommandos

​WSDL und Beispieldateien

​Import aus mehreren Systemen

​Verwandte Themen

Dateien per SFTP übertragen

Der Ablauf in vier Kommandos

StartImport

GetProgress

GetAddedCustomers

GetResult

Fehlerbehandlung

Fehler beim Import

Fehler beim Aufruf der Kommandos

WSDL und Beispieldateien

Import aus mehreren Systemen

Verwandte Themen