Allgemeines

Diese Dokumentation beschreibt das SOAP-basierte Senden von Info-E-Mails zum WEBSALE-Shopsystem von einem externen System.

Über diese Schnittstelle lassen sich eine oder mehrere (HTML-)E-Mails zu einer Bestellung versenden. Eine typische Anwendung für diese Funktion ist das Versenden von E-Mails, wenn die bestellten Produkte zum Kunden geliefert werden.

Der Inhalt der Mail wird über ein Template vorgegeben, in dem beliebige Daten aus der Bestellung mit eigenen Daten (z. B. Bestellbestätigung, Rechnung, Lieferzeit, Trackingnummer, usw.) kombiniert werden können.

Ausschließlich verschlüsselter Abruf

Der Webservice muss über SSL aufgerufen werden. Unverschlüsselte Verbindungen werden abgelehnt.

UTF-8 Codierung

Alle Daten müssen im UTF-8 Format gesendet werden.

Integration der Bestelldaten in das E-Mail-Template

Für die Bestelldaten werden dafür die „OH-“ Tags verwendet, wie sie auch im Online-Shop für die Bestellhistorie benutzt werden. Siehe dazu die Frontend- und Designer-Dokumentation:

https://doku.websale.net/index.html?guide_funktionen_der_bestellhistorie.html

Zusätzlich zu den in der Frontend- und Designer-Dokumentation beschriebenen „OH-“ Tags stehen für das E-Mail-Template Tags mit dem Präfix „OH-OF-“ und „OH-PF-“ zur Verfügung, mit denen die im SOAP-Request übergebenen Daten eingefügt werden können.

Bitte beachten Sie, dass die „Info-E-Mails“ durch ein externes Modul gesendet werden und daher nicht alle Tags des WEBSALE-Shopsystems unterstützt werden.

Das Template sowie Standardwerte für Betreff und Absender der E-Mails werden in der Shopkonfiguration „shop.config“ eingestellt.

<OrderInfoMail>
  Allow			= yes
  SenderAddress	= MeineFirma@irgendwo.de   # Absender E-Mail-Adresse
  SenderName	= Meine Firma              # Absender-Name
  Subject-Txt	= Ihre Bestellung          # Betreff der E-Mail
  BCC-Address	=                          # optionale, blinde Empfängeradresse
  Template		= mail_orderinfo.htm       # E-Mail-Template
</OrderInfoMail>

Abgesehen von „Allow“ und „BCC-Address“ lassen sich alle Parameter in der SOAP-Message überschreiben. Mit „BCC-Address“ lässt sich die E-Mail zu Kontrollzwecken an eine weitere, blinde E-Mail-Adressen versenden.

Weiterhin ist es möglich, beliebige Dateien (z. B. PDFs) als Mail-Anhang zu versenden.

Die Empfänger-E-Mail und der Name des Empfängers werden automatisch aus den Bestelldaten ermittelt.

Voraussetzung

Das externe System muss bei jedem Aufruf die ShopID und das Passwort übergeben

Übermittlung der Mail-Daten durch das externe System (Schritt 1 „SendOrderInfoMails“)

Parameter	Beschreibung	Pflichtfeld

