WS-SOAP-InfoMails

Mit WS-SOAP-InfoMails löst ein externes System den Versand von E-Mails zu einer Bestellung aus. Der typische Fall ist die Versandbestätigung: Sobald die Ware das Lager verlässt, schickt die Warenwirtschaft einen SOAP-Request, und der Shop versendet die Mail mit Trackingnummer an den Besteller.

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

Der Webservice ist ausschließlich über SSL erreichbar. Empfängeradresse und Name des Empfängers ermittelt der Shop automatisch aus den Bestelldaten, Sie übergeben sie also nicht.

Das Mail-Template

Den Inhalt der Mail bestimmt ein Shop-Template. Darin kombinieren Sie Daten aus der Bestellung mit Werten, die Sie im Request mitschicken. Für die Bestelldaten dienen dieselben OH--Tags, die im Shop für die Bestellhistorie verwendet werden. Weil die Info-E-Mails durch ein externes Modul versendet werden, steht allerdings nicht der komplette Tag-Vorrat des Shopsystems zur Verfügung. Referenz: OH- (Bestellhistorie) Dazu kommen zwei Tag-Präfixe, die es nur hier gibt:

Präfix	Wofür
`OH-OF-`	Werte, die sich auf die gesamte Bestellung beziehen, aus den `OrderField`-Elementen des Requests
`OH-PF-`	Werte, die sich auf eine einzelne Bestellposition beziehen, aus den `PositionField`-Elementen

Voreinstellungen in der shop.config

Template sowie Standardwerte für Betreff und Absender stehen in der shop.config:

<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>

Bis auf Allow und BCC-Address lässt sich jeder dieser Parameter im SOAP-Request überschreiben. BCC-Address verschickt die Mail zu Kontrollzwecken zusätzlich an eine blinde Empfängeradresse. Steht Allow auf no oder fehlt die Sektion, scheitert jeder Versand mit ESOIF002. Das ist die häufigste Ursache, wenn die Schnittstelle technisch antwortet, aber keine Mail ankommt.

Request: SendOrderInfoMails

Ein Request kann mehrere Mails auslösen, maximal jedoch 100.

Parameter	Beschreibung	Pflichtfeld
`ShopID`	Die Shop-ID	ja
`Password`	Passwort für die SOAP-Schnittstelle, das Sie von der WEBSALE AG erhalten	ja
`MsgID`	Beliebige Kennung, die unverändert in der Antwort zurückkommt	nein
`OrderInfos`	Enthält je Mail ein `OrderInfo`-Element, höchstens 100	ja
`OrderInfo`	Daten für den Versand einer einzelnen E-Mail	ja, innerhalb von `OrderInfos`
`OrderNumber`	Bestellnummer des Shops	ja, innerhalb von `OrderInfo`
`Subject`	Betreff, überschreibt die `shop.config`	nein
`SenderAddress`	Absender-Adresse, überschreibt die `shop.config`	nein
`SenderName`	Absender-Name, überschreibt die `shop.config`	nein
`Template`	Inhalt des Mail-Templates, überschreibt das globale Template	nein
`TemplateName`	Name der Template-Datei, überschreibt die `shop.config`	nein

Dateianhänge

Parameter	Beschreibung	Pflichtfeld
`Attachments`	Enthält je Datei ein `Attachment`-Element	nein
`Attachment`	Daten einer einzelnen Datei	nein
`FileName`	Dateiname, wird in der E-Mail als Anhang angezeigt	ja, innerhalb von `Attachment`
`FileData`	Dateiinhalt base64-kodiert	ja, innerhalb von `Attachment`

So lassen sich beliebige Dateien mitschicken, beispielsweise eine Rechnung als PDF.

Eigene Werte für die gesamte Bestellung

Parameter	Beschreibung	Pflichtfeld
`OrderFields`	Oberelement der `OrderField`-Elemente	nein
`OrderField`	Ersetzt einen Tag im Template durch einen beliebigen Wert. Maximal 100 Elemente.	nein
`Name`	Name des Tags ohne die umrahmenden Tilden. Im Template steht davor der Präfix `OH-OF-`.	ja, innerhalb von `OrderField`
`Value`	Wert, durch den der Tag ersetzt wird	ja, innerhalb von `OrderField`

Heißt der Name im Request BspTag, lautet der Tag im Template ~OH-OF-BspTag~. Neben der reinen Ersetzung funktionieren auch die Klammerungen {OH-OF-BspTag}…{/OH-OF-BspTag} und {!OH-OF-BspTag}…{/!OH-OF-BspTag}. Damit blenden Sie Teile des Templates abhängig davon ein oder aus, ob ein Wert gefüllt ist. Eine Zeile „Ihre Sendungsnummer lautet …” erscheint so nur dann, wenn tatsächlich eine Nummer übergeben wurde.

Eigene Werte je Bestellposition

