SOAP-from-Shop

SOAP-from-Shop holt Daten aus dem Shop ab: Bestellungen, Anfragen aus INQUIRY4-Formularen, Adressdatenänderungen und Gutscheindaten. Alle vier folgen demselben Muster, deshalb lohnt es sich, dieses Muster einmal zu verstehen und danach nur noch die Unterschiede nachzuschlagen.

Eigenschaft	Wert
Übertragungsrichtung	WEBSALE Shop → Warenwirtschaft (Data-from-Shop)
Übertragungsart	SOAP
Formate	XML, WSDL
Zeichensatz	UTF-8

Der Webservice ist ausschließlich über SSL erreichbar. Unverschlüsselte Verbindungen lehnt er ab.

Das Abrufmuster

Jeder Abruf besteht aus zwei Schritten: Das externe System schickt einen Request, das WEBSALE-System antwortet mit den angeforderten Daten. Damit kein Datensatz doppelt oder gar nicht ankommt, muss das externe System zwei Dinge leisten: Es übergibt bei jedem Aufruf ShopID und Passwort, und es merkt sich die zuletzt empfangene Datensatznummer.

Erster Abruf gegen laufenden Betrieb

Beim allerersten Abruf gibt es noch keine gemerkte Nummer. Der Request nennt dann Datum und Uhrzeit, ab denen gelesen werden soll, und setzt SkipFirstMatch auf false. Im laufenden Betrieb übergeben Sie stattdessen die zuletzt empfangene Nummer und setzen SkipFirstMatch auf true. Die Übertragung beginnt dann mit dem darauf folgenden Datensatz, der bereits verarbeitete wird also nicht erneut geliefert. Einen einzelnen Datensatz holen Sie, indem Sie seine Nummer übergeben, das jeweilige Max…Count-Feld auf 1 setzen und SkipFirstMatch auf false lassen. Enthält ein Request sowohl eine Datensatznummer als auch Datum und Uhrzeit, gewinnt die Nummer. Datum und Uhrzeit werden dann ignoriert.

Blättern, bis Finished true ist

Liegen mehr Datensätze vor, als Sie angefordert haben, liefert die Antwort Finished=false. In diesem Fall wiederholen Sie den Request mit der zuletzt empfangenen Nummer, bis Finished auf true steht. Wer diese Schleife weglässt, holt bei hohem Aufkommen dauerhaft nur den jeweils ersten Block ab und merkt es nicht, weil kein Fehler auftritt. Pro Aufruf lassen sich maximal 1000 Datensätze abrufen, voreingestellt sind 100.

Die vier Kommandos im Vergleich

Daten	Kommando	Nummernfeld	Mengenfeld	Format und Inhalt
Bestellungen	`GetOrders`	`OrderNumber`	`MaxOrderCount`	WS-Bestelldaten
Anfragen	`GetInquiries`	`InquiryNumber`	`MaxInquiryCount`	WS-Anfragedaten
Adressänderungen	`GetAddresses`	`AddressNumber`	`MaxAddressCount`	WS-Adressdatenänderungen
Gutscheindaten	`GetVouchers`	`VoucherNumber`	`MaxVoucherCount`	WS-Gutscheindaten (from-Shop)

Parameter des Requests

Diese Parameter gelten für alle vier Kommandos:

Parameter	Beschreibung	Pflichtfeld
`ShopID`	Die Shop-ID	ja
`Password`	Passwort für die SOAP-Schnittstelle, das Sie von der WEBSALE AG erhalten	ja
`Date`	Datum im Format `YYYY-MM-DD`, ab dem übertragen werden soll	bei Bestellungen nur, wenn das Nummernfeld fehlt. Bei Anfragen und Adressänderungen immer. Bei Gutscheinen optional.
`Time`	Uhrzeit im Format `HH:MM:SS`, ab der übertragen werden soll	nein
`MsgID`	Beliebige Kennung, die das WEBSALE-System unverändert in der Antwort zurückgibt. Für die Verarbeitung ohne Bedeutung, aber nützlich, um Antwort und Request in Protokollen zuzuordnen.	nein
`SkipFirstMatch`	`true` beginnt mit dem Datensatz nach dem übergebenen, `false` beginnt mit dem übergebenen	ja

Nur bei GetOrders kommt ein weiterer Parameter hinzu:

Parameter	Beschreibung	Pflichtfeld
`SubshopIDs`	Kommagetrennte Liste der SubshopIDs, deren Bestellungen abgerufen werden sollen. Ist die Liste leer oder fehlt der Parameter, kommen die Bestellungen aller Subshops.	nein

Serverseitig kann der Zugriff auf bestimmte Subshops eingeschränkt sein. Steht in der Liste ein Subshop, der nicht freigeschaltet ist, bricht die Übertragung mit ES013 ab. Beispiel: maximal 100 Bestellungen abrufen, die seit dem 11.05.2013 um 11:00 Uhr eingegangen sind:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns="http://www.websale.de/">
  <SOAP-ENV:Body>
    <ns:GetOrders>
      <request>
        <ShopID>testshop</ShopID>
        <Password>xyz</Password>
        <Date>2013-05-11</Date>
        <Time>11:00:00</Time>
        <MaxOrderCount>100</MaxOrderCount>
        <SkipFirstMatch>false</SkipFirstMatch>
      </request>
    </ns:GetOrders>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parameter der Antwort

