Operation: CreateOrder

Die Anfrage ist ein Element vco:CreateOrderRequest, die Antwort ist ein Element vco:OrderResponse. Das Element vco:CreateOrderRequest erweitert den Typ vct:RequestType um das Element vco:OrderRequestLine, welches mindestens einmal vorkommen muss. Dieses besitzt die folgenden Elemente:

Name

Typ/Vorkommen

Beschreibung

Name

Typ/Vorkommen

Beschreibung

cac:SellersItemIdentification

cac:ItemIdenficationType

Kennzeichnung des zu bestellenden Artikels

cbc:Quantity

cbc:QuantityType

Menge

cac:BuyersItemIdentification

cac:ItemIdenficationType?

optional: Artikelnummer des Käufers

cbc:DeliveryDate

cbc:Date?

optional: gewünschtes Lieferdatum

cbc:BacklogIndicator

cbc:IndicatorType?

optional: Indikator für Nachlieferung

 

Regel: CreateOrderRequest

Ein veloconnect-konformer Client vehält sich wie folgt: Für die Zwecke der Transaktion Order wird davon ausgegangen, dass die Bestellung normalisiert ist, d.h. je zwei verschiedene Zeilen der Bestellung beziehen sich auf verschiedene Artikelkennzeichnungen des Verkäufers (kurz: Bestellnummer). Zu jeder Zeile dieser Bestellung wird ein Element OrderRequestLine wie folgt angelegt:

Regel: OrderRequestLine(Client)

  1. Das Element SellersItemIdentifcation enthält die Bestellnummer.

  2. Das Element Quantity enthält die Bestellmenge (vgl. Absatz cbc:QuantityType).

  3. Das optionale Element BuyersItemIdentification kann für die Angabe der Artikelnummer des Käufers verwendet werden.

  4. Das optionale Element DeliveryDate wird nur verwendet, wenn vom Benutzer explizit eine Lieferung zu einem späteren Zeitpunkt gewünscht wird. Das Programm muss diese Eingabemöglichkeit nicht vorsehen. Falls es dies doch tut, ist dafür Sorge zu tragen, dass die Eingabe des Benutzers möglichen Einschränkungen des Servers genügt. Insbesondere ist diese Eingabemöglichkeit nicht anzubieten, wenn der Server die Angabe eines Liefertermins nicht unterstützt. Ferner darf das Datum nicht in der Vergangenheit liegen.

  5. Es wird davon ausgegangen, dass zwischen Käufer und Verkäufer eine Verreinbarung herrscht, ob nicht lieferbare Artikel üblicherweise nachzuliefern sind oder nicht. Das Element BacklogIndicator ist nur zu verwenden, wenn der Benutzer eine explizite Abweichung von dieser Regel wünscht. Dem Benutzer kann diese Möglichkeit eröffnet werden, muss aber nicht.

 

Wird die URL oder die URL-S-Bindung verwendet, muss jedes dieser Elemente in eine Folge von Parametern übersetzt werden. Dies geschieht wie folgt: Sei X der Inhalt des ID-Elements von SellersItemIdentification. Name und Wert der für die Serialisierung verwendeten Parameter sind dann wie folgt:

Name

Wert

Name

Wert

Quantity.X

Inhalt des Elements Quantity

quantityUnitCode.X

Inhalt des Attributs quantityUnitCode des Elements Quantity

DeliveryDate.X

Inhalt des Elements DeliveryDate.

BacklogIndicator.X

Inhalt des Elements BacklogIndicator.

BuyersItemIdentification.X

Inhalt des ID-Elements von BuyersItemIdentification

 

Regel: Serialisierung von vco:OrderRequestLine

Ein veloconnect-konformer Server darf die Transaktion Order in der URL- oder URL-S-Bindung nur dann implementieren, wenn gewährleistet ist:

  1. Jeder Artikel ist durch eine Artikelnummer eindeutig gekennzeichnet, d.h. zur Kennzeichnung von Gegenständen wird nur das ID-Element in Elementen cac:SellersItemIdentification benötigt.

  2. Es werden keine Artikelnummern verwendet, in denen das Zeichen = vorkommt.

 

Das Element vco:OrderResponse erweitert den Typ vct:TransactionResponseType um die Elemente vco:OrderResponseLine, vco:RequestReplacement, vco:ItemUnknown, die jeweils beliebig oft vorkommen können.

Das Element vco:OrderResponseLine ist aus folgenden Elementen aufgebaut:

Name

Typ/Vorkommen

Beschreibung

Name

Typ/Vorkommen

Beschreibung

