WS-Bestellgenerator (DE)
Allgemeine Leistungen
Im Folgenden wird ein Bestellgenerator beschrieben, mit dessen Hilfe automatisierte Aufträge im Shop generiert werden können. Die Aufträge werden per XML-Daten übergeben.
Die Übergabe der Aufträge/XML-Daten kann mit 2 Methoden erfolgen:
Methode 1: manuell
Die XML-Daten werden per XML-Datei zu einer Web-Applikation hochgeladen und anschließend verarbeitet. Hierzu wird die Web-Applikation manuell bedient.
Die XML-Datei hat einen fest vorgegebenen Namen „orders.xml“. Das Hochladen der Datei erfolgt SSL-verschlüsselt.
Anwender dieser Applikation müssen sich zuvor im Shop anmelden und eine Berechtigung für den Bestellgenerator haben. Die Berechtigung (Flag im Kundenstamm) wird vom Shopbetreiber zugewiesen, entweder über den Servicebereich der WEBSALE AG oder per Kundendatenimport-Schnittstelle.
In der XML-Datei können bis zu 1000 Aufträge auf einmal übergeben werden.
Übergabe der Daten per XML-Datei-Upload:
<?xml version="1.0" encoding="UTF-8"?>
<Orders>
<Order>
... Daten des 1. Auftrags ...
</Order>
<Order>
... Daten des 2. Auftrags ...
</Order>
<Order>
... Daten des 3. Auftrags ...
</Order>
...
<Order>
... Daten des 1000. Auftrags (Höchstanzahl) …
</Order>
</Orders>Methode 2: automatisiert
Die XML-Daten werden ohne Web-Applikation direkt dem Shop Blowfish-verschlüsselt gesendet. Es kann jeweils genau 1 Auftrag übergeben werden. Der Shop gibt das Resultat der Verarbeitung per XML-Antwort zurück.
Übergabe der XML-Daten per Blowfish-Verschlüsselung:
<?xml version="1.0" encoding="UTF-8"?>
<Order>
... Daten des Auftrags ...
</Order>Funktionsumfang
Der XML-Bestellgenerator unterstützt nicht alle Funktionen, die im Shop angeboten werden, sondern nur die nachfolgend beschriebenen Funktionen. Insbesondere können nur Offline-Bezahlmethoden verwendet werden oder Online-Bezahlmethoden ohne Client-Authentifizierung (Kreditkartenclearing Server-zu-Server und ELV). Bezahlmethoden wie PayPal oder Sofortüberweisung sind nicht möglich, da hier eine Client-Authentifizierung über den Browser erfolgen muss. Bei einer erfolgreichen Bestellung wird ein Bestätigungsmail an die übergebene E-Mail-Adresse gesendet.
Anmeldung und Gastbestellungen
Die XML-Schnittstelle kann sowohl für existierende Benutzer (mit Anmeldung) als auch für Gastbestellungen (ohne Anmeldung) verwendet werden.
Inhalt der XML-Daten
Optionale Parameter können leer übergeben oder komplett weggelassen werden.
<?xml version="1.0" encoding="UTF-8"?>
<Orders> (Nur bei Datei-Upload)
<Order>
<Products>
<Product>
<Number>Produktnummer</Number>
<SetID>Verdichtungsnummer</SetID>
<Set>
<PIndex>Produktindex des Set-Oberartikels</PIndex>
<PVarIndex>Variantenindex des Set-Oberartikels</PVarIndex>
<CVarIndex-X>Variantenindex des X-ten Set-Unterartikels</CvarIndex-X>
<child>
<index>Produktindex eines Set-Unterartikels</index>
<varindex>Variantenindex des Set-
Unterartikels</varindex>
</child>
</Set>
<SetIDUserIndex>UserIndex</SetIDUserIndex>
<Quantity>Menge</Quantity>
<Price>Produktpreis</Price>
<Length>Produkthöhe</Length>
<Width>Produktbreite</Width>
<countryofproduction>Produktionsland bzw. -standort</countryofproduction>
<ForceW2PFlag>yes</ForceW2PFlag>
<Variations>
<Variation>
<Name>Variationsname</Name>
<Value>Variationswert</Value>
</Variation>
<Variation>
<Name>Variationsname</Name>
<Value>Variationswert</Value>
</Variation>
…
<Variations>
<TextInputs>
<TextInput>
<Name>Texteingabefeldname</Name>
<Value>Texteingabefeldwert</Value>
</TextInput>
<TextInput>
<Name>Texteingabefeldname</Name>
<Value>Texteingabefeldwert</Value>
</TextInput>
...
</TextInputs>
<DeliverySplit>
<+Entry>
<DeliveryAddressID>ID der Lieferadresse</DeliveryAddressID>
<DeliveryQuantity>Menge</DeliveryQuantity>
<SampleCopy>yes</SampleCopy>
</+Entry>
</DeliverySplit>
</Product>
...
</Products>
<Payment>
<Code>Zahlungsartencode</Code>
<Debit>
<ExternalID>Externe ID<ExternalID>
<AccountHolder>Kontoinhaber</AccountHolder>
<BankName>Name des Kreditinstitutes</BankName>
<AccountNumber>Kontonummer</AccountNumber>
<BankCode>BLZ</BankCode>
<IBAN>IBAN</IBAN>
<BIC>BIC</BIC>
</Debit>
<CreditCard>
<Holder>Karteninhaber</Holder>
<BrandID>Kartentyp</BrandID>
<Number>Kartennummer ohne Leerzeichen</Number>
<ExpiryDate>Verfallsdatum</ExpiryDate>
<VerificationCode>Kartenprüfnummer</VerificationCode>
</CreditCard>
</Payment>
<Delivery>
<Code>Zustellcode</Code>
<ID>ID des Zustellers</ID>
<Reference>Referenztext</Reference>
</Delivery>
<OrderOptions>
<ResellerSurcharge>Resellerzuschlag</ResellerSurcharge>
<Reference>Referenztext</Reference>
<Reference2>Referenztext 2</Reference2>
<OrderOptions1-Entry>Options-Nummer</OrderOptions1-Entry>
<OrderOptions2-Entry>Options-Nummer</OrderOptions2-Entry>
<OrderOptions3-Entry>Options-Nummer</OrderOptions3-Entry>
<OrderOptions4-Entry>Options-Nummer</OrderOptions4-Entry>
<OrderOptions5-Entry>Options-Nummer</OrderOptions5-Entry>
</OrderOptions>
<OrderSpecialInput>
optionale Zusatzinformationen zur Bestellung
</OrderSpecialInput>
<Voucher>
<Number>Gutscheinnummer</Number>
</Voucher>
<BillingAddress>
(Daten der Rechnungsadresse)
</BillingAddress>
<DeliveryAddress>
(Daten der abweichenden Lieferadresse)
<+Entry>
<DeliveryAddressID>ID der Lieferadresse</DeliveryAddressID>
<+Entry>
</DeliveryAddress>
<ClimateNeutral>Klimaneutrale Produktion unterstützen</ClimateNeutral>
</Order>
</Orders> (Nur bei Datei-Upload)Nachfolgend werden die Sektionen und Parameter erläutert.
Zeichensatz
Die Daten werden im UTF-8 Zeichensatz übergeben.
<?xml version="1.0" encoding="UTF-8"?>Datentypen
C (Character): beliebige druckbare Zeichen
N (Numeric): Zahlen (0-9)
I (Integer): 4 Byte Ganzzahl
F (Float): 4 Byte Fließkommazahl (z.B. für Preise)
Die maximale Länge wird nach dem Zeichen für den Typ gestellt.
Beispiel: C30 für ein 30-stelliges Feld mit beliebigen, druckbaren Zeichen
Übergabe eines Produktes (erforderlich)
<Products>
<Product>
<Number>Produktnummer</Number>
<SetID>Verdichtungsnummer</SetID>
<Set>
<PIndex>Produktindex des Set-Oberartikels</PIndex>
<PVarIndex>Variantenindex des Set-Oberartikels</PVarIndex>
<CVarIndex-X>Variantenindex des X-ten Set-Unterartikels</CvarIndex-X>
<child>
<index>Produktindex eines Set-Unterartikels</index>
<varindex>Variantenindex des Set-Unterartikels</varindex>
</child>
</Set>
<SetIDUserIndex>UserIndex</SetIDUserIndex>
<Quantity>Menge</Quantity>
<Price>Produktpreis</Price>
<Length>Produkthöhe</Length>
<Width>Produktbreite</Width>
<countryofproduction>Produktionsland bzw. -standort</countryofproduction>
<ForceW2PFlag>yes</ForceW2PFlag>
<Variations>
<Variation>
<Name>Variationsname</Name>
<Value>Variationswert</Value>
</Variation>
<Variation>
<Name>Variationsname</Name>
<Value>Variationswert</Value>
</Variation>
…
<Variations>
<TextInputs>
<TextInput>
<Name>Texteingabefeldname</Name>
<Value>Texteingabefeldwert</Value>
</TextInput>
<TextInput>
<Name>Texteingabefeldname</Name>
<Value>Texteingabefeldwert</Value>
</TextInput>
...
</TextInputs>
<DeliverySplit>
<+Entry>
<DeliveryAddressID>ID der Lieferadresse</DeliveryAddressID>
<DeliveryQuantity>Menge</DeliveryQuantity>
<SampleCopy>yes</SampleCopy>
</+Entry>
</DeliverySplit>
</Product>
<Product>
(Daten des 2. Produktes)
</Product>
…
<Product>
(Daten des 100. Produktes)
</Product>
</Products>Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
Products | Erf. | Übergabe aller Produkte |
Product | Erf. | Übergabe eines einzelnen Produktes. Diese Sektion kann bis zu 100 mal wiederholt werden. Es können somit bis zu 100 Produkte übergeben werden. |
Number | Erf. wenn SetID fehlt Typ: C128 | Eindeutige Produktnummer. Dies kann auch die Produktnummer einer abhängigen Variante sein. |
SetID | Erf. Wenn Number fehlt Typ: C64 | Nur bei Sets möglich. Bei einem Set kann vorab im Shop eine SetID zu jeder Set-Kombination definiert und abgespeichert werden. Hier wird einer der gespeicherten SetIDs übergeben. |
| Erf. Wenn Number oder SetID fehlt | Alternative/Direkte Übergabe eines kompletten Sets ohne SetID. Es ist nicht möglich CvarIndex-X Sektionen und Child-Sektionen innerhalb eines Sets zu verwenden. In diesem Fall werden folgende Daten übergeben:
|
| Erf. Wenn Number oder SetID fehlt | Alternative/Direkte Übergabe eines unvollständigen Sets ohne SetID. Für nicht übergebene Variantenindizes von Set-Unterartikeln wird die erste, vollständig definierte Variantenkombination verwendet. Die Adressierung der Set-Unterartikel erfolgt anhand von Produktindex und Variantenindex, dabei ist es nicht notwendig den genauen Aufbau des Sets zu kennen. Ein übergebener Variantenindex wird nur einmal verwendet. Bei Mehrfachzuweisungen (wenn das Set ein Produkt mehrfach enthält) müssen/können diese explizit mehrfach angegeben werden und werden in der Reihenfolge der Angabe berücksichtigt. Alle übergebenen Child-Sektionen müssen auch für die Bestellung verwendet werden: Wird mindestens eine übergebene Child-Sektion nicht berücksichtigt (z.B. da der Setartikel keinen Set-Unterartikel mit dem übergebenen Variantenindex besitzt) wird ein Fehler zurückgegeben. Es ist nicht möglich CvarIndex-X Sektionen und Child-Sektionen innerhalb eines Sets zu verwenden. In diesem Fall werden folgende Daten übergeben: |
SetIDUserIndex | Opt. | Die SetID soll von einem anderen User geladen werden. |
Quantity | Opt. Typ: I oder F | Optionale Menge. Fehlt dieser Parameter oder ist er leer, dann ist die Menge „1“ |
Length | Erf. Wenn Flächenprodukt | Angabe der gewünschten Produkthöhe. |
Width | Erf. Wenn Flächenprodukt | Angabe der gewünschten Produktbreite. |
Price | Opt. | Optionaler Stückpreis der Position. |
countryofproduction | Opt. | 3-stelliger ISO-Code des Landes, in dem das Produkt produziert werden soll ODER Produktionsstandort in der Form 3ISO-ALPHANUM (ISO-Code, Trennzeichen Bindestrich, Alphanumerische Kennung des Produktionsstandorts). Bei Angabe eines Produktionsstandorts wird diese abgetrennt und im Feld ProductionLocationIdentifier in den Bestelldaten beim Produkt übergeben. |
ForceW2PFlag | Opt. | Flag zur Identifizierung von W2P-Bestellungen. Wenn gesetzt, werden in den Bestelldaten die beiden Flags gesetzt (<Item> Ebene): |
Variations | Opt. | Übergabe von normalen Varianten |
Variation | Opt. | Übergabe einer normalen Variante |
Name | Erf. für normale Varianten Typ: C128 | Variantenname, z.B. „Farbe“, „Größe“, „Höhe“, „Breite“, usw. Bitte beachten Sie! |
Value | Erf. für normale Varianten Typ: C128 | Variantenwert, z.B. „rot“, „44“ usw. Bitte beachten Sie! |
TextInputs | Opt. | Übergabe von Texteingabefeldern |
TextInput | Opt. | Übergabe eines Texteingabefelds |
Name | Erf. für Texteingabefeld Typ: C128 | Name des Texteingabefelds, z.B. „Besatz“, "Beschriftung", usw. Bitte beachten Sie! |
Value | Erf. für Texteingabefeld Typ: C255 | Wert des Texteingabefelds, z.B. „Müller“, „Meine kleine Farm“ usw.
|
| Opt. | Nur bei MULTI-ALA Splits (Split-Order) DeliveryAddressID ist auch bei <DeliveryAddresses> definiert. DeliveryQuantity-Menge des Splits SampleCopy-Belegexemplar |
Übergabe der Zahlungsart (optional)
<Payment>
<Code>Zahlungsartencode</Code>
<Debit>
<ExternalID>externe ID</ExternalID>
<AccountHolder>Kontoinhaber</AccountHolder>
<AccountNumber>Kontonummer</AccountNumber>
<BankCode>BLZ</BankCode>
<BankName>Name des Kreditinstitutes</BankName>
<IBAN>IBAN</IBAN>
<BIC>BIC</BIC>
</Debit>
<CreditCard>
<Holder>Karteninhaber</Holder>
<BrandID>Kartentyp</BrandID>
<Number>Kartennummer ohne Leerzeichen</Number>
<ExpiryDate>Verfallsdatum im Format: YYYY-MM</ExpiryDate>
<VerificationCode>Kartenprüfnummer</VerificationCode>
</CreditCard>
</Payment>Die Sektion <Debit>...</Debit> wird nur bei der Zahlungsart „Lastschrift“ übergeben. Ansonsten fehlt diese Sektion komplett.
Die Sektion <CreditCard>...</CreditCard> wird nur bei der Zahlungsart „Kreditkarte“ übergeben. Ansonsten fehlt diese Sektion komplett.
Sicherheitshinweis:
Der Bestellgenerator speichert keine Bank- oder Kreditkartendaten ab. Sie werden nur für die jeweilige Bestellung verwendet.
Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
Payment | Opt. | Übergabe einer optionalen Zahlungsart |
Code | Erf. Bei Übergabe einer Zahlungsart Typ: I | Code der Zahlungsart. Beispiele für Zahlungsarten-Codes: |
CreditCard | Erforderlich für Zahlungsart Kreditkarte | Sektion der Kartendaten |
Holder | Erf. Typ: C128 | Name des Karteninhabers |
BrandID | Erf. Typ: I | Kartentyp als Integer-Wert. Folgende Kartentypen werden unterstützt: 1=VISA (weitere sind möglich) |
Number | Erf. Typ: N19 | Kartennummer ohne Leerzeichen. Beispiel: 4018499066751123 |
ExpiryDate | Erf. | Gültigkeit der Karte im Format „YYYY-MM“ z.B. 2010-09 |
VerificationCode | Erf. Typ: N4 | Kartenprüfnummer. Beispiel: 621 |
Debit | Erforderlich für Zahlungsart Lastschrift | Sektion der Bankdaten |
ExternalID | C64 | Optional. |
AccountHolder | Erf. Typ: C128 | Name des Kontoinhabers |
BankName | Erf. Typ: C128 | Name der Bank |
AccountNumber | Erf. (ohne SEPA) Typ: N64 | Kontonummer ohne Leerzeichen. Beispiel: 486335560 |
BankCode | Erf. (ohne SEPA) Typ: N64 | BLZ ohne Leerzeichen Beispiel: 76040061 |
IBAN | Erf. mit SEPA | IBAN |
BIC | Erf. mit SEPA | BIC |
Bitte beachten Sie:
Die Zahlungsart ist optional. Es können nur Offline-Bezahlmethoden verwendet werden oder Online-Bezahlmethoden ohne Client-Authentifizierung (Creditkartenclearing Server-zu-Server und ELV). Bezahlmethoden wie PayPal oder Sofortüberweisung sind nicht möglich, da hier eine Client-Authentifizierung über den Browser erfolgen muss.
Beispiel: Bezahlung per Kreditkarte
<Payment>
<Code>1</Code>
<CreditCard>
<Holder>Hans Meier</Holder>
<BrandID>1</BrandID>
<Number>42000230112244558798</Number>
<ExpiryDate>2013-01</ExpiryDate>
<VerificationCode>655</VerificationCode>
</CreditCard>
</Payment>Beispiel: Bezahlung per Lastschrift
<Payment>
<Code>4</Code>
<Debit>
<AccountHolder>Hans Meier</AccountHolder>
<AccountNumber>4654233421</AccountNumber>
<BankCode>76040061</BankCode>
<BankName>Commerzbank</BankName>
</Debit>
</Payment>Beispiel: Bezahlung per Rechnung
<Payment>
<Code>6</Code>
</Payment>Beispiel: Bezahlung per Nachnahme
<Payment>
<Code>3</Code>
</Payment>Übergabe der Zustellung (optional)
Die Zustellung kann auf 2 Arten übergeben werden: Entweder mit dem Namen des Versanddienstleisters sowie dem Betrag der Lieferkosten (FixedDelivery) oder mit der Zustell-ID und dem Zustellcode (Delivery).
Achtung
Wenn beide Sektionen übergeben werden, wird die Sektion <FixedDelivery> verwendet!
Übergabe mit Betrag und Lieferantenname:
<FixedDelivery>
<Name>Name des Versanddienstleisters</Name>
<Total>Lieferkosten</Total>
</FixedDelivery>Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
FixedDelivery | Opt. | Übergabe einer optionalen Zustellung mit Betrag und Versanddienstleister |
Name | Erf. Typ: C255 | Name des Versanddienstleisters |
Total | Erf. Typ: F | Betrag der Lieferkosten
|
Übergabe mit ID und Zustellcode:
<Delivery>
<ID>Zustell-ID</ID>
<Code>Zustellcode</Code>
<Reference>Referenztext</Reference>
</Delivery>Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
Delivery | Opt. | Übergabe einer optionalen Zustellung |
ID | Opt. Typ: C64 | Eine eindeutige ID, die im Shop zu jeder Zustellung definiert werden kann. Fehlt die ID, dann ermittelt der Shop automatisch eine der passenden Zustellungen aufgrund der gesetzten Zustell-Filter. |
Code | Opt. Typ: C64 | Code der Zustellung, (z. B. Expresslieferung) der im Shop zu jeder Zustellung definiert werden kann. |
Reference | Opt. Typ: C1024 | Durch Reference wird immer die erste Versandart gewählt, die den entsprechenden Referenztext im Parameter AutoOrderReference der Shopkonfiguration hat. Wenn ID und Reference übergeben werden, wird die ID priorisiert. |
Übergabe von Auftragsoptionen (optional)
<OrderOptions>
<ResellerSurcharge>120.90</ResellerSurcharge>
<Reference>Referenztext 1</Reference>
<Reference2>Referenztext 2</Reference2>
<OrderOptions1-Entry>Options-Nummer</OrderOptions1-Entry>
<OrderOptions2-Entry>Options-Nummer</OrderOptions2-Entry>
<OrderOptions3-Entry>Options-Nummer</OrderOptions3-Entry>
<OrderOptions4-Entry>Options-Nummer</OrderOptions4-Entry>
<OrderOptions5-Entry>Options-Nummer</OrderOptions5-Entry>
</OrderOptions>Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
OrderOptions | Opt. | Übergabe von Auftragsoptionen |
ResellerSurcharge | Opt. Typ: F | Optionaler Resellerzuschlag. Preisformat: Bitte beachten Sie: Fehlt dieser Parameter oder ist er leer, dann wird kein Reseller-Zuschlag übergeben. |
Reference Reference2 | Opt. Typ: C50 | Referenztext zur Bestellung. Der Referenztext wird auf Rechnungen, E-Mail-Bestätigungen und in der Auftragshistorie angezeigt. Die maximale Länge dieses Textes beträgt 50 Zeichen. Fehlt dieser Parameter oder ist er leer, dann wird kein Referenztext übergeben. |
OrderOptions1-Entry | Opt. | Hier können bis zu 5 OrderOptions übergeben werden, so wie diese in der Shopkonfiguration shop.config hinterlegt wurden. <OrderOptions1>
Allow = yes
VATRate-Value = 1
<+Entry> # 1. Option
Name-Txt = keine Belegexemplare
Cost-Value = 0
CostType-Value = 0
Display-Txt =
</+Entry>
<+Entry> # 2. Option
Name-Txt = Belegexemplare
Cost-Value = 25.00
CostType-Value = 1
Display-Txt = ...
</+Entry>
</OrderOptions1>Eintrag im Bestellgenerator, wenn die 2. Option (Belegexemplare) verwendet werden soll: Analog dazu, können die anderen OrderOptions referenziert werden |
Übergabe von Zusatzinformationen zur Bestellung (optional)
Die Übergabe von Zusatzinformationen ist optional.
<OrderSpecialInput></OrderSpecialInput>Parameter | Optional / Erforderlich | Beschreibung |
|---|---|---|
OrderSpecialInput | Opt. Typ: C32000 | Übergabe von Zusatzinformationen zur Bestellung |
Übergabe einer Gutscheinnummer (optional)
<Voucher>
<Number>1234-5678-1234-5678</Number>
</Voucher>Parameter | Optional / Erforderlich | Beschreibung |
|---|