Formatbeschreibung: Order

Allgemeines

Das XML-Format für Orders basiert auf dem Standardformat für XML-Kataloge. In einer Bestellung ist eine Bestellposition genau eine mögliche Konfiguration eines Lieferbereichs, der im Katalog definiert wurde.

Es wird zwischen konfigurierbaren und einfachen Produkten unterschieden.

Einfache (nicht konfigurierbare) Produkte

Solche Produkte können bestellt werden, indem Sie die gewünschte Menge angeben ohne Auswahl bestimmter Produktfeatures. Eine articleID beschreibt genau ein bestimmtes Produkt mit klar definierten Produkt-Eigenschaften (Merkmalen).

Beispiel:

„Wöhlk ContactCare Kombilösung - 360ml“

Konfigurierbare Produkte

Solche Produkte (Kontaktlinsen, Brillengläser, Fassungen) sind mit unterschiedlichen Kombinationen von Produkt-Eigenschaften erhältlich.

Beispiel:

Kontaktlinse: sphere, diameter, radiusBasecurve

Fassung: colour, size, templeLength

Für eine gültige Bestellung, müssen alle bestellrelevanten Produkt-Eigenschaften (includeInOrder=true) in der Bestellung unter Konfiguration definiert werden.

Aufbau des Bestellformates (Order.xml)

Im Element Order werden allgemeine Informationen zur Bestellung definiert. Es gliedert sich in die zwei Bereiche Client und OrderItems.

Die Validierung erfolgt auf Basis der jeweils aktuellsten Schema-Version. Diese ist unter folgender Url erreichbar:

https://templates.look4optics.com/v_1_13/order.xsd

Unter Client besteht die Möglichkeit optional Adressinformationen zum Besteller anzugeben.

Im Anschluss erfolgt die Beschreibung der einzelnen Auftragspositionen. Hier sind nur Produktmerkmale enthalten, die im Katalog als bestellrelevant (includeInOrder=true) definiert sind. Jede Auftragsposition enthält eine gültige Konfiguration aus den im Katalog definierten Konfigurationsvarianten.

Liste der Standard Produkteigenschaften

Die Liste der FeatureTemplates finden Sie in dem Dokument ‚Übersicht der Feature Templates‘.

Das Element Order

Das Element Order enthält die Elemente Client (Informationen zum Besteller) und OrderItems (Bestellpositionen).

Das Element Order beginnt mit der Definition allgemeiner Informationen zur Bestellung.

Die Werte ‚schemaMajorVersionID‘ und ‚schemaMinorVersionID‘ sollten beim Schreiben fest in der Bestellsoftware hinterlegt sein, da sie zeigen, welche Version des Standards beim Aufbau des Dokuments verwendet wird. So können sich andere Programme beim Parsen des Dokuments darauf einstellen. Die Werte können in der Sendersoftware hochgesetzt werden, wenn es eine neue Standard-Version gibt und das Programm auf Kompatibilität geprüft wurde.

Für die Beschreibung stehen nachfolgende Attribute zur Verfügung:

Attribute	Type / Use	Description / Example
catalogID	xs:string required	Version des Katalogformates auf dessen Basis die Erfassung der Auftragspositionen erfolgte (z.B. Schema_Catalog_1_6)
catalogName	xs:string optional	Name des Kataloges auf dessen Basis die Erfassung erfolgte (z.B. Catalog 1.6)
clientOrderID	xs:string required	ID der Bestellung (des Übertragungssatzes) auf Senderseite (z.B. 00023-345785)
originalClientOrderID	xs:string optional	Bestellnummer des ursprünglichen Kunden, z.B. bei Bestellungen von Home Delivery Services (z.B. 00023-345785)
clientSupplierID	xs:string optional	ID des Herstellers beim Kunden (z.B. Woehlk-123456)
currency	xs:string optional	Währung (z.B. EURO)
generationDate	xs:dateTime optional	Datum und Zeit der Auftragserstellung (z.B. 2011-02-11T11:48:34)
generatorInfo	xs:string optional	Information zur Generierungsquelle, Bezeichnung bzw. Version der Software (z.B. Look4 Webservices Test)
schemaMajorVersionID	xs:integer required	Hauptversionsnummer für die Beschreibung der aktuellen Schema Version (z.B. 1)
schemaMinorVersionID	xs:integer required	Unterversionsnummer für die Beschreibung der aktuellen Schema Version (z.B. 0)
supplierID	xs:string required	UstID des Herstellers an den die Bestellung gesendet wird, Land und Nummer ohne Trennzeichen (z.B. DE813058544)
supplierName	xs:string optional	Name des Herstellers an den die Bestellung gesendet wird (z.B. Woehlk)
vatRate	xs:decimal optional	Mehrwertsteuersatz in % (z.B. 19)

