General services

In the following an order generator is described, with whose assistance automatized orders can be generated in the shop. The orders are placed via XML data.

The transfer of the order/XML data may take place by way of two methods:

Method 1: manual

The XML data are uploaded to a web application via an XML file and are ultimately processed. The web application here is operated manually. The XML file has a set name "orders.xml".

The transfer (uploading) of the file takes place with SSL encryption.

Users of this application must log-in to the shop beforehand and must have authorization for the order generator. The authorization (flag in the customer base) is assigned by the shop operator over the WEBSALE AG service area or by customer data import interface.

In the XML file a maximum of 1000 orders can be transferred at once.

Transfer of the data per XML file upload:

<?xml version="1.0" encoding="UTF-8"?>
<Orders>
  <Order>
    ... Data of the 1st Order ...
  </Order>
  <Order>
    ... Data of the 2nd Order ...
  </Order>
  <Order>
    ... Data of the 3rd Order ...
  </Order>
    ...
  <Order>
    ... Data of the 1000th Order (maximum number) ...
  </Order>
</Orders>

Method 2: automated

The XML data are Blowfish-encrypted and sent without a web application directly to the shop. In each case exactly one order can be given. The shop returns the results of the processing via XML response.

Transfer of XML data with Blowfish encryption:

<?xml version="1.0" encoding="UTF-8"?>
<Order>
  ... Order Data ...
</Order>

Range of functions

The XML order generator does not support all functions that are offered in shop, but only the functions described below. In particular, only offline payment methods can be used or online payment methods without client authentication (credit card clearing server-to-server and ELV). Payment methods such as PayPal or Direct Debit are not possible, since client authentication must occur here over the browser. With a successful order, a confirmation e-mail is sent to the given e-mail address.

Sign-in and guest orders

The XML interface can be used for both existing users (with sign-in) and guest users (without sign-in).

Content of the XML data

Optional parameters can be given empty or can be completely omitted.

<?xml version="1.0" encoding="UTF-8"?>
<Orders>	<!--(Only with file upload)-->
	<Order>
		<Products>
			<Product>
				<Number>Product Number</Number>
				<SetID>Compression Number</SetID>
				<Set>
					<PIndex>Product Index of the Set Upper Article</PIndex>
					<PVarIndex>Variation Index of the Set Upper Article</PVarIndex>
					<CVarIndex-X> Variation Index of the Xth Set Sub Article</CVarIndex-X>
					<child>
						<index>Product Index of the Set Sub Article</index>
						<varindex>Variation Index of the Set Sub Article</varindex>
					</child>
				</Set>
				<SetIDUserIndex>UserIndex</SetIDUserIndex>
				<Quantity>Quantity</Quantity>
				<Price>Product price</Price>
				<Length>Product length</Length>
				<Width>Product width</Width>
				<countryofproduction>Country or location of production</countryofproduction>
				<ForceW2PFlag>yes</ForceW2PFlag>
				<Variations>
					<Variation>
						<Name>Variation Name</Name>
						<Value>Variation Value</Value>
					</Variation>
					<Variation>
						<Name> Variation Name</Name>
						<Value> Variation Value</Value>
					</Variation>
					<!-- ... -->
				</Variations>
				<TextInputs>
					<TextInput>
						<Name> Text Field Name</Name>
						<Value>Text Field Value</Value>
					</TextInput>
					<TextInput>
						<Name> Text Field Name</Name>
						<Value> Text Field Value</Value>
					</TextInput>
					<!-- ... -->
				</TextInputs>
				<DeliverySplit>
					<+Entry>
						<DeliveryAddressID></DeliveryAddressID>
						<DeliveryQuantity></DeliveryQuantity>
						<SampleCopy>yes</SampleCopy>
					</+Entry>
				</DeliverySplit>
			</Product>
			<!-- ... -->
		</Products>
		<Payment>
			<Code>Payment Method Code</Code>
			<Debit>
				<ExternalID>ExternalID</ExternalID>
				<AccountHolder>Account Holder</AccountHolder>
				<BankName>Name of Credit Institution</BankName>
				<AccountNumber>Account No.</AccountNumber>
				<BankCode>Bank Code</BankCode>
				<IBAN>IBAN</IBAN>
				<BIC>BIC</BIC>
			</Debit>
			<CreditCard>
				<Holder>Card Holder</Holder>
				<BrandID>Card Type</BrandID>
				<Number>Card No. Without Spaces </Number>
				<ExpiryDate>Expiry Date</ExpiryDate>
				<VerificationCode>Card Verification Code</VerificationCode>
			</CreditCard>
		</Payment>
		<Delivery>
			<Code>Delivery Code</Code>
			<ID>Delivery Service ID</ID>
		</Delivery>
		<OrderOptions>
			<ResellerSurcharge>Reseller Surcharge</ResellerSurcharge>
			<Reference>Reference Text 1</Reference>
			<Reference2>Reference Text 2</Reference2>
			<OrderOptions1-Entry>Option Number</OrderOptions1-Entry>
			<OrderOptions2-Entry>Option Number</OrderOptions2-Entry>
			<OrderOptions3-Entry>Option Number</OrderOptions3-Entry>
			<OrderOptions4-Entry>Option Number</OrderOptions4-Entry>
			<OrderOptions5-Entry>Option Number</OrderOptions5-Entry>
		</OrderOptions>
		<OrderSpecialInput>
			<!-- Optional additional information for the order -->
		</OrderSpecialInput>
		<Voucher>
			<Number>Voucher Code</Number>
		</Voucher>
		<BillingAddress>
			<!-- (Billing Address Data) -->
		</BillingAddress>
		<DeliveryAddress>
			<!-- (Data of the alternative delivery address) -->
			<+Entry>
				<DeliveryAddressID></DeliveryAddressID>
			</+Entry>
		</DeliveryAddress>
		<ClimateNeutral> Support climate-neutral production </ClimateNeutral>
	</Order>