cbc:Quantity

cbc:QuantityType

Menge

cac:Item

cac:ItemType

Beschreibung des bestellten Artikels

cac:UnitPrice

cbc:PriceAmountType

Einzelpreis

vco:Availability?

vco:AvailabilityType

Liefererbarkeit (vgl. Absatz vco:AvailabilityType)

cbc:DeliveryDate

cbc:Date?

Lieferdatum

cbc:BacklogIndicator

cbc:IndicatorType?

Indikator für Nachlieferung

 

Das Element vco:RequestReplacement besteht aus zwei Elementen:

Name

Typ/Vorkommen

Beschreibung

Name

Typ/Vorkommen

Beschreibung

cac:SellersItemIdentifcation

cac:ItemIdentificationType

Vom Käufer bestellter Artikel

cac:ItemReplacement

cac:ItemReplacementType+

Ersatzvorschlag

Der Typ cac:ItemReplacementType erweitert den Type cac:ItemIdentificationType um ein verbindliches Element cac:ReplacementCode vom Typ cac:ReplacementCodeType sowie ein optionales Element cbc:Description. Der Typ cac:ReplacementCodeType kann nur folgende Zeichenketten als Inhalt haben:

  • identical

  • package

  • recommended

 

Das Element vco:ItemUnknown enthält ein Element cac:SellersItemIdentification.

vco:AvailabilityType

Der Typ vco:AvailabilityType besteht aus folgenden Elementen:

Name

Typ/Vorkommen

Beschreibung

Name

Typ/Vorkommen

Beschreibung

vco:Code

vco:AvailabilityCodeType

Code für Lieferbarkeit, kann nur folgende Werte annehmen: available, partially_available, expecting_delivery, not_available

vco:AvailableQuantity

cbc:QuantityType?

lieferbare Menge

cbc:ExpectedDeliveryDate

cbc:DateType?

erwartete Lieferung

cac:ItemReplacement

cac:ItemReplacementType*

Ersatzvorschlag

 

Regel: CreateOrder

Ein veloconnect-konformer Server reagiert auf ein Anfrage CreateOrderRequest wie folgt:

  1. Falls in der Anfrage keine TransactionID übermitttelt wird, wird eine neue Transaktionsinstanz erzeugt. Falls dies nicht möglich ist, wird der ResponseCode 421 zurückgeliefert.

  2. Falls in der Anfrage eine TransactionID übermittelt wird, wird überprüft, ob hierzu schon eine Transaktionsinstanz existiert. Falls eine solche existiert und sich diese weder im Startzustand noch im Endzustand befindet, wird die Bearbeitung der Anfrage abgebrochen und der ResponseCode 430 zurückgeliefert. Ansonsten wird der Transaktionskontext gelöscht und die Transaktionsinstanz in den Zustand 1 versetzt.

  3. Mit jedem Element OrderRequestLine wird gemäß der Regel OrderRequestLine(Server) verfahren. Hierbei werden im Transaktionskontext Elemente OrderResponseLine angelegt, sowie eventuelle Elemente RequestReplacement erzeugt.

  4. Aus dem Transaktionskontext werden die Elemente OrderResponseLine in die Antwort eingefügt, sowie die im vorherigen Schritt erzeugten Elemente RequestReplacement. Die Antwort wird mit ResponseCode 200 an den Client ausgeliefert und die Transaktionsinstanz wechselt in den Zustand 2 (Updatezustand)

Regel: OrderRequestLine(Server)