Parameter	Beschreibung	Pflichtfeld
`PositionInfos`	Enthält Daten, die bei einzelnen Bestellpositionen erscheinen sollen	nein
`PositionInfo`	Daten für eine einzelne Position. Maximal 100 Elemente.	nein
`PositionNumber`	Wert des Feldes `PositionNumber` aus den Bestelldaten, auf das sich die Werte beziehen	ja, innerhalb von `PositionInfo`
`PositionFields`	Wie `OrderFields`	nein
`PositionField`	Wie `OrderField`	nein
`Name`	Wie bei `OrderField`, im Template jedoch mit dem Präfix `OH-PF-`	ja, innerhalb von `PositionField`
`Value`	Wie bei `OrderField`	nein

Beispiel-Request:

<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>

Antwort: SendOrderInfoMailsResponse

Die Antwort enthält je übergebenem OrderInfo einen Status. Ein Request kann also teilweise erfolgreich sein.

Parameter	Übergeordnetes Element	Beschreibung
`MailStati`		Enthält je `OrderInfo` aus dem Request ein `MailStatus`-Element
`MailStatus`	`MailStati`	Statusinformationen zu einem `OrderInfo`
`OrderNumber`	`MailStatus`	Die Bestellnummer
`Status`	`MailStatus`	`OK`, wenn die E-Mail generiert wurde, sonst `Error`
`ErrorCode`	`MailStatus`	Fehler-Code, nur im Fehlerfall, beispielsweise `ESOIF001`
`ErrorText`	`MailStatus`	Fehlertext, nur im Fehlerfall
`MsgID`		Die im Request gesendete MsgID

<ns:SendOrderInfoMailsResponse>
  <response>
    <MailStati>
      <MailStatus>
        <OrderNumber>137750926502699</OrderNumber>
        <Status>OK</Status>
      </MailStatus>
      <MailStatus>
        <OrderNumber>987654321</OrderNumber>
        <Status>Error</Status>
        <ErrorCode>ESOIF001</ErrorCode>
        <ErrorText>Bestellung ist nicht vorhanden</ErrorText>
      </MailStatus>
    </MailStati>
  </response>
</ns:SendOrderInfoMailsResponse>

Werten Sie deshalb jeden MailStatus einzeln aus. Ein Request ohne SOAP Fault bedeutet nicht, dass alle Mails verschickt wurden.

Fehlerbehandlung

Fehler, die den gesamten Request betreffen, kommen als SOAP Fault zurück:

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`	Kein passender Shop, falsches Passwort oder Schnittstelle nicht freigeschaltet.
`ES005 Fehler bei Server-Initialisierung`	Bei der Initialisierung des SOAP-Servers trat ein Fehler auf.
`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.
`ES012 Formatfehler`	Ein Feld mit vorgegebenem Format hat einen falschen Aufbau.
`ES015 Ungültiger Request`	Das SOAP-Framework konnte den Request nicht verarbeiten.
`ES025 Services deaktiviert`	Die Dienste des Shops sind wegen Wartungsarbeiten deaktiviert.

Fehler, die nur eine einzelne Mail betreffen, stehen im jeweiligen MailStatus:

Fehlermeldung	Beschreibung
`ESOIF001 Bestellung ist nicht vorhanden`	Zur angegebenen `OrderNumber` existiert keine Bestellung.
`ESOIF002 Funktion inaktiv`	In der `shop.config` des Subshops, aus dem die Bestellung stammt, steht `Allow` in der Sektion `OrderInfoMail` auf `no`, oder Parameter beziehungsweise Sektion fehlen ganz.
`ESOIF003 Template existiert nicht`	Das im Request oder in der `shop.config` angegebene Mail-Template existiert nicht im Template-Verzeichnis des Subshops, oder es ist gar keines angegeben.
`ESOIF004 Absenderadresse fehlt`	Weder im Request noch in der `shop.config` steht eine Absenderadresse.
`ESOIF005 Betreff fehlt`	Weder im Request noch in der `shop.config` steht ein Betreff.

WSDL-Datei und Server-URL

Zur Schnittstelle gehört die WSDL-Datei infomail.wsdl, mit der sich der Anbindungscode je nach Programmiersprache automatisiert erzeugen lässt. WSDL-Datei und die URL des SOAP-Servers erhalten Sie von Ihrem WEBSALE-Ansprechpartner.

Schnittstellen

Das Mail-Template

Voreinstellungen in der shop.config

Request: SendOrderInfoMails

Dateianhänge

Eigene Werte für die gesamte Bestellung

Eigene Werte je Bestellposition

Antwort: SendOrderInfoMailsResponse

Fehlerbehandlung

WSDL-Datei und Server-URL

Verwandte Themen

​Das Mail-Template

​Voreinstellungen in der shop.config

​Request: SendOrderInfoMails

​Dateianhänge

​Eigene Werte für die gesamte Bestellung

​Eigene Werte je Bestellposition

​Antwort: SendOrderInfoMailsResponse

​Fehlerbehandlung

​WSDL-Datei und Server-URL

​Verwandte Themen

Das Mail-Template

Voreinstellungen in der shop.config

Request: SendOrderInfoMails

Dateianhänge

Eigene Werte für die gesamte Bestellung

Eigene Werte je Bestellposition

Antwort: SendOrderInfoMailsResponse

Fehlerbehandlung

WSDL-Datei und Server-URL

Verwandte Themen