</Orders><!--(Only with file upload)-->

In the following the sections and parameters are explained.

Character set

The data are given in the UTF-8 character set.

<?xml version="1.0" encoding="UTF-8"?>

Data types

C (Character): Any printable character
N (Numeric): Numbers (0-9)
I (Integer): 4 Byte Integers
F (Float): 4 Byte Floating Point Number (e.g., for prices)

The maximum length is set according to the character for the type.
Example: C30 for a 30-character field with any printable character

Transfer of a product (required)

<Products>
	<Product>
		<Number>Product Number</Number>
		<SetID>Compression Number</SetID>
		<Set>
			<PIndex>Product Index of the Set Upper Article</PIndex>
			<PVarIndex>Variation Index of the Set Upper Article </PVarIndex>
			<CVarIndex-X> Variation Index of the Xth Set Sub Article </CVarIndex-X>
			<child>
				<index>Product Index of the Set Sub Article</index>
				<varindex>Variation Index of the Set Sub Article</varindex>
			</child>
		</Set>
		<SetIDUserIndex>UserIndex</SetIDUserIndex>
		<Quantity>Quantity</Quantity>
		<Price>Product Price</Price>
		<Length>Product length</Length>
		<Width>Product width</Width>
		<countryofproduction>Country or location of production</countryofproduction>
		<ForceW2PFlag>yes</ForceW2PFlag>
		<Variations>
			<Variation>
				<Name>Variation Name</Name>
				<Value>Variation Value</Value>
			</Variation>
			<Variation>
				<Name>Variation Name</Name>
				<Value>Variation Value</Value>
			</Variation>
			<!-- ... -->
		</Variations>
		<TextInputs>
			<TextInput>
				<Name>Text Field Name</Name>
				<Value>Text Field Value</Value>
			</TextInput>
			<TextInput>
				<Name>Text Field Name</Name>
				<Value>Text Field Value</Value>
			</TextInput>			
			<!-- ... -->
		</TextInputs>
		<DeliverySplit>
		    <+Entry>
			    <DeliveryAddressID>ID of the delivery address</DeliveryAddressID>
				<DeliveryQuantity>Quantity</DeliveryQuantity>
				<SampleCopy>yes</SampleCopy>
            </+Entry>
		</DeliverySplit>
	</Product>
	<Product>
		<!-- (Data of the 2nd Product) -->
	</Product>
	<!-- ... -->
	<Product>
		<!-- (Data of the 100th Product) -->
	</Product>
</Products>

Parameter	Optional / Required	Description

