Format description: OrderResponse

General

The document OrderResponse is used to exchange several status stages of orders from the supplier to the customer system. The different possible stages can be:

1:Order Accepted
2:Order not accepted - and defined error code and error message

Format layout for exchange of order status (OrderResponse)

The format for status exchange is based on the formats Catalog.xml and Order.xml. For a simple realisation of a status exchange exchange there are only a small number of information needed. For different use cases a couple of additional information can be transferred.

An order confirmation relates always to exact one order with one or more order positions.

The validation is based on the latest schema version with the following link:

http://templates.look4optics.com/v_2_0/OrderResponse.xsd

The element OrderResponse

The element OrderResponse contains at least one of the attributes clientOrderID, clientID or supplierID and the elements OrderError and OrderItems. The element OrderItems can consist of one ore more OrderItem elements.

The element OrderResponse can have the following attributes:

Attribute Type / Use Description / Example
clientID xs:NMTOKEN required Client number, at supplier (e.g. 012345)
clientName xs:NMTOKEN optional Client name (e.g. Smith Optics Ltd.)
clientOrderID xs:NMTOKEN required Order ID on the side of the client - key for mapping (e.g. 00023-345785)
clientSupplierID xs:string optional Unique ID of the supplier at client (e.g. Woehlk-123456)
currency xs:string optional Currency (e.g. EURO)
generationDate xs:dateTime required Generation date of the status file (e.g. 2011-02-11T11:48:34)
generatorInfo xs:NMTOKEN optional Description of the generator software (e.g. Look4 Webservices Test)
orderDate xs:dateTime optional Date and time of the order generation (e.g. 2011-02-11T11:48:34)
orderResponseID xs:string optional Unique ID for the order response (e.g. OR-20110211105912-123)
orderTransmissionType xs:NMTOKEN optional Order transmission type, standard values: fax, phone, onlineShop, edi (e.g. edi)
schemaMajorVersionID xs:integer required Major version number for the description of the current schema version (e.g. 1)
schemaMinorVersionID xs:integer required Minor version number for the description of the current schema version (e.g. 0)
supplierID xs:string required Unique ID of the supplier, VAT-ID (e.g. DE813058544)
supplierName xs:string optional Name of the supplier (e.g. Woehlk)

The element OrderError

The element OrderError contains the attributes errorCode and errorDescription. If this element exists the complete order is invalid. The reason for the error is given back as errorCode and errorDescription.

List error codes for element OrderError

The list describes syntactic or logical errors of the element Order.

Attribute Description Type Example
errorCode Error code optional 5
errorDescription Error description optional No valid order item existing

List error descriptions

Value Inherent errorDescription
1 Addresses: addressID s not unique
2 Order position (OrderItem) references unknown address
3 Client unknown at supplier/ shop service (if only known clients are accepted)
4 Wrong SupplierID (supplier not known in recipient system)
5 No (valid) order position exists
6 Not specified error on line item level
7 Not specified error in order

The element OrderItems

The element OrderItems consists of one or more elements OrderItem.

The element OrderItem

The element OrderItem contains the status information for one order item (order position).

It contains the following attributes:

Attribute Type / Use Description / Example
articleID xs:NMTOKEN optional Article ID (e.g. A2780)
articleName xs:string optional Name of the Article (e.g. Contact Life Spheric Box)
clientArticleID xs:string optional Article number at client (e.g. CL-CLSB-1234)
clientArticleName xs:string optional Article name at client (e.g. Woehlk - Contact Life Spheric Box)
clientOrderItemID xs:NMTOKEN required ID of order item at optician software of client (e.g. LOOK4-WLK-01)
deliveryDate xs:dateTime optional Estimated delivery date (e.g. 2015-04-22T09:00:00)
deliveryQuantity xs:integer optional Delivered quantity (e.g. 1)
eanCode xs:string optional EAN-Code, 13-digit (e.g. 7234567891234)
errorCode xs:NMTOKEN optional Error code (e.g. 4)
errorDescription xs:string optional Error description (e.g. Article 'A2780': Selected DeliveryRange doesnt contain feature 'Diameter' with value '15.6'.)
netPurchasePrice xs:decimal optional Net purchase price (e.g. 20.00)
orderedQuantity xs:integer optional Ordered quantity (e.g. 1)
orderItemStatus xs:NMTOKEN required Order status information, see list of values (e.g. 0)
orderItemType xs:NMTOKEN optional Item type: standard, freeOfCharge, returns (e.g. standard)
referenceName xs:NMTOKEN optional Commission at client (e.g. Stock)
shipmentDate xs:dateTime optional Shipment date (e.g. 2015-04-22T09:00:00)
shipmentType xs:string optional Shipment type: postal, UPS, … (e.g. postal)
supplierOrderID xs:string optional Order ID at the supplier (e.g. 2011-159874)
supplierOrderItemID xs:NMTOKEN optional ID of order item at supplier (e.g. Smith-WLK-01)
unitOfMeasure xs:NMTOKEN optional Unit of measure: pieces, boxes, bottles (e.g. boxes)
upcCode xs:string optional UPC-Code, 12-digit (e.g. 723456789123)