Die Antwort ist bei allen vier Kommandos gleich aufgebaut. Ein Sammelelement enthält je Datensatz ein Einzelelement, dieses wiederum Datum, Uhrzeit, Nummer und die eigentlichen Nutzdaten als XML.

Parameter	Beschreibung
`Finished`	`true`, wenn alle vorliegenden Datensätze gesendet wurden. `false` bedeutet, dass ein erneuter Request nötig ist.
`…Count`	Anzahl der gesendeten Datensätze, beispielsweise `OrderCount`
`Orders`, `Inquiries`, `Addresses`, `Vouchers`	Sammelelement mit je einem Einzelelement pro Datensatz
`Order`, `Inquiry`, `Address`, `Voucher`	Einzelelement mit `Date`, `Time`, der Nummer und den Nutzdaten
`…Data`	Die eigentlichen Daten im XML-Format, beispielsweise `OrderData`
`MsgID`	Die im Request übergebene MsgID

Bei GetOrders kommt SubshopIDs hinzu. Das Feld wird zurückgegeben, wenn im Request SubshopIDs gesetzt waren oder die Shop-Konfiguration das Abholen auf bestimmte Subshops einschränkt. Es enthält dann die Liste der SubshopIDs, für die Bestelldaten abgerufen werden können. Bei Gutscheinen beziehen sich Date und Time auf den Zeitpunkt der Generierung des Gutscheins, nicht auf eine Bestellung.

Fehlerbehandlung

Tritt ein Fehler auf, antwortet die Schnittstelle mit einem SOAP Fault:

<SOAP-ENV:Fault>
  <faultcode>SOAP-ENV:Client</faultcode>
  <faultstring>ES007 SSL erforderlich</faultstring>
</SOAP-ENV:Fault>

Fehlermeldung	Beschreibung
`ES001 Fehlende ShopID oder Passwort`	Im Request fehlt `ShopID` oder `Password`. Aus Sicherheitsgründen wird nicht genauer unterschieden.
`ES002 Ungültige ShopID oder ungültiges Passwort`	Beide Parameter waren vorhanden, aber es existiert kein passender Shop, das Passwort ist falsch oder die Schnittstelle ist für den Shop nicht freigeschaltet. Auch hier wird aus Sicherheitsgründen nicht genauer unterschieden.
`ES005 Fehler bei Server-Initialisierung`	Bei der Initialisierung des SOAP-Servers trat ein Fehler auf. Versuchen Sie es später erneut. Hält der Fehler länger als 30 Minuten an, wenden Sie sich an die WEBSALE AG.
`ES007 SSL erforderlich`	Der Aufruf muss über eine verschlüsselte Verbindung erfolgen.
`ES008 Falsche Shop-Version`	Das aufgerufene SOAP-Interface passt nicht zur Version des Shops.
`ES009 Fehlendes Pflichtfeld`	Ein Pflichtfeld im Request fehlt oder ist leer.
`ES010 Ungültige Datensatz-ID`	Die übergebene Nummer existiert im WEBSALE-System nicht oder nicht für das angegebene Datum.
`ES011 Datum fehlt`	Bei Anfragen und Adressdatenänderungen ist zusätzlich zur Datensatz-ID ein Datum erforderlich.
`ES012 Formatfehler`	Ein Feld mit vorgegebenem Format, beispielsweise `Date` oder `Time`, hat einen falschen Aufbau.
`ES013 Subshop nicht freigeschaltet`	In `SubshopIDs` stand ein Subshop, für den das Abholen von Bestelldaten nicht freigeschaltet ist.
`ES014 Ungültiger MaxCount-Wert`	Mehr als 1000 Datensätze je Aufruf sind nicht möglich. `0` und negative Werte sind ebenfalls unzulässig.
`ES015 Ungültiger Request`	Das SOAP-Framework konnte den eingehenden Request nicht verarbeiten.
`ES016 Plugin-Fehler`	Eine Bestellung konnte durch ein Konvertierungs-Plugin nicht bearbeitet werden.

WSDL-Dateien und Server-URLs

Zu jedem der vier Abrufe gehört eine eigene WSDL-Datei: order.wsdl, inquiry.wsdl, address.wsdl und voucher.wsdl. Damit lässt sich der Anbindungscode je nach Programmiersprache automatisiert erzeugen. Die WSDL-Dateien und die URLs des SOAP-Servers erhalten Sie von Ihrem WEBSALE-Ansprechpartner.

Schnittstellen

Das Abrufmuster

Erster Abruf gegen laufenden Betrieb

Blättern, bis Finished true ist

Die vier Kommandos im Vergleich

Parameter des Requests

Parameter der Antwort

Fehlerbehandlung

WSDL-Dateien und Server-URLs

Verwandte Themen

​Das Abrufmuster

​Erster Abruf gegen laufenden Betrieb

​Blättern, bis Finished true ist

​Die vier Kommandos im Vergleich

​Parameter des Requests

​Parameter der Antwort

​Fehlerbehandlung

​WSDL-Dateien und Server-URLs

​Verwandte Themen

Das Abrufmuster

Erster Abruf gegen laufenden Betrieb

Blättern, bis Finished true ist

Die vier Kommandos im Vergleich

Parameter des Requests

Parameter der Antwort

Fehlerbehandlung

WSDL-Dateien und Server-URLs

Verwandte Themen