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

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

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

Voucher

Opt.

Transfer of a voucher number

Number

Opt.

Type: C19

Voucher number

Please take note:
The complete order is rejected with an unknown or invalid voucher number.

Transfer of the billing address

For guest orders the transfer of the billing address is obligatory.
This is option when signed-in. If no billing address is given during sign-in, (if the BillingAddress section is missing) then the billing address saved with the user's account/login data is used.

In the shop, for each billing address field it is defined whether the field

is supported
is optional or required

The fields of the entered billing address must synchronize with the shop configuration. Please contact the shop operator to find out which fields are supported and which fields are optional or required.

Please take note:
The transferred billing address data will not be stored in the shop data bank, but rather given only under contract.

<BillingAddress>
	<Number>Customer Number</Number>
	<Company>Company Name</Company>
	<SalutationCode>Salutation Code</SalutationCode>
	<TitleCode>Title Code</TitleCode>
	<FirstName>Name</FirstName>
	<LastName>Last Name</LastName>
	<Street1>Street + House No.  (optional)</Street1>
	<Street2>House No., if Street 1 only contains the street </Street2>
	<Zip>ZIP</Zip>
	<City>City</City>
	<State>State/Province</State>
	<CountryCode>DEU</CountryCode>
	<Phone>Telephone (private)</Phone>
	<BusinessPhone>Telephone (business)</BusinessPhone>
	<MobilePhone>Telephone (mobile)</MobilePhone>
	<Fax>Fax (private)</Fax>
	<BusinessFax>Fax (business)</BusinessFax>
	<E-Mail2>E-mail address</E-Mail2>
	<DateOfBirth>Date of Birth (YYYY-MM-DD)</DateOfBirth>
	<PostOfficeBox>P. O. Box</PostOfficeBox>
	<Department>Department</Department>
	<CostCenter>Cost Center</CostCenter>
	<PostOfficeBoxZip>P.O. Box ZIP</PostOfficeBoxZip>
	<TaxID>VAT ID</TaxID>
	<Suffix1>User defined</Suffix1>
	<Suffix2>User defined</Suffix2>
	...
	<Suffix50>User defined</Suffix50>
</BillingAddress>

All standard fields of the billing address are of the type C128

Parameter	Optional / Required	Description
BillingAddress	Opt.	Transfer of an optional billing address
Number	Analog shop configuration	Customer number
Company	Analog shop configuration	Company name
SalutationCode	Analog shop configuration	Salutation code, as defined in the shop, for example, 00: no salutation 01: Mr 02: Mrs 05: Company 07: Family etc... Please contact the shop operator about this.
TitleCode	as shop configuration	Title code, as defined in the shop, for example, 1: Dipl. Ing. 2: Dr. Ing. 3: Dr. med. etc... Please contact the shop operator about this.
FirstName	as shop configuration	First Name
LastName	as shop configuration	Last Name
Street1	as shop configuration	Street and optional house number
Street2	as shop configuration	Separate house number, if Street1 only contains the street
Zip	as shop configuration	ZIP
City	as shop configuration	City
State	as shop configuration	State
CountryCode	as shop configuration	3-digit code according to ISO 3166 Column A3 Example: DEU = Deutschland
Phone	as shop configuration	Telephone (private)
BusinessPhone	as shop configuration	Telephone (business)
MobilePhone	as shop configuration	Telephone (cellular)
Fax	as shop configuration	Fax (private)
BusinessFax	as shop configuration	Fax (business)
E-Mail	as shop configuration	Can only be given in a guest order. This parameter is ignored while signed-in.
E-Mail2	as shop configuration	2^nd E-mail address
DateOfBirth	as shop configuration	Date of birth in the format YYYY-MM-DD
PostOfficeBox	as shop configuration	Post Office Box
Department	as shop configuration	Department
CostCenter	as shop configuration	Cost Center
PostOfficeBoxZip	as shop configuration	Post Office Box ZIP
TaxID	as shop configuration	VAT ID
Suffix1...Suffix50	as shop configuration	May be used analogous to the shop configuration. Please contact the shop operator concerning this.

Transfer of the delivery address (optional)

In the shop, for each field of the delivery address it is defined whether the field

is supported
is optional or required

The fields of the entered delivery address must synchronize with the shop configuration. Please contact the shop operator to find out which fields are supported and which fields are optional or required.