Parameter	Beschreibung	Pflichtfeld
ShopID	Die Shop-ID	ja
Password	Das Passwort für die SOAP-Schnittstelle. Das Passwort erhalten Sie von der WEBSALE AG.	ja
MsgID	Optional kann das externe System eine MsgID mitgeben, die vom WEBSALE-System in der Antwort zurückgegeben wird. Für die Verarbeitung des Requests hat die MsgID keine Bedeutung.	nein
OrderInfos	Enthält für jede Mail ein „OrderInfo“ Unterelement. Die Zahl der Mails, die mit einem Request versendet werden können ist auf 100 begrenzt.	ja
OrderInfo	Enthält die Daten für den Versand einer einzelnen E-Mail. Alle folgenden Elemente sind Unterelemente von „OrderInfo“	ja, innerhalb von „OrderInfos“
OrderNumber	Die Bestellnummer des Shops.	ja, innerhalb von „OrderInfo“
Subject	Der Betreff der E-Mail. Überschreibt die globale Einstellung in der Datei shop.config.	nein
SenderAddress	Die Absender-Adresse. Überschreibt die globale Einstellung in der Datei shop.config.	nein
SenderName	Der Absender-Name. Überschreibt die globale Einstellung in der Datei shop.config.	nein
Template	Der Inhalt des Mail-Templates. Überschreibt den Inhalt des globalen Templates, das in der Datei shop.config angegeben ist	nein
TemplateName	Name der Template-Datei. Überschreibt die globale Einstellung in der Datei shop.config.	nein
Attachments	Enthält für jede Datei, die als Anhang mit der Mail verschickt werden soll, ein „Attachment“ Element.	nein
Attachment	Enthält die Daten für eine Datei, die mit der Mail verschickt werden soll.	nein
FileName	Der Namen der Attachment-Datei. Wird in der E-Mail als Anhang angezeigt.	ja, innerhalb von „Attachment“
FileData	base64-kodierte Daten der Attachment-Datei.	ja, innerhalb von „Attachment“
OrderFields	Oberelement der „OrderField“ Elemente	nein
OrderField	Mit dem „OrderField“ Elementen lassen sich Tags im Template durch beliebige Werte ersetzen, die sich auf die gesamte Bestellung beziehen. Es werden maximal 100 OrderField-Elemente unterstützt.	nein
Name	Name des Tags im Template ohne die umrahmenden „~“ Zeichen. Im Template muss dem Namen der Präfix „OH-OF-“ vorangestellt werden. Bsp: Wird in der SOAP-Message der Name „ BspTag“ verwendet, so lautet der zugehörige Tag im Template „~OH-OF-BspTag~“. Neben der Ersetzung des Wertes werden auch die Klammerungen {OH-OF-BspTag}…{/OH-OF-BspTag} und {!OH-OF-BspTag}…{/!OH-OF-BspTag} unterstützt, d. h. abhängig davon ob ein Wert gefüllt ist lassen sich Teile des Templates ein- oder ausblenden.	ja, innerhalb von „OrderField“
Value	Der Wert durch den der unter „Name“ angegebene Tag im Template ersetzt werden soll.	ja, innerhalb von „OrderField“
PositionInfos	Enthält Daten, die bei den einzelnen Bestellpositionen angezeigt werden sollen.	nein
PositionInfo	Enthält die Daten, die bei einer einzelnen Bestellposition angezeigt werden sollen. Es werden maximal 100 PositionInfo-Elemente unterstützt.	nein
PositionNumber	Hier muss der Wert des Feldes „PositionNumber“ in den Bestelldaten angegeben werden, auf die sich die in „PositionInfo“ angegebenen Werte beziehen.	ja, innerhalb von „PositionInfo“
PositionFields	Siehe „OrderFields“	nein
PositionField	Siehe „OrderField“	nein
Name	Siehe „OrderField“/„Name“, statt dem Präfix „OH-OF-“ müssen die Tags im Template hier allerdings den Präfix „OH-PF-“ haben.	ja, innerhalb von „PositionField“
Value	Siehe „OrderField“/„Value“	nein

Beispiel für einen SendOrderInfoMails-Request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Body>
		<SendOrderInfoMails xmlns="http://www.websale.de/">
			<request>
				<ShopID>testshop</ShopID>
				<Password>123456</Password>
				<OrderInfo>
					<OrderNumber>137750926502699</OrderNumber>
					<Attachments>
						<Attachment>
							<FileName>testfile.pdf</FileName>
							<FileData>dGVzdCdC1hdHRhY2ht...Rh50DQoxMjM=</FileData>
						</Attachment>
					</Attachments>
					<OrderFields>
						<OrderField>
							<Name>OrderComment</Name>
							<Value>Kommentar zur Bestellung</Value>
						</OrderField>
					</OrderFields>
					<PositionInfos>
						<PositionInfo>
							<PositionNumber>1</PositionNumber>
							<PositionFields>
								<PositionField>
									<Name>ShowItem</Name>
									<Value>X</Value>
								</PositionField>
								<PositionField>
									<Name>TrackingNumber</Name>
									<Value>TNum123</Value>
								</PositionField>
							</PositionFields>
						</PositionInfo>
					</PositionInfos>
				</OrderInfo>				
				<!-- ... -->
			</request>
		</SendOrderInfoMails>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Übermittlung der Antwort durch WEBSALE (Schritt 2 „SendOrderInfoMailsResponse“)

Als Antwort wird eine Status-Liste der übergebenen „OrderInfo“-Datensätze gesendet.

Parameter	Übergeordnetes Element	Beschreibung	Pflichtfeld

Parameter	Übergeordnetes Element	Beschreibung	Pflichtfeld
MailStati		Enthält für jedes „OrderInfo“ Element aus dem Request ein „MailStatus“ Element.	ja
MailStatus	MailStati	Enthält die Status-Informationen für ein „OrderInfo“ Element aus dem Request.	nein
OrderNumber	MailStatus	Die Bestellnummer	ja, innerhalb von „MailStatus“
Status	MailStatus	OK: Die E-Mail wurde erfolgreich generiert. Error: Es konnte keine Mail generiert werden.	ja, innerhalb von „MailStatus“
ErrorCode	MailStatus	Fehler-Code, z. B. „ESOIF001“. Wird nur bei einem Fehler ausgegeben.	nein
ErrorText	MailStatus	Fehler-Text, z. B. „Bestellnummer existiert nicht“. Wird nur bei einem Fehler ausgegeben.	nein
MsgID		Die vom externen System im Request gesendete MsgID	nein