Es sei ein Element OrderRequestLine gegeben. Der Transaktionskontext wird wie folgt modifiziert:

  1. Es wird überprüft, ob SellersItemIdentification eine gültige Artikelkennzeichnung ist. Falls dies nicht der Fall ist und Regel: RequestReplacement anwendbar ist, wird gemäß dieser Regel ein RequestReplacement-Element erzeugt, ansonsten wird die übergebene SellersItemIdentification in ein ItemUnknown-Element verpackt.

  2. Falls SellersItemIdentification eine gültige Artikelkennzeichnung ist, wird ein Element OrderResponseLine erzeugt. Die Elemente Quantity, DeliveryDate, BacklogIndicator werden übernommen, wobei folgende Modifikationen möglich sind:

    1. Falls für die Bestellmenge nur gewisse Werte zulässig sind, kann die Menge auf den nächsten gültigen Wert angepasst werden. (Beispiel: Als Einheit wird Stück verwendet, die Abgabe erfolgt aber nur in Packungen zu 100 Stück.)

    2. Falls das gewünschte Lieferdatum nicht eingehalten werden kann, kann das Datum auf einen anderen Wert gesetzt werden. Dieser sollte möglichst nahe beim gewünschten Termin liegen.

    3. Falls der Server nicht in der Lage ist, Angaben zum Liefertermin zu verarbeiten oder nur unter Einschränkungen, müssen diese Enschränkungen im veloconnect-Profil in der Eigenschaft Order.DeliveryDate angegeben werden.

    4. Sofern das gewünschte Nachlieferungsverhalten nicht realisiert werden kann, ist das Element BacklogIndicator entsprechend zu setzen.

  3. Das Element BuyersItemIdentfication sollte übernommen werden, muss aber nicht, falls das System nicht in der Lage ist, diese Information im Transaktionskontext zu speichern.

  4. Aus dem Warenwirtschaftssystem werden die Stammdaten des identifizierten Artikels ermittelt und im Element Item abgelegt.

  5. Der Nettoeinzelpreis des Artikels ist im Element UnitPrice abzulegen. Dieser Einzelpreis bezieht sich auf die in Quantity angegebenen Einheit. Der Gesamtpreis eines Posten ergibt sich also durch Multiplikation des Einzelpreises (UnitPrice) mit der Anzahl (Quantity).

  6. Die Verfügbarkeit des Artikels wird aus aktuell verfügbaren Daten des Warenwirtschaftssystems ermittelt werden und gemäß Regel: Availability im Element Availability abgelegt werden. Falls der Server diese Information nicht zur Verfügung stellt, muss dies im veloconnect-Profil mittels der Eigenschaft Order.Availability angegeben werden.

  7. Das erzeugte Element OrderResponseLine wird im Transaktionskontext gespeichert und ersetzt dort ein eventuell schon vorhandenes Element mit der gleichen Artikelkennzeichnung. Falls die angegebene Menge den Wert 0 hat, so wird das Element aus dem Transaktionskontext entfernt.

 

Regel: RequestReplacement

Erhält der Server vom Client eine Artikelkennzeichnung, die nicht mehr zum aktuellen Sortiment gehört, aber dennoch soweit vom Server interpretiert werden kann, dass er einen oder mehrere Ersatzvorschläge unterbreiten will, so wird dies mit dem Element vco:RequestReplacement mitgeteilt. Das Kind-Element vco:SellersItemIdentification wird unverändert aus der Anfrage übernommen, für jeden Ersatzartikel wird ein Element cac:ItemReplacement gemäß nachfolgender Regel gebildet.

Regel: ItemReplacement

Ersatzartikel werden durch ein Element cac:ItemReplacement mitgeteilt. Das Kind-Element cac:ReplacementCode vom Typ cac:ReplacementCodeType qualifiziert den Vorschlag wie folgt:

Inhalt

Bedeutung

Inhalt

Bedeutung

identical

Der Ersatzartikel unterscheidet sich vom zu ersetzenden Artikel nur durch die Artikelnummer. (Zum Beispiel anwendbar, wenn eine Umstellung der Artikelnummern stattgefunden hat und der Client noch die alten verwendet)

package

Der Ersatzartikel unterscheidet sich vom zu ersetzenden Artikel nur durch die Verpackungseinheit.

recommended

Der Verkäufer hält den Ersatzartikel für einen adäquaten Ersatz und spricht eine Empfehlung aus. In diesem Fall wird empfohlen, die Artikelbeschreibung im nachfolgenden Element cbc:Description mitzuteilen.

 

Regel: Availability

Die Verfügbarkeit eines Artikels wird in einem Element vom Typ vco:AvailabilityType mitgeteilt. Die Inhalte seiner Kind-Elemente einer veloconnect-konformen Implementierung genügen den folgenden Regeln.

  1. Im Element vco:Code wird die Verfügbarkeit wie folgt kodifiziert:
    - available: Der Artikel ist in der gewünschten Menge lieferbar
    - partially_available: Der Artikel ist nur in einer Teilmenge lieferbar
    - expecting_delivery: Der Artikel ist nicht in der gewünschten Menge lieferbar, eine Lieferung wird aber durch den Käufer in absehbarer Zeit erwartet
    - not_available: Der Artikel ist nicht lieferbar. Weitere Angaben sind nicht möglich.

  2. Im Element AvailableQuantity wird die lieferbare Menge angegeben. Eine Angabe erfolgt nur, wenn der Code partially_availlable oder expecting_delivery verwendet wird. Falls der Code partially_available verwendet wird, muss die lieferbare Menge angegeben werden.

  3. Im Element cbc:ExpectedDeliveryDate wird mitgeteilt, wann der Verkäufer voraussichtlich die angeforderte Menge liefern kann. Dieses Element ist nur dann zu verwenden, wenn der Code expecting_delivery verwendet wird. Wenn in diesem Falle dieses Element nicht ausgefüllt wird, muss der Server in seinem veloconnect-Profil mit der Eigenschaft Order.expectingDelivery angeben, in welchem Zeitraum mit der Lieferung zu rechnen wird.

  4. Falls der Verkäufer einen oder mehrere Ersatzartikel angeben möchte, kann dies mit dem Element ItemReplacement gemäß Regel: ItemReplacement geschehen.

