General

This documentation describes the SOAP-based sending of info emails to the WEBSALE shop system from an external system.

This interface can be used to send one or more (HTML) emails for an order. A typical application for this function is sending emails when the ordered products are shipped to the customer.

The content of the mail is specified by a template in which any data from the order can be combined with your own data (e.g. order confirmation, invoice, delivery time, tracking number, etc.).

Exclusively encrypted retrieval

The web service must be accessed via SSL. Unencrypted connections will be rejected.

UTF-8 encoding

All data must be sent in UTF-8 format.

Integration of the order data into the e-mail template

For the order data the "OH-" tags are used, as they are also used in the online shop for the order history. See frontend-documentation Onlineshop-Design mit WEBSALE V8s

In addition to the "OH-" tags described in the WEBSALE documentation, tags with the prefix "OH-OF-" and "OH-PF-" are available for the e-mail template, which can be used to insert the data passed in the SOAP request.

Please note that the "info emails" are sent by an external module and therefore not all tags of the WEBSALE shop system are supported.

The template as well as default values for subject and sender of the emails are set in the shop configuration "shop.config".

<OrderInfoMail>
  Allow         = yes
  SenderAddress = MyCompany@domain.de # Sender email address
  SenderName    = My company # Sender name
  Subject-Txt   = Your order # subject of the email
  BCC-Address   = # optional blind recipient address
  Template      = mail_orderinfo.htm # e-mail template
</OrderInfoMail>

Except for "Allow" and "BCC-Address", all parameters in the SOAP message can be overridden. With "BCC-Address" the e-mail can be sent to another blind e-mail address for control purposes.

Furthermore, it is possible to send any files (e.g. PDFs) as mail attachments.

The recipient e-mail and the name of the recipient are automatically determined from the order data.

Requirement

The external system must transfer the ShopID and password each time it is called up

Transfer of the mail data by the external system (step 1 "SendOrderInfoMails")

Parameter	Description	Required field

Parameter	Description	Required field
ShopID	The shop ID	yes
Password	The password for the SOAP interface. You will receive the password from WEBSALE AG.	yes
MsgID	Optionally the external system can provide a MsgID which will be returned by the WEBSALE system in the response. The MsgID has no meaning for the processing of the request.	no
OrderInfos	Contains an "OrderInfo" sub-element for each mail. The number of mails that can be sent with a request is limited to 100.	yes
OrderInfo	Contains the data for sending a single mail. All following elements are subelements of "OrderInfo".	yes, within "OrderInfos”
OrderNumber	The order number of the shop.	yes, within "OrderInfo”
Subject	The subject of the e-mail. overrides the global setting in the shop.config file.	no
SenderAddress	The sender address. overrides the global setting in the shop.config file.	no
SenderName	The sender name. overrides the global setting in the shop.config file.	no
Template	The contents of the mail template. overwrites the contents of the global template specified in the shop.config file	no
TemplateName	The name of the template file. overwrites the global setting in the shop.config file.	no
Attachments	Contains an "Attachment" element for each file to be sent as an attachment with the mail.	no
Attachment	Contains the data for a file to be sent with the mail.	no
FileName	The name of the attachment file. Will be displayed in the mail as an attachment.	yes, within "Attachment”
FileData	base64 encoded data of the attachment file.	yes, within “Attachment”
OrderFields	Upper element of the "OrderField" elements	no
OrderField	The "OrderField" elements can be used to replace tags in the template with any values that apply to the entire order. A maximum of 100 OrderField elements are supported.	no
Name	Name of the tag in the template without the surrounding "~" characters. In the template, the name must be prefixed with "OH-OF-". Ex: If the name " BspTag" is used in the SOAP message, the corresponding tag in the template is "~OH-OF-BspTag~". In addition to value replacement, {OH-OF-BspTag}...{/OH-OF-BspTag} and {!OH-OF-BspTag}...{/!OH-OF-BspTag} brackets are supported, i.e. depending on whether a value is filled, parts of the template can be shown or hidden.	yes, within "OrderField
Value	The value by which the tag specified under "Name" should be replaced in the template.	yes, within "OrderField”
PositionInfos	Contains data to be displayed for each order position.	no
PositionInfo	Contains data to be displayed at a single order position. A maximum of 100 PositionInfo elements are supported.	no
PositionNumber	The value of the "PositionNumber" field in the order data to which the values specified in "PositionInfo" refer must be specified here.	yes, within "PositionInfo”
PositionFields	See "OrderFields”	no
PositionField	See "OrderField”	no
Name	See "OrderField"/"Name", but instead of the prefix "OH-OF-" the tags in the template must have the prefix "OH-PF-" here.	yes, within "PositionField”
Value	See "OrderField"/"Value”	no

