WS-SOAP-InfoMails (DE)
- Rainer Biedermann
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:
Onlineshop-Design mit WEBSALE V8s
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 |
|---|---|---|
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 | 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 |
|---|---|
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 |
|---|---|
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“ |
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.