In Webshops wird zur Kennzeichnung der Verfügbarkeit von Artikeln zumeist ein Ampelsystem mit den Farben grün, gelb und rot verwendet. In der veloconnect Terminologie haben wir folgende Entsprechung:

  • available: grün

  • partially_available: gelb

  • expecting_delivery: gelb

  • not_available: rot

Bei Ampelfarbe gelb können mit veloconnect zusätzliche Informationen übermittelt werden. Die übermittelten Angaben zur Verfügbarkeit sollen den Einzelhändler in die Lage versetzen, zu entscheiden, ob und wann mit einer Lieferung zu rechnen ist, um ggf. auch nach Alternativen zu suchen.

Es ist dazu nicht erforderlich, die exakten Lagerdaten per veloconnect nach aussen zu geben. Folgende Massnahmen bei der Implementierung sind also völlig legitim und konform zur Spezifikation:

  • ist der Lagerbestand ausreichend, wird immer available übermittelt, auch wenn die angefragte Menge den Lagerbestand überschreitet

  • bei partially_available oder expecting_delivery kann als lieferbare Menge durchaus auch die angefragte Menge anstelle der tatsächlich lieferbaren Menge angegeben werden

Es liegt in der Verantwortung des Lieferanten zu entscheiden, wie aktuell die Daten sind, aufgrund deren die Verfügbarkeit ermittelt wird. Es ist dabei völlig legitim, abhängig vom Kontext mit unterschiedlichen Datengrundlagen zu arbeiten. Z.B. beim Download aller Artikeldaten per TextSearch oder bei massenhaften Artikelabfragen per GetItemDetailsList sind die Anforderungen an die Aktualität nicht so hoch wie im Kontext einer Bestellung oder bei Abfrage einzelner Artikel per GetItemDetails.

Umgekehrt daraus ergibt sich für Clients:

  • Verfügbarkeiten sollten im Bestellkontext immer direkt vom veloconnect Server geholt werden

  • massenweise Abfrage von Verfügbarkeit hat keinen Sinnn

Regel: OrderResponse(Client)

Ein veloconnect-konformer Client ordnet jedem der zurückgelieferten Elemente OrderResponseLine und RequestReplacement eine Zeile der normalisierten Bestellung mittels der Bestellnummer (SellersItemIdentification) zu, und überprüft für jede Zeile der normalisierten Bestellung, ob einer der folgenden Fälle vorliegt. Jedes Vorkommnis eines solchen Falles ist dem Benutzer mit allen relevanten Information mitzuteilen. Dieser hat daraufhin die Möglichkeit, die Bestellung abzuändern und den Bestellvorgang fortzusetzen oder abzubrechen. Alternativ besteht auch die Möglichkeit, Regeln festzulegen, wie in jedem dieser Fälle die Bestellung modifiziert werden soll und unter welchen Bedingungen mit der modifizierten Bestellunge fortgefahren wird oder diese abgebrochen wird. Für jeden einzelnen Posten der Bestellung ist jeder der folgenden Fälle zu berücksichtigen:

  1. Die Zeile ist einem Element ItemUnknown zugeordnet worden. Es ist davon auszugehen, dass die Bestellnummer falsch ist.

  2. Die Zeile ist einem Element RequestReplacement zugeordnet worden. Es ist davon auszugehen, dass die Bestellnummer veraltet ist.

  3. Der Artikel ist nicht oder nicht vollständig lieferbar. (Für diesen und die folgenden Fälle ist vorausgesetzt, dass der Zeile ein Element OrderResponseLine zugeordnet wurde.)

  4. Die jeweiligen Mengenangabe sind verschieden.

  5. In der Bestellung ist ein Lieferdatum explizit angegeben und dieses weicht ab von der Angabe in OrderResponseLine.

  6. In der Bestellung ist ein Nachlieferungsverhalten explizit gefordert und dieses weicht ab von der Angabe in OrderResponseLine