Please note:
The transferred billing address data will not be stored in the shop data bank, but rather given only under contract.

<DeliveryAddress>
	<OneTime>yes</OneTime>
	<Company>Company Name</Company>
	<SalutationCode>Salutation Code</SalutationCode>
	<TitleCode>Title Code</TitleCode>
	<FirstName>Name</FirstName>
	<LastName>Last Name</LastName>
	<Street1>Street + House No. (optional)</Street1>
	<Street2> House No., if Street 1 only contains the street</Street2>
	<Zip>ZIP</Zip>
	<City>City</City>
	<State>State/Province</State>
	<CountryCode>DEU</CountryCode>
	<Phone>Telephone (private)</Phone>
	<BusinessPhone>Telephone (business)</BusinessPhone>
	<MobilePhone>Telephone (mobile)</MobilePhone>
	<Fax>Fax (private)</Fax>
	<BusinessFax>Fax (business)</BusinessFax>
	<E-Mail>E-mail address</E-Mail>
	<DateOfBirth>Date of Birth (YYYY-MM-DD)</DateOfBirth>
	<PostOfficeBox>P. O. Box</PostOfficeBox>
	<Department>Department</Department>
	<CostCenter>Cost Center</CostCenter>
	<PostOfficeBoxZip>P. O. Box ZIP</PostOfficeBoxZip>
	<Suffix1>User defined </Suffix1>
	<Suffix2>User defined</Suffix2>
	...
	<Suffix50>User defined</Suffix50>
</DeliveryAddress>

All standard fields of the delivery address are of the type C128

Parameter	Optional / Required	Description
DeliveryAddress	Opt.	Transfer of an optional alternative delivery address.
OneTime	Opt.	If this parameter is set to "yes," then the WWS must delete this address if the order is carried out. Please contact the WWS manufacturer to find out whether this field is supported.
Company	as shop configuration	Company name
SalutationCode	as shop configuration	Salutation code, as defined in the shop, for example, 00: no salutation 01: Mr 02: Mrs 05: Company 07: Family etc... Please contact the shop operator about this.
TitleCode	as shop configuration	Title code, as defined in the shop, for example, 1: Dipl. Ing. 2: Dr. Ing. 3: Dr. med. etc... Please contact the shop operator about this.
FirstName	as shop configuration	First name
LastName	as shop configuration	Last name
Street 1	as shop configuration	Street and optional house number
Street 2	as shop configuration	Separate house number, if Street1 only contains the street
ZIP	as shop configuration	ZIP
City	as shop configuration	City
State	as shop configuration	State
CountryCode	as shop configuration	3-digit code according to ISO 3166 Column A3 Example: DEU = Deutschland
Phone	as shop configuration	Telephone (private)
BusinessPhone	as shop configuration	Telephone (business)
MobilePhone	as shop configuration	Telephone (cellular)
Fax	as shop configuration	Fax (private)
BusinessFax	as shop configuration	Fax (business)
E-Mail	as shop configuration	E-mail address
DateOfBirth	as shop configuration	Date of birth in the format YYYY-MM-DD
PostOfficeBox	as shop configuration	Post Office Box
Department	as shop configuration	Department
CostCenter	as shop configuration	Cost Center
PostOfficeBoxZip	as shop configuration	Post Office Box ZIP
Suffix1...Suffix50	as shop configuration	May be used analogous to the shop configuration. Please contact the shop operator concerning this.

Supporting the transfer of climate-neutral production

Supporting climate neutral production (automatic selection of the first project)

<ClimateNeutral>yes</ClimateNeutral>

Parameter

optional/required

Description

ClimateNeutral

Opt.

yes: Yes, supported

no: No, not supported

Direct transfer of the XML data (without web application)

The transfer of the XML data is Blowfish-encrypted. A 16-character-key is predetermined for this in the shop and in the external system.

Get method and blowfish method

The 16-digit password is directly used as the key.

The message to be encrypted is "filled in" by a multiple of 8 bytes (best with null bytes) and the message is encrypted in 8 byte blocks with the OpenSSL Blowfish ECB Function.

The shop is accessed via HTTP. The data are transferred via Get method. A maximum of 8,000 characters are given in the request.

Log-in with e-mail address

