WS-Bestellgenerator

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. In einer Datei lassen sich bis zu 1000 Aufträge auf einmal übergeben.

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

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

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

Schnittstellen

Die beiden Übergabewege

Funktionsumfang

Aufbau der XML-Daten

Datentypen

Direkte Übergabe ohne Web-Applikation

Antwort des Shops

Einen ASSE-Prozess anstoßen

Wann ein Auftrag erzeugt wird

Fehlercodes

Verwandte Themen

​Die beiden Übergabewege

​Funktionsumfang

​Aufbau der XML-Daten

​Datentypen

​Direkte Übergabe ohne Web-Applikation

​Antwort des Shops

​Einen ASSE-Prozess anstoßen

​Wann ein Auftrag erzeugt wird

​Fehlercodes

​Verwandte Themen

Die beiden Übergabewege

Funktionsumfang

Aufbau der XML-Daten

Datentypen

Direkte Übergabe ohne Web-Applikation

Antwort des Shops

Einen ASSE-Prozess anstoßen

Wann ein Auftrag erzeugt wird

Fehlercodes

Verwandte Themen