Standard values for the attribute orderItemType

standard:If attribute is not indicated standard is applied
freeOfCharge:Item free of charge
returns:Returns item

Standard values for the attribute orderTransmissionType

phone:Order by phone
fax:Fax order
onlineShop:Order via online shop
edi:Electronic order between two ERPs (EDI order)

Standard values for the attribute orderItemStatus

0:Submitted (order/OrderItem received by recipient system)
1:Transmitted (order /OrderItem has been transmitted to supplier system)
2:Received (supplier system has received the OrderItem)
3:In Progress (OrderItem in progress at supplier)
4:DeliveryDate (Notification about estimated delivery date)
5:Delivered (order has been sent by supplier)
8:Modified (order has been modified by supplier, e.g. 3x3 boxes instead of 1x9 box)
9:Cancelled (if order has been cancelled after transmission)
10:Error (error during processing order - defined error codes for automatic error handling and error description as text (display))

List ErrorCodes for element OrderItems

Errors related to one specific order item (order position):

1:Article for OrderItem not found in catalog –> reason e.g.old catalog on client side
2:Invalid configuration: unknown feature –> reason e.g.old catalog on client side
3:Invalid configuration: selected delivery range does not contain a selected feature –> reason e.g.old catalog on client side
4:Invalid configuration: invalid value
5:Invalid configuration: missing feature (“incomplete configuration”) –> old catalog on client side
6:Invalid number of articles
7:Client known at receiver system but not allowed to order this article

Steps of order check and corresponding status messages

The checking of the orders at the receiver system works on three levels which requires corresponding messages.

General check

First the order xml has to be checked itself. If an error is found, (no xml, invalid XML, no schema referenced) that means the complete order is invalid, a corresponding status message will be sent back to the sender address.

Check of the element Order

Then the check is carried out at the order level. If an error occurs here, an error message is sent in the OrderResponse.

Check of the element OrderItem

If the check on order level was ok, the check is completed by checking on order item level. Is an order item invalid, there will be sent also a corresponding error message. Here as well will be answered to the first found answer address.

All from receiver system accepted order items will be confirmed in a corresponding status mail which contains one confirmation line for each order item.

Analysis of status and error messages

Generally for each order at least one status message (received) has to be send. Does the sender system not receive a status message (OrderResponse) the order was not received at the side of the supplier. Information about OrderItems with errors and status updates can also be sent separately. That means an OrderResponse message must not contain mandatorily all OrderItems of an order (error or status updates).

The status messages must evaluate also level by level.

How to:

  1. No OrderResponse –> order not received on receiver side
  2. OrderResponse with element OrderError –> order generally invalid or incorrect. The element Order contains the errorCode and errorDescription for error analysis
  3. OrderResponse with element OrderItems –> the OrderResponse contains the order status for the single order items. Incorrect positions include errorCode and errorDescription for an automatic evaluation.

Example-XML-Code for status exchange

Example 1 (error message order completely invalid)

<OrderResponse xsi:noNamespaceSchemaLocation=
  "http://templates.look4optics.com/v_2_0/OrderResponse.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  clientOrderID="00023-345785" orderDate="2017-02-11T14:35:57.3850000+01:00"
  supplierID="DE813058544" supplierName="Woehlk" clientID="00011"
  clientName="Testkunde11" generationDate="2017-02-11T14:35:57.6350000+01:00"
  schemaMajorVersionID="1" schemaMinorVersionID="12" >
    <Order clientOrderID="00023-345785" errorCode="3"
      errorDescription="customer '00011' not found in shopservice"/>