Parameter	Optional / Required	Description
Products	Req.	Transfer of all products.
Product	Req.	Transfer of an individual product. This section can be repeated up to 100 times. Therefore up to 100 products can be transferred.
Number	Req. if the SetID is missing Type: C128	Unique product number. This can also be the product number of an independent variable.
SetID	Req. if the number is missing Type: C64	Only possible with sets. A SetID for each set combination can be defined and saved in advance by the shop. One of the saved SetIDs is transferred here.
`<Set>` `<PIndex>...</PIndex>` `<PVarIndex>...</PVarIndex>` `<CVarIndex-X>...</CVarIndex-X>` `</Set>`	Req. if Number or SetID is missing	Alternative/direct transfer of a set without SetID. In this case the complete set with all set sub articles must be stated. It is not possible to use CvarIndex-X-sections and Child-section within a set. In this case the following data will be transferred: `<PIndex>...</PIndex>`: Product Index of the Set Upper Article `<PVarIndex>...</PVarIndex>`: Variation Index of the Set Upper Article `<CVarIndex-X>...</CVarIndex-X>`: Variation Index of the X^th Set Sub Article
`<Set>` `<PIndex>...</PIndex>` `<PVarIndex>...</PVarIndex>` `<child>` `<index>...</index>` `<varindex>...</varindex>` `</child>` `...` `<child>` `<index>...</index>` `<varindex>...</varindex>` `</child>` `</Set>`	Req. if Number or SetID is missing	Alternative/direct transfer of a set without SetID. In this case a variation index can be stated for each set sub article (in an own Child-section) The first completly defined variation combination will be used for not-transferred variation indexes Set sub articles are addressed by the product index and variation index. It is not required to know the exact structure of the set. The order of the transferred variation indexes is not relevant. A transferred variation index is only used once. For multiple assignments (if the set contains a product more than once) the index can be stated multiple times and will be processed in the order of the entries. All transferred child-sections must also be used for the order: If at least one transferred child-section can not be processed (e. g. because the set article does not contain a set sub article with the transferred variation index), an error will be returned. It is not possible to use CvarIndex-X-sections and Child-section within a set. In this case the following data will be transferred: `<PIndex>...</PIndex>`: Product Index of the Set Upper Article `<PVarIndex>...</PVarIndex>`: Variation Index of the Set Upper Article `<child>` `<index>...</index>` `<varindex>...</varindex>` `</child>`: Product Index and Variation Index of the Set Sub Article
SetIDUserIndex	Opt.	The SetID should be loaded by another user.
Quantity	Opt. Type: I or F	Optional amount. If this parameter is missing or empty, then the amount is "1"
Length	Req. if surface area product	Length of the product
Width	Req. if surface area product	Width of the product
Price	Opt. Type: F	Optional position item price. If available, this is used instead of the item price in the product data.
countryofproduction	Opt.	3-digit ISO code of the country in which the product is to be produced OR location of production in the form 3ISO-ALPHANUM (ISO code, hyphen separator, alphanumeric identifier of the location of production). If a production location is specified, this is separated and transferred in the field ProductionLocationIdentifier in the order data for the product.
ForceW2PFlag	Opt.	Flag for identifying W2P orders. If set, the two flags are set in the order data (<Item>): ForceW2PFlag = yes W2P = yes
Variations	Opt.	Transfer of normal variations
Variation	Opt.	Transfer of a normal variation
Name	Req. for normal variations Type: C128	Variation name, for example, "color," "size," "height," "width," etc. Please take note! The variation names must be exactly the same as the variation names defined in the shop and to the product
Value	Req. for normal variations Type: C128	Variations value, for example, "red," "44," etc. Please take note! The variation names must be exactly the same as the variation names defined in the shop and to the product
TextInputs	Opt.	Transfer of text entry fields
TextInput	Opt.	Transfer of a text entry field
Name	Req. for text entry field Type: C128	Name of the text entry field, for example, "stock," "label," etc. Please take note! The variation names must be exactly the same as the variation names defined in the shop and to the product
Value	Req. for text entry field Type: C255	Value of the text entry field, for example, "Müller," "My small farm," etc.
`<DeliverySplit>` `<+Entry>` `<DeliveryAddressID>` `...` `</DeliveryAddressID>` `<DeliveryQuantity>` `...` `</DeliveryQuantity>` `<SampleCopy>` `yes` `</SampleCopy>` `</+Entry>` `</DeliverySplit>`	optional	Only for Multi-ALA-Split (Split-Order) DeliveryAddressID is also defined for <DeliveryAddresses> DeliveryQuantity - Quantity of splits SampleCopy - specimen copy