Beispiel XML-Code:

<Order catalogID="catalog_de_de.xml" supplierID="DE813058544"
  generatorInfo="Look4 Webservices Test" generationDate="2017-02-11T11:48:34"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation=
  "https://templates.look4optics.com/v_1_13/order.xsd"
  clientOrderID="00023-345785" schemaMajorVersionID="1"
  schemaMinorVersionID="13" >
</Order>

Das Element Client

Das Element Client enthält die zwei Attribute clientID (Kundennummer beim Lieferanten) und clientName (Firmenname). Optional kann über responseMail die Mailadresse mitgegeben werden, an die Statusmeldungen für diesen Auftrag versendet werden sollen. Außerdem können optional noch Adressangaben gemacht werden (z.B. Lieferadresse ggf. auch für Endkunden falls diese nicht mit der Bestelladresse übereinstimmt).

Attribute	Type / Use	Description / Example
clientID	xs:string required	Kundennummer beim Lieferanten (z.B. 012345)
clientName	xs:string optional	Firmenname des Kunden (z.B. Schmidt Optik GmbH)
responseMail	xs:string optional	Mailadresse für Statusmeldungen (z.B. antwort@optik-test-schmidt.de)

Das Element Address hat folgende Attribute:

Im Element Address können mehrere Adressen mitgegeben werden. Diese Angaben sind optional. Für die Mitgabe von abweichenden Lieferadressen wird die Lieferadresse hier mitgegeben und kann unter OrderItems einzelnen Auftragspositionen zugeordnet werden. Somit können beispielsweise durch die Firmen-Zentrale Bestellungen für mehrere Filialen in einem Auftrag versendet werden. Mit der Adresse können auch die zugehörigen clientID (Kundennummer der Filiale beim Lieferanten) übergeben werden.

Das Handling für abweichende Lieferadressen ist bei den Herstellern unterschiedlich und sollte deshalb immer mit LOOK4 oder den betreffenden Lieferanten abgestimmt bzw. in der Testphase umfassend getestet werden.

Attribute	Type / Use	Description / Example
addressID	xs:string required	Eindeutige ID für eine Adresse. Diese kann später einem oder mehreren Aufträgen zugeordnet werden - abweichende Lieferadresse (z.B. 123456)
addressType	xs:NMTOKEN required	Adresstyp, Standardwerte: MainAddress, ShippingAddress, BillingAddress (z.B. MainAddress)
city	xs:string required	Stadt (z.B. Berlin)
clientBranchID	xs:string optional	Filialnummer des Kunden (z.B. 1234)
clientID	xs:string optional	Kundennummer (z.B. 123423)
clientType	xs:NMTOKEN optional	Kundenart, Standardwerte: Consumer, Branch, Retailer (z.B. Retailer)
email	xs:string optional	E-Mail-Adresse (z.B. mail@optician-test-smith.co.uk)
fax	xs:string optional	Fax (z.B. +0044 1302 344 321)
isoCountryCode	xs:language required	ISO Länderkennzeichen (z.B. GB)
name	xs:string required	Name (z.B. Schmidt Optik GmbH)
name2	xs:string optional	Name 2 (z.B. Augenoptik und mehr)
phone	xs:string optional	Telefon (z.B. +0044 1302 344 123)
street	xs:string required	Strasse (z.B. Hauptstrasse 123)
zip	xs:string required	PLZ (z.B. 12345)