Here you may transfer an e-mail address that exists in the shop databank. The shop databank then automatically loads all user data (billing address, optional alternative delivery address, user settings, etc.)

The e-mail address is transferred as Blowfish-encrypted and hex-coded.

http://<Shop-URL>&act=autoorder&email=<verschlüsselte eMail- Adresse>&orderdata=<encrypted XML data>

Example:
http://<Shop-URL>&act=autoorder&email=02ccff2233...&orderdata=1122ccffab...

Sign-in with UserIndex

A UserIndex can be given as an alternative to an e-mail address. The shop then automatically loads all the user's data (billing address, optional delivery address, user settings, etc.).

The e-mail address is transferred as Blowfish-encrypted and hex-coded.

http://<Shop-URL>&act=autoorder&userindex=<verschlüsselter UserIndex>&orderdata=<encrypted XML data>

Example:
http://<Shop-URL>&act=autoorder&userindex=02ccff2233...&orderdata=1122ccffab...

Guest order

In a guest order neither an e-mail address, nor a UserIndex is given. The transfer of a billing address is obligatory. Within the billing address the e-mail address is given.

http://<Shop-URL>&act=autoorder&orderdata=<encrypted XML data>

Example:
http://<Shop-URL>&act=autoorder&orderdata=1122ccffab...

orderdata

This parameter is required. Here the XML data are also transferred as Blowfish-encrypted and hex-coded.

Please take note:

The external system first administers Blowfish encryption and afterwards a hex coding of the encrypted binary data. Then the hex coded data is sent to the shop.

Example:
http://<Shop-URL>&act=autoorder&userid=02ccff2233...&orderdata=1122ccffab...

Output

Web application version

The Web-Application displays the following information for each generated order:

Date
Time
ShopID
SubshopID
OrderNumber
Total
UploadID (only with upload articles)
Status
Error message / Error code

Version of the direct XML transfer (without web application)

The shop responds with the following XML version:

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<basicdata>
		<date>Date in Format DD.MM.YYYY</date>
		<time>Time in Format HH:MM:SS</time>
		<mallid>Mallid</mallid>
		<shopid>ShopID</shopid>
		<subshopid>SubShopID</subshopid>
		<result>”OK” or “ERROR”</result>		<!-- The parameter “errorcode“ occurs only with the result=ERROR -->
		<errorcode>Error code</errorcode>		<!-- The parameters "errordetail1" and "errordetail2" are set with many errors.-->
		<errordetail1>Error description 1</errordetail1>
		<errordetail2>Error description 2</errordetail2>
	</basicdata>	<!-- The section <orderdata>...</orderdata> occurs only if result=OK -->
	<orderdata>
		<ordernumber>Order number</ordernumber>
		<subtotal>Subtotal</subtotal>
		<resellersurcharge>Reseller surcharge </resellersurcharge>		<!-- Optional -->
		<paymentcost>Payment method costs</paymentcost>		<!-- Optional -->
		<deliverycost>Delivery costs</deliverycost>		<!-- Optional -->
		<totaldiscount>Total discount</totaldiscount>		<!-- Optional -->
		<vat>VAT</vat>		<!-- Optional, only for netto-prices -->
		<totalsum>Total sum</totalsum>
		<uploadids>			<!-- Optional -->
			<uploadid>
				<UploadID>.<PositionID>
			</uploadid>
			<!-- ... -->
		</uploadids>
		<items>
			<item>				<!--for each order position -->
				<position>Position in Basket</position>
				<number>Product number</number>
				<quantity>Amount</quantity>
				<sum>Total sum of position</sum>
			</item>
			<!-- ... -->
		</items>
	</orderdata>
</response>

Triggering an ASSE process

A section can be defined in the configuration that allows an ASSE process to be triggered for each order item.

To do this, the configuration must be extended as follows:

<Asse>
    active        = yes
    Template      = asse_template.tpl
    EventTemplate = asse_event_template.tpl
    AsseDirectory = /var/spool/wsasse
</Asse>

The templates mentioned in the configuration must be stored in the order generator directory of the respective shop.

The template for the ASSE event can be as follows:

{
    "properties": {
        "content_type": "application/json",
        "delivery_mode": 2
    },
    "routing_key": "websale-ftp",
    "payload": "{\"uploadFinished\": \"$DC-FPTimestamp$\",\"shopNumber\": \"$WS-OTPasseordernumber$\",\"uploadId\": \"$WS-OTPasseuploadid$\",\"positionId\": \"$WS-OTPasseposition$\",\"source\": \"websale-ftp\",\"service\": \"autoOrder\",\"uri\": \"sftp://ftp.c1.websale.net:22022/$WS-OTPasseuploadid$/$WS-OTPasseposition$\"}",
    "payload_encoding":"string"
}

It is important here that the correct $WS and $DC tags are used, as these are replaced during the ordering process.

The ASSE template can look like this:

<Header>
   ShopID               = testshop
   SubShopID            = $WS-SubshopId$
   EventID              = wsOrderGeneratorUploadFinished
   Timestamp            = $DC-FPTimestamp$
   EventCounter         = 1
</Header>
<EventDeliveryTerms>
   Endpoint             = https://websale-asse:fNyb5t-dY5zALcVNwyPdg42ShPEVQWeZ@casual-khaki-bobcat.rmq2.cloudamqp.com/api/exchanges/websale/file.upload/publish
   Type                 = POST
   ConnectionTimeoutInMS = 5000
   ConnectionRetries    = 5
   ConnectionDelayInMinutes = 10
   ServiceCategory      = FileUpload
<DefinitionOfOK>
<+ConditionGroup>
<+Condition>
       Proof                = HTTPStatusCode
       Type                 = value
       Value                = 200
</+Condition>
</+ConditionGroup>
</DefinitionOfOK>
</EventDeliveryTerms>
<PayloadHEX>
$WS-AsseText$
</PayloadHEX>

The $WS-AsseText$ tag is replaced by the hex-encoded content of the ASSE event template.

The file is stored under <shopid>_<subshopid>_autoorderUploadFinish-<Bestellnummer>-<Positionsnummer>.asse in the directory /var/spool/wsasse.

Rules

An order will only be generated when all transferred data are correct. The following checks are performed by the order generator, among others:

If the given product number/SetID exists and if the inventory is sufficient.
If the given normal variations are correct
If defined minimum order quantities are met and if defined maximum order quantities are not surpassed.
If defined denominations are correctly given.
If all required fields of the address data and the method of payment are present.
With online clearing: If the payment with credit card or direct debit are carried out electronically.
If the method of payment “cash on delivery” is given in a reseller surcharge
Etc …

With the status "OK" the order is successfully generated.

With the status "ERROR", the order could not be generated. Additionally, an error code will be given.

Error Codes

An error code is always given with an error. The following codes are supported:

Error Code	Additional error code	Description
100		The parameter "UserID" is missing when accessing the shop
101		Error when decrypting the parameter "UserID"
102		Unknown user ID
103		The user does not have access for this Subhop
104		The parameter "OrderData" is missing when accessing the shop
105		Error when decrypting the parameter "OrderData"
106		The section "Order" is missing in the order data
107		The section "Products" is missing in the order data
108		In a section "Product" the article or compression number is missing
109		In the order data there are no article or compression numbers present
110		The section "Payment" is missing in the order data
111		The parameter "c" is missing in the section "Payment"
112		Unknown method of payment
113		The transferred method of payment is not activated for this account
114		The section "Creditcard" is missing
115		The parameter "Holder" is missing with the payment method credit card
116		The parameter "Number" is missing with the payment method credit card
117		Invalid format of the parameter "ExpiryDate." The format must be "YYY-MM" for example 2010-03
118		The parameter "VerificationCode" is missing with the method of payment credit card
119		The section "Debit" is missing in the order data for the method payment "direct debit"
120		The parameter "Debit" is missing in the order data for the method of payment direct debit
121		The parameter "AccountNumber" is missing for the method of payment direct debit
122		The parameter "BankCode" is missing for the method of payment direct debit
123		The parameter "BankName" is missing for the method of payment direct debit
124		The section "Delivery" is missing
125		The parameter "Code" is missing in the section "Delivery"
126		The account has no authorization for a Reseller surcharge
127		The Reseller-surcharge has surpassed the maximum amount
128		The Reseller-surcharge requires the method of payment surname
129		The section "DeliveryAddress" is missing in the order data
130		At least one required field of the delivery address is missing or is transferred as invalid. Please check "SalutationCode", "TitleCode" and "CountryCode," among others
131		For this order the maximum number of articles has been surpassed
132		The article number has surpassed the maximum length of 64 characters
133		The article or compression number is unknown
133	C1	Unknown product (unknown product index)
133	C2	Unknown product (unknown category index)
133	C3	Set sub article not found
133	C4	Unknown set sub article (unknown category index)
133	C5	Product not found in category
133	C6	Product not found in category / Empty category
133	C7	Product not found in category
133	C8	Problem with depending variants
133	C9	Value for depending variant is missing
133	C11	Value of variant is not/ no longer existing
133	C12	Internal error, UploadID could not be generated
133	C13	Product is “service product” (cannot be ordered)
133	C14	Surface area product: Entries outside the permissible value range
133	C15	countryofproduction specified, not stored for product
133	C16	countryofproduction specified, not included in the list for the product
133	C17	countryofproduction: Country specified with location of production. Incorrect entry (structure not <3ISO>-<alnum LocationIdentifier>)
134		The order quantity must be > 0
135		The article is sold out
136		The given order quantity is invalid
137		The minimum order quantity is not transmitted
138		The maximum order quantity has been surpassed
139		There could be no articles found in this order
140		The transmitted method of payment is not allowed for this order
141		No corresponding card type could be found for the transmitted credit card number
142		No corresponding delivery could be determined for this order
143		The credit card transaction was declined by the Payment-Provider
144		The direct debit transaction was declined by the Payment-Provider
145		Neither the Parameter UserID nor the section "BillingAddress" were transferred
146		The section "BillingAddress" may not be transferred
147		At least one required field of the billing address is missing or was tranferred invalidly. Please check "SalutationCode", "TitleCode" und "CountryCode," among others
148		The parameter "ID" is missing in the section delivery
149		The given supplier ID is unknown
150		A required text entry field was not transferred
151		The maximum entry length of a field of the billing address has been surpassed: Field name: "~errordetails1~", maximum length: ~errordetails2~
152		The maximum entry length of a field of the delivery address has been surpassed: Field name: "~errordetails1~", maximum length: ~errordetails2~
153		Invalid voucher number
154		Method of payment direct debit is only possible with ExternalID and "ExternalID" is missing in the section "Debit."
155		No bank data could be found for the given ExternalID.
156		IBAN missing.
157		BIC is a required field, but is missing.
158		IBAN is invalid.
159		BIC is invalid.
160		Internal error while generating orderdata
161		No <pindex> or no <pvarindex> set
162		Order option is not available for this country
163		Within the section “set“, “cvarindex-X“ and “child“ were transferred.
164		Internal error
165		„varindex“ or „index“ is missing in a section “child“
166		DeliverySplit not allowed
167		internal error
168		Quantity missing at split address
169		no delivery addresses indicated/missing delivery addresses
170		for product x the specified delivery address could not be found/is missing (see message)
171		Delivery address invalid (ID in message)
172		Delivery address invalid (same delivery country of all addresses, different delivery country allowed, …)
173		Split invalid for shopping basket item (affected item in message)
174		AddressID missing for delivery address
175		No climate-neutral project available
176		internal error
177		Reference text 1 is too long (max. 50 characters)
178		Reference text 2 is too long (max. 50 characters)
180		Delivery address could not be assigned to the product (error code in message)
190		Vaulting or PPC are not enabled
191		No VaultID available
192		Clearing failed
711		internal error
712		internal error

Gutenstetter Str. 2, 90449 Nürnberg, +49 (0)911-63 221-0, kontakt@websale.de, www.websale.de

Haftungsausschluss

^{Alle Inhalte werden von der WEBSALE AG ausschließlich zu allgemeinen Informationszwecken veröffentlicht. Für die Richtigkeit, Vollständigkeit und Aktualität der Inhalte können wir jedoch keine Gewähr übernehmen.}

Disclaimer

^{All content is published by WEBSALE AG for general information purposes only. However, we cannot guarantee the correctness, completeness and actuality of the contents.}

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)

Transfer of the billing address

Transfer of the delivery address (optional)

Supporting the transfer of climate-neutral production

Direct transfer of the XML data (without web application)

Get method and blowfish method

Log-in with e-mail address

Sign-in with UserIndex

Guest order

orderdata

Output

Web application version

Version of the direct XML transfer (without web application)

Triggering an ASSE process

Rules

Error Codes