Transfer of the method of payment (optional)

<Payment>
	<Code>Payment method code</Code>
	<Debit>
		<ExternalID>External ID</ExternalID>
		<AccountHolder>Account Holder</AccountHolder>
		<AccountNumber>Account Number</AccountNumber>
		<BankCode>Bank Code</BankCode>
		<BankName>Name of Credit Institution</BankName>
		<IBAN>IBAN</IBAN>
		<BIC>BIC</BIC>
	</Debit>
	<CreditCard>
		<Holder>Card Holder</Holder>
		<BrandID>Card Type</BrandID>
		<Number>Card No. without Spaces</Number>
		<ExpiryDate>Expiry Date in Format: YYYY-MM</ExpiryDate>
		<VerificationCode>Card Verification Code</VerificationCode>
	</CreditCard>
</Payment>

The Section <Debit>...</Debit> is only given with the method of payment "direct debit." Otherwise this section is completely absent.

The Section <CreditCard>...<CreditCard> is only given with the method of payment "credit card." Otherwise this section is completely absent.

Security information:

The order generator does not store any bank or credit card data. This is only used for each order.

Parameter	Optional / Required	Description

Parameter	Optional / Required	Description
Payment	Opt.	Transfer of an optional method of payment
Code	Req. with transfer of a method of payment Type: I	Method of payment code. Examples for payment type codes: 1=Credit card 3=Cash on delivery 4=Direct debit 5=Prepayment 6=Invoice … You find all payment type codes in the documentation for designers: Zahlungsarten Codes
CreditCard	Required for payment by credit card	Card data section
Holder	Req. Type: C128	Card holder name
BrandID	Req. Type: I	Type of card as an Integer-value. The following types of cards are accepted: 1=VISA 2=Mastercard 3=American Express 4=Diners (more are possible)
Number	Req. Type: N19	Card number without spaces. Example: 4018499066751123
ExpiryDate	Req.	Credit card validity in the format "YYYY- MM" for example 2010-09
VerificationCode	Req. Type: N4	Card verification code. Example: 621
Debit	Required for payment by direct debit	Bank data section
ExternalID	C64	Optional. Bank details can be given with an external ID. If this parameter is given, then all of the following parameters of the bank details will be ignored.
AccountHolder	Req. Type: C128	Account holder name
BankName	Req. Type: C128	Name of the bank
AccountNumber	Req. (without SEPA) Type: N64	Account number without spaces. Example: 486335560
BankCode	Req. (without SEPA) Type: N64	Bank code without spaces Example: 76040061
IBAN	Req. with SEPA	IBAN
BIC	Req. with SEPA	BIC

Please note:

The method of payment is optional. Only offline methods of payment can be used or online methods of payment without client authentication (credit card clearing server-to-server and ELV). Method of payments such as PayPal or immediate transfer are not possible, since client authentication must take place here over the browser.

Example: Payment by credit card

<Payment>
	<Code>1</Code>
	<CreditCard>
		<Holder>Hans Meier</Holder>
		<BrandID>1</BrandID>
		<Number>42000230112244558798</Number>
		<ExpiryDate>2013-01</ExpiryDate>
		<VerificationCode>655</VerificationCode>
	</CreditCard>
</Payment>

Example: Payment by direct debit

<Payment>
	<Code>4</Code>
	<Debit>
		<AccountHolder>Hans Meier</AccountHolder>
		<AccountNumber>4654233421</AccountNumber>
		<BankCode>76040061</BankCode>
		<BankName>Commerzbank</BankName>
	</Debit>
</Payment>

Example: Payment by invoice

<Payment>
	<Code>6</Code>
</Payment>

Example: Payment per cash on delivery

<Payment>
	<Code>3</Code>
</Payment>

Transfer of delivery (optional)

The delivery can be transferred in 2 ways, either by the amount of the delivery costs and the name of the deliverer or by ID and delivery code.

Caution: If both sections are submitted, the section <FixedDelivery> is used!

