> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# WS-Bestellgenerator

> Automatisierte Bestellungen per XML im Shop auslösen, als Datei-Upload über die Web-Applikation oder Blowfish-verschlüsselt direkt an den Shop.

Mit dem WS-Bestellgenerator lösen Sie automatisierte Bestellungen im Shop aus. Die Daten eines Auftrags werden als XML übergeben. Die Schnittstelle eignet sich besonders für wiederkehrende Bestellungen im B2B-Umfeld und ist für das Abo-Modul Voraussetzung.

| Eigenschaft | Wert |
| - | - |
| Info | Übergabe von XML-Daten, um eine AutoOrder auszulösen |
| Übertragungsrichtung | Externe Applikation → WEBSALE Shop (Data-to-Shop) |
| Übertragungsart | SFTP oder HTTP |
| Dateiformate | XML |

## Die beiden Übergabewege

**Manuell über die Web-Applikation.** Die XML-Daten werden als Datei zu einer Web-Applikation hochgeladen und dort verarbeitet. Die Datei heißt immer `orders.xml`, der Upload läuft SSL-verschlüsselt. Anwender müssen im Shop angemeldet sein und eine Berechtigung für den Bestellgenerator haben. Diese Berechtigung ist ein Flag im Kundenstamm und wird vom Shopbetreiber zugewiesen, entweder im Online-Servicebereich oder über den [Kundendatenimport](https://dokumentation.websale.de/v8s/schnittstellen/kundendaten/ws-sftp-kunden-pro.md). In einer Datei lassen sich bis zu 1000 Aufträge auf einmal übergeben.

```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<?xml version="1.0" encoding="UTF-8"?>
<Orders>
  <Order>
    ... Daten des 1. Auftrags ...
  </Order>
  <Order>
    ... Daten des 2. Auftrags ...
  </Order>
  ...
  <Order>
    ... Daten des 1000. Auftrags (Höchstanzahl) ...
  </Order>
</Orders>
```

**Automatisiert ohne Web-Applikation.** Die XML-Daten gehen Blowfish-verschlüsselt direkt an den Shop. Pro Aufruf wird genau ein Auftrag übergeben, der Shop antwortet mit dem Ergebnis der Verarbeitung als XML.

```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<?xml version="1.0" encoding="UTF-8"?>
<Order>
  ... Daten des Auftrags ...
</Order>
```

## Funktionsumfang

Der Bestellgenerator unterstützt nicht alle Funktionen des Shops. Bei den Zahlungsarten sind nur Offline-Methoden möglich sowie Online-Methoden ohne Client-Authentifizierung, also Kreditkartenclearing Server-zu-Server und ELV. Zahlungsarten wie PayPal oder Sofortüberweisung scheiden aus, weil sie eine Authentifizierung des Kunden im Browser erfordern.

Die Schnittstelle lässt sich für angemeldete Benutzer und für Gastbestellungen verwenden. Nach einer erfolgreichen Bestellung geht eine Bestätigungsmail an die übergebene E-Mail-Adresse.

## Aufbau der XML-Daten

Optionale Parameter können leer übergeben oder ganz weggelassen werden. Die Daten werden im Zeichensatz UTF-8 übergeben.

```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<?xml version="1.0" encoding="UTF-8"?>
<Orders>                          <!-- nur bei Datei-Upload -->
  <Order>
    <Products>
      <Product> ... </Product>
      ...
    </Products>
    <Payment> ... </Payment>
    <Delivery> ... </Delivery>
    <OrderOptions> ... </OrderOptions>
    <OrderSpecialInput> ... </OrderSpecialInput>
    <Voucher> ... </Voucher>
    <BillingAddress> ... </BillingAddress>
    <DeliveryAddress> ... </DeliveryAddress>
    <ClimateNeutral>yes</ClimateNeutral>
  </Order>
</Orders>
```

Die vollständige Beschreibung aller Sektionen und Felder samt Beispielen finden Sie unter [Felder und Beispiele](https://dokumentation.websale.de/v8s/schnittstellen/bestellungen/ws-bestellgenerator/felder-und-beispiele.md).

### Datentypen

Die Felddefinitionen nutzen eine kurze Typangabe, der die maximale Länge folgt. `C30` steht also für ein 30-stelliges Feld mit beliebigen druckbaren Zeichen.

| Kürzel | Bedeutung |
| - | - |
| `C` | Character, beliebige druckbare Zeichen |
| `N` | Numeric, Zahlen von 0 bis 9 |
| `I` | Integer, 4-Byte-Ganzzahl |
| `F` | Float, 4-Byte-Fließkommazahl, beispielsweise für Preise |

## Direkte Übergabe ohne Web-Applikation

Bei der automatisierten Übergabe werden die Daten Blowfish-verschlüsselt. Dafür wird ein vorab vereinbarter Schlüssel aus 16 Zeichen im Shop und im externen System fest hinterlegt.

Das 16-stellige Passwort dient direkt als Schlüssel. Die zu verschlüsselnde Nachricht wird auf ein Vielfaches von 8 Byte aufgefüllt, am besten mit Null-Bytes, und blockweise mit der OpenSSL-Funktion Blowfish-ECB verschlüsselt. Das externe System verschlüsselt also zuerst und kodiert das Ergebnis anschließend hexadezimal. Der Shop wird per HTTP mit der GET-Methode aufgerufen, die Anfrage darf höchstens 8000 Zeichen lang sein.

Je nachdem, wie der Besteller identifiziert wird, sieht der Aufruf unterschiedlich aus. Der Parameter `orderdata` mit den verschlüsselten XML-Daten ist immer erforderlich.

| Fall | Aufruf |
| - | - |
| Anmeldung mit E-Mail-Adresse | `http://<Shop-URL>&act=autoorder&email=<verschlüsselte E-Mail-Adresse>&orderdata=<verschlüsselte XML-Daten>` |
| Anmeldung mit UserIndex | `http://<Shop-URL>&act=autoorder&userindex=<verschlüsselter UserIndex>&orderdata=<verschlüsselte XML-Daten>` |
| Gastbestellung | `http://<Shop-URL>&act=autoorder&orderdata=<verschlüsselte XML-Daten>` |

Bei Anmeldung mit E-Mail-Adresse oder UserIndex lädt der Shop automatisch alle Daten des Benutzers, also Rechnungsadresse, optionale Lieferadresse und Benutzereinstellungen. Bei einer Gastbestellung wird weder das eine noch das andere übergeben. Dort ist die Rechnungsadresse Pflicht, und innerhalb der Rechnungsadresse ist die E-Mail-Adresse ein Pflichtfeld.

## Antwort des Shops

Die Web-Applikation zeigt zu jedem generierten Auftrag Datum, Uhrzeit, ShopID, SubshopID, Auftragsnummer, Gesamtsumme, Status und im Fehlerfall die Fehlermeldung samt Fehlercode an. Bei Upload-Artikeln kommt die UploadID hinzu.

Bei der direkten XML-Übergabe antwortet der Shop mit folgender Struktur:

```xml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <basicdata>
    <date>Datum im Format DD.MM.YYYY</date>
    <time>Uhrzeit im Format HH:MM:SS</time>
    <mallid>MallID</mallid>
    <shopid>ShopID</shopid>
    <subshopid>SubShopID</subshopid>
    <result>"OK" oder "ERROR"</result>
    <!-- errorcode kommt nur bei result=ERROR -->
    <errorcode>Fehlercode</errorcode>
    <!-- errordetail1 und errordetail2 sind bei manchen Fehlern gesetzt -->
    <errordetail1>Fehlerbeschreibung 1</errordetail1>
    <errordetail2>Fehlerbeschreibung 2</errordetail2>
  </basicdata>
  <!-- die Sektion orderdata kommt nur bei result=OK -->
  <orderdata>
    <ordernumber>Auftragsnummer</ordernumber>
    <subtotal>Warenwert</subtotal>
    <resellersurcharge>Reseller-Zuschlag</resellersurcharge>   <!-- optional -->
    <paymentcost>Kosten der Zahlungsart</paymentcost>          <!-- optional -->
    <deliverycost>Kosten der Zustellung</deliverycost>         <!-- optional -->
    <totaldiscount>Gesamtrabatte</totaldiscount>               <!-- optional -->
    <vat>Betrag der Mehrwertsteuer</vat>                       <!-- optional, nur bei Nettopreisen -->
    <totalsum>Gesamtsumme des Auftrages</totalsum>
    <uploadids>                                                <!-- optional -->
      <uploadid>
        UploadID.PositionID
      </uploadid>
      ...
    </uploadids>
    <items>
      <item>                                                   <!-- für jede Bestellposition -->
        <position>Position im Warenkorb</position>
        <number>Produktnummer</number>
        <quantity>Menge</quantity>
        <sum>Gesamtsumme der Position</sum>
      </item>
      ...
    </items>
  </orderdata>
</response>
```

## Einen ASSE-Prozess anstoßen

Der Bestellgenerator kann pro Bestellposition einen [Asynchronous-Server-Side-Event](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale/ws-asse.md) auslösen. Dazu wird die Konfiguration um diese Sektion erweitert:

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

Die beiden genannten Templates liegen im Bestellgenerator-Verzeichnis des Shops. Das Template für das ASSE-Event kann so aussehen:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
}
```

Entscheidend sind die korrekten `$WS-` und `$DC-`-Tags, denn sie werden im Lauf des Bestellprozesses ersetzt. Das ASSE-Template selbst kann so aussehen:

```
<Header>
   ShopID               = testshop
   SubShopID            = $WS-SubshopId$
   EventID              = wsOrderGeneratorUploadFinished
   Timestamp            = $DC-FPTimestamp$
   EventCounter         = 1
</Header>
<EventDeliveryTerms>
   Endpoint             = https://BENUTZER:PASSWORT@HOST/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>
```

Das Tag `$WS-AsseText$` wird durch den hexadezimal kodierten Inhalt des Event-Templates ersetzt. Die erzeugte Datei liegt anschließend unter `<shopid>_<subshopid>_autoorderUploadFinish-<Bestellnummer>-<Positionsnummer>.asse` im Verzeichnis `/var/spool/wsasse`.

## Wann ein Auftrag erzeugt wird

Ein Auftrag entsteht nur dann, wenn alle übergebenen Daten korrekt sind. Der Bestellgenerator prüft unter anderem:

* Existiert die übergebene Produktnummer oder SetID und reicht der Lagerbestand?
* Sind die übergebenen normalen Varianten korrekt?
* Werden definierte Mindest- und Maximalbestellmengen eingehalten?
* Sind definierte Stückelungen korrekt übergeben?
* Sind alle Pflichtfelder der Adressdaten und der Zahlungsart vorhanden?
* Beim Online-Clearing: Konnte die Zahlung mit Kreditkarte oder Lastschrift elektronisch durchgeführt werden?
* Wird bei einem Resellerzuschlag die Zahlungsart Nachnahme übergeben?

Beim Status `OK` wurde der Auftrag erfolgreich erzeugt. Beim Status `ERROR` konnte er nicht erzeugt werden, zusätzlich wird ein Fehlercode ausgegeben.

## Fehlercodes

Bei einem Fehler wird stets ein Fehlercode übergeben. Folgende Codes werden unterstützt:

| Fehlercode | Zusatzcode | Beschreibung |
| - | - | - |
| 100 | | Der Parameter "UserID" fehlt beim Aufruf des Shops |
| 101 | | Fehler beim Entschlüsseln des Parameters "UserID" |
| 102 | | Unbekannte Benutzerkennung |
| 103 | | Der Benutzer hat keine Berechtigung für diesen Subshop |
| 104 | | Der Parameter "OrderData" fehlt beim Aufruf des Shops |
| 105 | | Fehler beim Entschlüsseln des Parameters "OrderData" |
| 106 | | Die Sektion "Order" fehlt in den Auftragsdaten |
| 107 | | Die Sektion "Products" fehlt in den Auftragsdaten |
| 108 | | In einer Sektion "Product" fehlt die Artikel- oder Verdichtungsnummer |
| 109 | | In den Auftragsdaten sind keine Artikel- oder Verdichtungsnummern vorhanden |
| 110 | | Die Sektion "Payment" fehlt in den Auftragsdaten |
| 111 | | Der Parameter "Code" fehlt in der Sektion "Payment" |
| 112 | | Unbekannte Zahlungsart |
| 113 | | Die übergebene Zahlungsart ist für diesen Account nicht freigeschaltet |
| 114 | | Die Sektion "Creditcard" fehlt |
| 115 | | Der Parameter "Holder" fehlt bei der Zahlungsart Kreditkarte |
| 116 | | Der Parameter "Number" fehlt bei der Zahlungsart Kreditkarte |
| 117 | | Ungültiges Format des Parameters "ExpiryDate". Das Format muss "JJJJ-MM" beispielsweise 2010-03 sein |
| 118 | | Der Parameter "VerificationCode" fehlt bei der Zahlungsart Kreditkarte |
| 119 | | Die Sektion "Debit" fehlt in den Auftragsdaten für die Zahlungsart "Lastschrift" |
| 120 | | Der Parameter "AccountHolder" fehlt für die Zahlungsart Lastschrift |
| 121 | | Der Parameter "AccountNumber" fehlt für die Zahlungsart Lastschrift |
| 122 | | Der Parameter "BankCode" fehlt für die Zahlungsart Lastschrift |
| 123 | | Der Parameter "BankName" fehlt für die Zahlungsart Lastschrift |
| 124 | | Die Sektion "Delivery" fehlt |
| 125 | | Der Parameter "Code" fehlt in der Sektion "Delivery" |
| 126 | | Der Account hat keine Berechtigung für einen Reseller-Zuschlag |
| 127 | | Der Reseller-Zuschlag hat den maximalen Betrag überschritten |
| 128 | | Der Reseller-Zuschlag erfordert die Zahlungsart Nachnahme |
| 129 | | Die Sektion "DeliveryAddress" fehlt in den Auftragsdaten |
| 130 | | Mindestens ein Pflichtfeld der Lieferadresse fehlt oder wurde ungültig übergeben. Bitte überprüfen Sie u.a. "SalutationCode", "TitleCode" und "CountryCode" |
| 131 | | Für diesen Auftrag wurde die maximale Anzahl von Artikeln überschritten |
| 132 | | Die Artikelnummer hat die maximale Länge von 64 Zeichen überschritten |
| 133 | | Die Artikel- oder Verdichtungsnummer ist unbekannt |
| 133 | C1 | Produkt unbekannt (Produktindex nicht gefunden) |
| 133 | C2 | Produkt unbekannt (Kategorieindex nicht gefunden) |
| 133 | C3 | Setunterprodukt nicht gefunden |
| 133 | C4 | Setunterprodukt unbekannt (Kategorieindex nicht gefunden) |
| 133 | C5 | Produkt in Kategorie nicht gefunden |
| 133 | C6 | Produkt in Kategorie nicht gefunden / Kategorie leer |
| 133 | C7 | Produkt in Kategorie nicht gefunden |
| 133 | C8 | Problem mit abhängigen Varianten |
| 133 | C9 | Wert für abhängige Variante fehlt |
| 133 | C11 | Variantenwert existiert nicht (mehr) |
| 133 | C12 | Interner Fehler, UploadID konnte nicht generiert werden |
| 133 | C13 | Produkt ist Serviceprodukt (können nicht bestellt werden) |
| 133 | C14 | Flächenprodukt: Eingaben außerhalb des zulässigen Bereichs |
| 133 | C15 | countryofproduction angegeben, bei Produkt nicht hinterlegt |
| 133 | C16 | countryofproduction angegeben, nicht in Liste bei Produkt enthalten |
| 133 | C17 | countryofproduction: Land mit Produktionsstandord angegeben. Fehlerhafter Eintrag (Aufbau nicht `<3ISO>-<alnum LocationIdentifier>`) |
| 134 | | Die Bestellmenge muss > 0 sein |
| 135 | | Der Artikel ist ausverkauft |
| 136 | | Die übergebene Bestellmenge ist ungültig |
| 137 | | Die Mindestbestellmenge wurde nicht übergeben |
| 138 | | Die maximale Bestellmenge wurde überschritten |
| 139 | | Für diesen Auftrag konnte kein Artikel gefunden werden |
| 140 | | Die übergebene Zahlungsart ist für diesen Auftrag nicht erlaubt |
| 141 | | Zur übergebenen Kreditkartennummer konnte kein passender Kartentyp ermittelt werden |
| 142 | | Für diesen Auftrag konnte keine passende Zustellung ermittelt werden |
| 143 | | Die Kreditkarten-Transaktion wurde vom Payment-Provider abgelehnt |
| 144 | | Die Lastschrift-Transaktion wurde vom Payment-Provider abgelehnt |
| 145 | | Weder der Parameter UserID noch die Sektion "BillingAddress" wurden übergeben |
| 146 | | Die Sektion "BillingAddress" darf nicht übergeben werden |
| 147 | | Mindestens ein Pflichtfeld der Rechnungsadresse fehlt oder wurde ungültig übergeben. Bitte überprüfen Sie u.a. "SalutationCode", "TitleCode" und "CountryCode" |
| 148 | | Der Parameter "ID" fehlt in der Sektion "Delivery" |
| 149 | | Die übergebene LieferantenID ist unbekannt |
| 150 | | Ein benötigtes Texteingabefeld wurde nicht übergeben |
| 151 | | Die maximale Eingabelänge eines Felds der Rechnungsadresse wurde überschritten: Feldname: "~~errordetails1~~", maximale Länge: ~~errordetails2~~ |
| 152 | | Die maximale Eingabelänge eines Felds der Lieferadresse wurde überschritten: Feldname: "~~errordetails1~~", maximale Länge: ~~errordetails2~~ |
| 153 | | Gutscheinnummer ungültig |
| 154 | | Zahlungsart Lastschrift nur mit ExternalID möglich und "ExternalID" in Sektion "Debit" fehlt. |
| 155 | | Zu der übergebenen ExternalID konnten keine Bankdaten gefunden werden. |
| 156 | | IBAN fehlt. |
| 157 | | BIC ist ein Pflichtfeld, aber fehlt. |
| 158 | | IBAN ist ungültig. |
| 159 | | BIC ist ungültig. |
| 160 | | Interner Fehler bei der Erzeugung der Bestelldaten aufgetreten |
| 161 | | Kein `<pindex>` oder kein `<pvarindex>` übergeben |
| 162 | | Bestelloption nicht gültig für dieses Land |
| 163 | | Innerhalb der Sektion „set“ wurde „cvarindex-X“ und „child“ übergeben. |
| 164 | | Interner Fehler |
| 165 | | „varindex“ bzw. „index“ fehlt in einer Sektion „child“ |
| 166 | | DeliverySplit nicht erlaubt |
| 167 | | interner Fehler |
| 168 | | Menge fehlt bei Split-Adresse |
| 169 | | keine Lieferadressen angegeben/Lieferadressen fehlen |
| 170 | | für Produkt x konnte angegebene Lieferadresse nicht gefunden werden/fehlt (siehe Meldung) |
| 171 | | Lieferadresse ungültig (ID in Meldung) |
| 172 | | Lieferadresse ungültig (gleiches Lieferland aller Adressen, abw. Lieferland erlaubt, ...) |
| 173 | | Split für Warenkorbposition ungültig (betroffene Position in Meldung) |
| 174 | | AddressID fehlt bei Lieferadresse |
| 175 | | Kein klimaneutrales Projekt vorhanden |
| 176 | | interner Fehler |
| 177 | | Referenztext 1 ist zu lang (max. 50 Zeichen) |
| 178 | | Referenztext 2 ist zu lang (max. 50 Zeichen) |
| 180 | | Lieferadresse konnte dem Produkt nicht zugewiesen werden (Fehlercode in Meldung) |
| 190 | | Vaulting oder PPC sind nicht freigeschaltet |
| 191 | | Keine VaultID vorhanden |
| 192 | | Clearing fehlgeschlagen |
| 711 | | interner Fehler |
| 712 | | interner Fehler |

## Verwandte Themen

* [Felder und Beispiele](https://dokumentation.websale.de/v8s/schnittstellen/bestellungen/ws-bestellgenerator/felder-und-beispiele.md)
* [WS-Bestelldaten](https://dokumentation.websale.de/v8s/schnittstellen/bestellungen/ws-bestelldaten.md)
* [WS-ASSE](https://dokumentation.websale.de/v8s/schnittstellen/marketing-seo-und-portale/ws-asse.md)


## Related topics

- [Felder und Beispiele](https://dokumentation.websale.de/v8s/schnittstellen/bestellungen/ws-bestellgenerator/felder-und-beispiele.md)
- [CustomOfferAPI](https://dokumentation.websale.de/v8s/schnittstellen/produkte-und-kategorien/custom-offer-api.md)
- [Bestellungen](https://dokumentation.websale.de/v8s/schnittstellen/bestellungen.md)
- [Abo-Modul](https://dokumentation.websale.de/v8s/marketing-funktionen/abo-modul.md)
- [Account-API](https://dokumentation.websale.de/v8s/schnittstellen/kundendaten/account-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.