Beispiel XML-Code:

<Addresses>
    <Address clientType="Branch" addressID="1" addressType="MainAddress"
      name="Schmidt Optik GmbH" name2="Augenoptik und mehr"
      zip="10995" city="Berlin" isoCountryCode="DE" phone="+0049 030 123459-0"
      fax="+0049 030 123459-1" email="filiale@optik-test-schmidt.de" />
    <!-- Adresse der Filiale -->
    <Address clientType="Retailer" addressID="2" addressType="BillingAddress"
      name="Schmidt Optik GmbH Verwaltung" name2="Augenoptik und mehr"
      zip="10999" city="Berlin" isoCountryCode="DE" phone="+0049 030 123456-0"
      fax="+0049 030 123456-1" email="zentrale@optik-test-schmidt.de" />
    <!-- Adresse der Zentrale -->
    <Address clientType="Consumer" addressID="3" addressType="ShippingAddress"
      name="Heinrich Kiefer" street="Kurze Straße 1" zip="41235" city="Frankfurt"
      isoCountryCode="DE" phone="+0049 069 123459-0"
      email="mail@Heinrich-Kiefer-Test.de" />
    <!-- Adresse des Endkunden -->
</Addresses>

Das Element OrderItems

Jedes Element OrderItems kann aus einem oder mehreren Elementen OrderItem bestehen. Jede OrderItem beschreibt eine Bestellposition. Die Referenzierung für die Statusabfrage und Zuordnung einzelner Auftragspositionen erfolgt über das Attribut clientOrderItemID. Dieses Feld muss bei Bestellungen per Webservice immer gefüllt sein. Zur Beschreibung werden die folgenden Attribute verwendet:

Attribute	Type / Use	Description / Example
addressID	xs:string optional	ID der zugehörigen Adresse (z.B. 123456)
articleID	xs:string required	Artikelnummer beim Lieferant (z.B. A2780)
articleName	xs:string optional	Artikelname (z.B. Contact Life Spheric Box)
clientArticleID	xs:string optional	Kundenartikelnummer (z.B. CL-CLSB-1234)
clientArticleName	xs:string optional	Artikelbezeichnung des Kunden (z.B. Woehlk - Contact Life Spheric Box)
clientOrderItemID	xs:string required	ID die (eindeutig) das OrderItem auf Senderseite bezeichnet. (z.B. LOOK4-WLK-01)
originalClientOrderItemID	xs:string optional	Kundennummer des ursprünglichen Kunden, z.B. bei Bestellungen von Home Delivery Services. (z.B. 23425234)
deliveryDate	xs:dateTime optional	Gewünschter Liefertermin (z.B. 2011-02-12T09:00:00)
eanCode	xs:string optional	EAN-Code, 13 Ziffern (z.B. 7234567891234)
netPurchasePrice	xs:decimal optional	Netto-Einkaufspreis (z.B. 20.00)
orderItemType	xs:NMTOKEN optional	Positionsart, Standardwerte: standard, freeOfCharge, returns (z.B. standard)
referenceName	xs:string optional	Kommission, Kunde / Auftragsnummer AO (z.B. Lager)
unitOfMeasure	xs:NMTOKEN optional	Bestellmengeneinheit, Standardwerte: bottles, boxes, pieces (z.B. boxes)
upcCode	xs:string optional	UPC-Code, 12 Ziffern (z.B. 723456789123)
vatRate	xs:decimal optional	Mehrwertsteuersatz in % (z.B. 19)

Beispiel XML-Code:

<OrderItems>
    <OrderItem articleID="A2780" articleName="Contact Life Spheric Box"
      clientOrderItemID="LOOK4-WLK-01" deliveryDate="2017-02-12T09:00:00"
      referenceName="Stock" unitOfMeasure="boxes">
        <Configuration quantity="1">
            <Feature templateID="Diameter" selectedValue="13.6"/>
            <Feature templateID="RadiusBasecurve" selectedValue="8.3"/>
            <Feature templateID="Sphere" selectedValue="-3"/>
        </Configuration>
    </OrderItem>
    <OrderItem articleID="A2780" articleName="Contact Life Spheric Box"
      clientOrderItemID="LOOK4-WLK-02" deliveryDate="2011-02-12T09:00:00"
      referenceName="Stock" unitOfMeasure="boxes">
        <Configuration quantity="1">
            <Feature templateID="Diameter" selectedValue="14.2"/>
            <Feature templateID="RadiusBasecurve" selectedValue="8.8"/>
            <Feature templateID="Sphere" selectedValue="0.25"/>
        </Configuration>
    </OrderItem>
    <OrderItem articleID="A3380" articleName="Premium Spheric 6er Box"
    clientOrderItemID="LOOK4-WLK-03" deliveryDate="2011-02-12T09:00:00"
    referenceName="Stock" unitOfMeasure="boxes">
        <Configuration quantity="1">
            <Feature templateID="Diameter" selectedValue="13.6"/>
            <Feature templateID="RadiusBasecurve" selectedValue="8.3"/>
            <Feature templateID="Sphere" selectedValue="-2.5"/>
        </Configuration>
    </OrderItem>
</OrderItems>

Das Element Configuration

Im Element Configuration wird die Konfiguration des Artikels beschrieben. Über das Attribut quantity wird die gewünschte Stückzahl dieser Konfiguration angegeben. Jede Konfiguration enthält eine Aufzählung der bestellrelevanten Produktmerkmale (Features). Die Gültigkeiten für den jeweiligen Artikel sind über den Katalog definiert.

Attribute	Type / Use	Description / Example
quantity	xs:positiveInteger required	Gewünschte Menge (z.B. 1)

Beispiel XML-Code:

(alle Produkt-Features im Catalog mit includeInOrder=true gekennzeichnet)

<Configuration quantity="1">
    <Feature templateID="Diameter" selectedValue="14.20"/>
    <Feature templateID="RadiusBasecurve" selectedValue="8.70"/>
    <Feature templateID="Sphere" selectedValue="-9.00"/>
</Configuration>

Das Element AdditionalData

Das seit Version 1.8 verfügbare optionale Element AdditionalData ermöglicht die Mitgabe von Zusatzinformationen zum Auftrag wie z.B. Keratografendaten für Kontaktlinsen oder Formdaten für Fassungen.

Attribute	Type / Use	Description / Example
dataDescription	xs:string optional	Beschreibung des Dateninhalts (z.B. SUFG4656)
dataFormat	xs:string required	Beschreibung des Datenformats (jpg, oma, dat) (z.B. dat)
dataSourceType	xs:string required	Beschreibung der Quelle oder des für die Messung benutzten Geräts (z.B. Topcon 231)
dataSourceVersion	xs:string required	Version der benutzten Quelle oder des Geräts (z.B. TR14)
dataType	xs:string required	Datentyp (z.B. Keratograph)

Das Element Feature

Attribute	Type / Use	Description / Example
selectedValue	xs:string required	Werte zum jeweiligen Parameter (z.B. 14.2)
templateID	xs:string required	Name des Parameters (z.B. Diameter)

Hier müssen alle im Katalog als bestellrelevant (includeInOrder=true) definierten Produkteigenschaften (Features) angegeben werden. Alle im Standard definierten Features finden Sie im Dokument ‚Übersicht der Feature Templates‘.

Beispiel XML-Code für eine komplette Bestellung