Transfer with amount and delivery name:

<FixedDelivery>
	<Name>Name of the deliverer</Name>
	<Total>Delivery costs</Total>
</FixedDelivery>

Parameter	Optional / Required	Description

Parameter

Optional / Required

Description

FixedDelivery

Opt.

Transfer of an optional delivery with amount and distributor name

Name

Req.

Type: C255

Name of the deliverer

Total

Req.

Type: F

Delivery costs

Transfer with ID and delivery code

<Delivery>
	<ID>Delivery ID</ID>
	<Code>Delivery code</Code>
	<Reference>Reference text</Reference>
</Delivery>

Parameter	Optional / Required	Description

Parameter	Optional / Required	Description
Delivery	Opt.	Transfer or an optional delivery
ID	Opt. Type: C64	A unique ID that can be defined by the shop for each delivery. If the ID is missing then the shop automatically transmits one of the appropriate deliveries based on the set delivery-filter.
Code	Opt. Type: C4	Delivery code (for example, express delivery) that can be defined by the shop for each delivery.
Reference	Opt. Type: C1024	By reference, the first shipping method is always selected that has the corresponding reference text in the AutoOrderReference parameter of the shop configuration. If ID and Reference are passed, the ID is prioritised.

Transfer of contract options (optional)

<OrderOptions>
	<ResellerSurcharge>120.90</ResellerSurcharge>
	<Reference>Reference text 1</Reference>
	<Reference2>Reference text 2</Reference2>
	<OrderOptions1-Entry>Option Number</OrderOptions1-Entry>
	<OrderOptions2-Entry>Option Number</OrderOptions2-Entry>
	<OrderOptions3-Entry>Option Number</OrderOptions3-Entry>
	<OrderOptions4-Entry>Option Number</OrderOptions4-Entry>
	<OrderOptions5-Entry>Option Number</OrderOptions5-Entry>
</OrderOptions>

Parameter	Optional / Required	Description

Parameter	Optional / Required	Description
OrderOptions	Opt.	Transfer of contract options
ResellerSurcharge	Opt. Type: F	Optional reseller surcharge. Price format: Example: 20.95 Please take note: With a reseller surcharge the method of payment must be given as "surname." If this parameter is empty or missing, then no reseller-surcharge is given.
Reference Reference2	Opt. Type: C50	The reference text of the order. The reference text is shown on invoices, e-mail confirmations and in the order history. The maximum length of this text is 50 characters. If this parameter is empty or missing, then no reference text is given.
OrderOptions1-Entry OrderOptions2-Entry OrderOptions3-Entry OrderOptions4-Entry OrderOptions5-Entry	Opt. Type: I	Up to 5 OrderOptions can be transferred as filed in the Shop Configuration shop.config. Example: Entry in the shop.config: `<OrderOptions1> Allow = yes VATRate-Value = 1 <+Entry> # 1. Option Name-Txt = no sample copies Cost-Value = 0 CostType-Value = 0 Display-Txt = </+Entry> <+Entry> # 2. Option Name-Txt = sample copies Cost-Value = 25.00 CostType-Value = 1 Display-Txt = ... </+Entry> </OrderOptions1>` Entry in the Order Generator, if the 2. option (sample copies) is to be used: `<OrderOptions1-Entry>2</OrderOptions1-Entry>` Similarly the other OrderOptions can be referenced.

Transfer of additional order information (optional)

The transfer of additional order information is optional.

<OrderSpecialInput></OrderSpecialInput>

Parameter	Optional / Required	Description

Parameter

Optional / Required

Description

OrderSpecialInput

Opt.

Type: C32000

Transfer of additional order information

Transfer of a voucher number (optional)

<Voucher>
  <Number>1234-5678-1234-5678</Number>
</Voucher>

Parameter	Optional / Required	Description

Parameter

Optional / Required

Description

Voucher

Opt.

Transfer of a voucher number

Number

Opt.

Type: C19

WS-Bestellgenerator (EN)

General services

Range of functions

Sign-in and guest orders

Content of the XML data

Character set

Data types

Transfer of a product (required)

Transfer of the method of payment (optional)

Transfer of delivery (optional)

Transfer of contract options (optional)

Transfer of additional order information (optional)

Transfer of a voucher number (optional)