Beispiel für eine Antwort auf einen SendOrderInfoMails-Request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:ns="http://www.websale.de/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Body>
		<ns:SendOrderInfoMailsResponse>
			<response>
				<MsgID/>
				<MailStati>
					<MailStatus>
						<OrderNumber>137750926502699</OrderNumber>
						<Status>OK</Status>
						<ErrorCode/>
						<ErrorText/>
					</MailStatus>
					<MailStatus>
						<OrderNumber>987654321</OrderNumber>
						<Status>Error</Status>
						<ErrorCode>ESOIF001</ErrorCode>
						<ErrorText>Bestellung ist nicht vorhanden</ErrorText>
					</MailStatus>
				</MailStati>
			</response>
		</ns:SendOrderInfoMailsResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Beispiel mit Bestelldaten, Mail-Template und SOAP-Request

Auszug aus den Bestelldaten:

Auszug aus dem Template:

Auszug der im SOAP-Request übergebene Daten:

Inhalt der daraus generierten Mail:

Fehlerbehandlung

Tritt ein Fehler auf, der den gesamten Request betrifft, so gibt die Schnittstelle einen „SOAP Fault“ zurück. Folgende Fehler können auftreten:

Fehlermeldung	Beschreibung

Fehlermeldung	Beschreibung
ES001 Fehlende ShopID oder Passwort	Im Request fehlt der Parameter „ShopID“ oder der Parameter „Password“. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert.
ES002 Ungültige ShopID oder ungültiges Passwort	Der Request enthielt zwar „ShopID“ und „Password“, aber es existiert kein passender Shop, das Passwort ist falsch oder die Schnittstelle ist für den Shop gar nicht freigeschaltet. Aus Sicherheitsgründen wird der Fehler nicht genau spezifiziert.
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.
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 Fehlendes Pflichtfeld XYZ	Ein Pflichtfeld im Request fehlt oder ist leer.
ES012 Formatfehler	Ein Feld für das ein bestimmtes Format vorgegeben ist hat einen falschen Aufbau.
ES015 Ungültiger Request	Das SOAP-Framework konnte den eingehenden Request nicht verarbeiten.
ES025 Services deaktiviert	Die Dienste des Shops sind wegen Wartungsarbeiten deaktiviert.

Beispiel für einen „SOAP-Fault“:

Folgende Fehler können beim Versand von Info-E-Mails auftreten:

Fehlermeldung	Beschreibung

Fehlermeldung	Beschreibung
ESOIF001 Bestellung ist nicht vorhanden	Für die im Request angegebene OrderNumber existiert keine Bestellung.
ESOIF002 Funktion inaktiv	In der shop.config des Subshops aus dem die Bestellung stammt steht das Feld „Allow“ in der Sektion „OrderInfoMail“ auf „no“ oder der Parameter oder die Sektion fehlen ganz
ESOIF003 Template existiert nicht	Das mit dem SOAP-Request übergebene oder in der shop.config konfigurierte Mail-Template existiert nicht im Template-Verzeichnis des Subshops oder es ist kein Template angegeben.
ESOIF004 Absenderadresse fehlt	Weder im Request noch in der shop.config ist eine Absender-E-Mail-Adresse vorhanden.
ESOIF005 Betreff fehlt	Weder im Request noch in der shop.config ist ein Betreff für die E-Mail vorhanden.

WSDL-Datei

Teil dieser Dokumentation ist eine WSDL-Datei (infomail.wsdl), die Sie auf der untergeordneten Seite zum Download finden. Sie können diese nutzen, um den Code zur Anbindung der Schnittstelle automatisiert zu erstellen. Voraussetzung dafür ist, dass es für die von Ihnen verwendete Programmiersprache ein passendes Tool gibt um die WSDL einzulesen.

URL des SOAP-Servers für InfoMails

Für V8-Shops lautet die URL des SOAP-Servers derzeit:

Info-E-Mails: https://soap-toshop.websale.net/infomails

Bitte beachten Sie, dass sich diese URL in Zukunft ändern kann. Stellen Sie also sicher, dass sich diese ohne größeren Aufwand bei Ihnen ändern lässt.

WS-SOAP-InfoMails (DE)