<Order catalogID="catalog_de_de.xml" supplierID="DE813058544"
  generatorInfo="Look4 Webservices Test" generationDate="2017-02-11T11:48:34"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation=
  "https://templates.look4optics.com/v_1_13/order.xsd"
  clientOrderID="00023-345785" schemaMajorVersionID="1"
  schemaMinorVersionID="13" >
    <Client clientID="00011" clientName="Testkunde11" responseMail="info@look4.de">
    <Addresses>
    <Address clientType="Branch" addressID="1" addressType="MainAddress"
      name="Schmidt Optik GmbH" name2="Augenoptik und mehr"
      zip="10995" city="Berlin" isoCountryCode="DE" phone="+0049 030 123459-0"
      fax="+0049 030 123459-1" email="filiale@optik-test-schmidt.de" />
    <!-- Adresse der Filiale -->
    <Address clientType="Retailer" addressID="2" addressType="BillingAddress"
      name="Schmidt Optik GmbH Verwaltung" name2="Augenoptik und mehr"
      zip="10999" city="Berlin" isoCountryCode="DE" phone="+0049 030 123456-0"
      fax="+0049 030 123456-1" email="zentrale@optik-test-schmidt.de" />
    <!-- Adresse der Zentrale -->
    <Address clientType="Consumer" addressID="3" addressType="ShippingAddress"
      name="Heinrich Kiefer" street="Kurze Straße 1" zip="41235" city="Frankfurt"
      isoCountryCode="DE" phone="+0049 069 123459-0"
      email="mail@Heinrich-Kiefer-Test.de" />
    <!-- Adresse des Endkunden -->
</Addresses>
    </Client>
    <OrderItems>
        <OrderItem articleID="A2780" articleName="Contact Life Spheric Box"
          clientOrderItemID="LOOK4-WLK-01" deliveryDate="2017-02-12T09:00:00"
          referenceName="Stock" unitOfMeasure="boxes">
                <Configuration quantity="1">
                <Feature templateID="Diameter" selectedValue="13.6"/>
                <Feature templateID="RadiusBasecurve" selectedValue="8.3"/>
                <Feature templateID="Sphere" selectedValue="-3"/>
            </Configuration>
        </OrderItem>
        <OrderItem articleID="A2780" articleName="Contact Life Spheric Box"
          clientOrderItemID="LOOK4-WLK-02" deliveryDate="2017-02-12T09:00:00"
          referenceName="Stock" unitOfMeasure="boxes">
            <Configuration quantity="1">
                <Feature templateID="Diameter" selectedValue="14.2"/>
                <Feature templateID="RadiusBasecurve" selectedValue="8.8"/>
                <Feature templateID="Sphere" selectedValue="0.25"/>
            </Configuration>
        </OrderItem>
        <OrderItem articleID="A3380" articleName="Premium Spheric 6er Box"
          clientOrderItemID="LOOK4-WLK-03" deliveryDate="2017-02-12T09:00:00"
          referenceName="Stock" unitOfMeasure="boxes">
            <Configuration quantity="1">
                <Feature templateID="Diameter" selectedValue="13.6"/>
                <Feature templateID="RadiusBasecurve" selectedValue="8.3"/>
                <Feature templateID="Sphere" selectedValue="-2.5"/>
            </Configuration>
        </OrderItem>
    </OrderItems>
</Order>

Vorankündigung für Schema 2.0

Die beiden IDs clientOrderID und clientOrderItemID werden verpflichtend. Dabei müssen die beiden IDs nicht für sich genommen unique sein, aber in Kombination.

So werden auch nach Teilannahme und Korrektur gesplittete Aufträge unterstützt.

Übertragung der Bestellung

Das Format ist unabhängig von der Art der Datenübertragung. Die Übertragung erfolgt per Webservice mit einer HTTP-Anforderung (POST). Die Bestellung über die Webservices von LOOK4Optics erfolgt an folgende URL:

** Produktiv: ** http://www.look4optics.de/OrderService/PlaceOrder.ashx

Für detaillierte Informationen kontaktieren Sie bitte den LOOK4 Support oder direkt den Lieferanten. Die URLs für Hersteller die eigene Webservices betreiben, finden Sie in den jeweiligen Katalogen im Element WebServices.