Example for a 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>Comment of order</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>

Transmission of the response by WEBSALE (step 2 "SendOrderInfoMailsResponse")

As response a status list of the passed "OrderInfo" records is sent.

Parameter	parent Element	Description	Required field

Parameter	parent Element	Description	Required field
MailStati		Contains a "MailStatus" element for each "OrderInfo" element from the request.	yes
MailStatus	MailStati	Contains the status information for an "OrderInfo" element from the request.	no
OrderNumber	MailStatus	The order number	yes, within "MailStatus”
Status	MailStatus	OK: The mail was generated successfully. Error: No mail could be generated.	yes, within "MailStatus”
ErrorCode	MailStatus	Error code, e.g. "ESOIF001". Will only be output in case of an error.	no
ErrorText	MailStatus	Error text, e.g. "Order number does not exist". Will only be output in case of an error.	no
MsgID		MsgID sent by the external system in the request	no

Example of a response to a 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>Order does not exist</ErrorText>
					</MailStatus>
				</MailStati>
			</response>
		</ns:SendOrderInfoMailsResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example with order data, mail template and SOAP request

Extract from the order data:

Excerpt from the template:

Excerpt of the data transferred in the SOAP request:

Content of the mail generated from it:

Error handling

If an error occurs that affects the entire request, the interface returns a "SOAP Fault". The following errors may occur:

Error message	Description

Error message	Description
ES001 Missing ShopID or password	The parameter "ShopID" or the parameter "Password" is missing in the request. For security reasons, the error is not specified exactly.
ES002 Invalid ShopID or password	The request contained "ShopID" and "Password", but there is no matching shop, the password is wrong or the interface is not enabled for the shop at all. For security reasons the error is not specified exactly.
ES005 Error during server initialization	An error occurred while initializing the SOAP server. Try again later or contact WEBSALE AG.
ES007 SSL required	The program must be called via an encrypted connection. A call with a normal "http" URL is not allowed.
ES008 Wrong shop version	The SOAP interface for the V8 version of a shop was called, but no V8 shop exists.
ES009 Missing required field XYZ	A required field in the request is missing or empty.
ES012 Format error	A field for which a certain format is specified has an incorrect structure.
ES015 Invalid request	The SOAP framework could not process the incoming request.
ES025 Services disabled	The shop's services are disabled due to maintenance.

Example of a "SOAP Fault":

The following errors can occur when sending info emails:

Error message	Description

Error message	Description
ESOIF001 Order does not exist	No order exists for the OrderNumber specified in the request.
ESOIF002 Function inactive	In the shop.config of the subshop from which the order originates, the "Allow" field in the "OrderInfoMail" section is set to "no" or the parameter or section is missing entirely
ESOIF003 template does not exist	The mail template passed with the SOAP request or configured in shop.config does not exist in the template directory of the subshop or no template is specified.
ESOIF004 Sender address missing	No sender email address exists in either the request or in shop.config.
ESOIF005 Subject is missing	Neither the request nor the shop.config has a subject for the email.

WSDL file

Part of this documentation is a WSDL file (infomail.wsdl), which you can download on the subordinate page. You can use this to automatically create the code for connecting the interface. The prerequisite for this is that there is a suitable tool for the programming language you use to read in the WSDL.

URL of the SOAP server for InfoMails

For WEBSALE V8 shops, the URL of the SOAP server is currently:

InfoMails: https://soap-toshop.websale.net/infomails

Please note that this URL may change in the future. So make sure that it can be changed without much effort on your end.

Dokumentation

WS-SOAP-InfoMails (EN)