</OrderResponse>

Example 2 (invalid ``OrderItems``)

<OrderResponse xsi:noNamespaceSchemaLocation=
  "http://templates.look4optics.com/v_2_0/OrderResponse.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  clientOrderID="00023-345785" orderDate="2017-02-11T14:35:57.3850000+01:00"
  supplierID="DE813058544" supplierName="Woehlk" clientID="00011"
  clientName="Testkunde11" generationDate="2017-02-11T14:35:57.6350000+01:00"
  schemaMajorVersionID="1" schemaMinorVersionID="12" >
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-01" orderItemStatus="10"
        errorCode="4" errorDescription="Article 'A2780':
        Selected DeliveryRange doesnt contain feature 'Diameter' with value '15.6'."
        upcCode="123456789123" netPurchasePrice="10" grossPrice="15"/>
    </OrderItems>
</OrderResponse>

Example 3 (confirmation for ``OrderItems``)

<OrderResponse xsi:noNamespaceSchemaLocation=
  "http://templates.look4optics.com/v_2_0/OrderResponse.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  clientOrderID="00023-345785" orderDate="2017-02-11T14:35:57.3850000+01:00"
  supplierID="DE813058544" supplierName="Woehlk" clientID="00011"
  clientName="Testkunde11" generationDate="2017-02-11T14:35:57.6350000+01:00"
  schemaMajorVersionID="1" schemaMinorVersionID="12" >
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-02" orderItemStatus="0"
          upcCode="123456789124" netPurchasePrice="11" grossPrice="16"/>
        <OrderItem clientOrderItemID="LOOK4-WLK-03" orderItemStatus="0"
          upcCode="123456789125" netPurchasePrice="12" grossPrice="17"/>
    </OrderItems>
</OrderResponse>

Example 4 (Status updates)

<OrderResponse xsi:noNamespaceSchemaLocation=
  "hhttp://templates.look4optics.com/v_2_0/OrderResponse.xsd"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  clientOrderID="00023-345785" orderDate="2017-02-11T14:35:57.3850000+01:00"
  supplierID="DE813058544" supplierName="Woehlk" clientID="00011"
  clientName="Testkunde11" generationDate="2017-02-11T14:35:57.6350000+01:00"
  schemaMajorVersionID="1" schemaMinorVersionID="12" >

    <!-- This example file contains various examples for the different
         status updates. To have a valid file, use ONE element
         <OrderItems> and delete the other -->

    <!-- Example: Received (supplier system has received the OrderItem) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-02" orderItemStatus="2"
          upcCode="123456789124" netPurchasePrice="11" grossPrice="16"/>
    </OrderItems>

    <!-- Example: In Progress (OrderItem in progress at supplier) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-02" orderItemStatus="3"
          upcCode="123456789124" netPurchasePrice="11" grossPrice="16"/>
    </OrderItems>

    <!-- Example: DeliveryDate (Notification about estimated delivery date) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-02" orderItemStatus="4"
          upcCode="123456789124" deliveryDate="2017-02-24T09:00:00"
          netPurchasePrice="11" grossPrice="16"/>
    </OrderItems>

    <!-- Example: DeliveryDate (Notification about estimated delivery date,
         second message) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-02" orderItemStatus="4"
          upcCode="123456789124" deliveryDate="2017-02-25T09:00:00"
          netPurchasePrice="11" grossPrice="16"/>
    </OrderItems>

    <!-- Example: Delivered (order has been sent by supplier) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-01" orderItemStatus="5"
          upcCode="123456789123" netPurchasePrice="10" grossPrice="15"/>
    </OrderItems>

    <!-- Example: Error (error during processing order - defined error codes
        for automatic error handling and error description as text (display)) -->
    <OrderItems>
        <OrderItem clientOrderItemID="LOOK4-WLK-01" orderItemStatus="10"
          errorCode="1"
          errorDescription="Article for OrderItem not found in catalog"
          upcCode="123456789123" netPurchasePrice="10" grossPrice="15"/>
    </OrderItems>

</OrderResponse>
Contact / Legal