Order Web services¶
The order Web services allow to place orders in a supplier’s shop and to query the status
of a previously placed order. Place a new order with PlaceOrder and display the order status of
single orders with getOrderStatus.
Please note that it is possible that the web service is unavailable due to an error or internet problem and so the placement of the order might not be confirmed. In this case, your application must be able to hold non-placeable orders and place them later after the service went online.
Place order: PlaceOrder¶
Request¶
The request is carried out as a HTTP request (POST) with ticket.
| Productive URL: | https://www.look4optics.de/OrderService/PlaceOrder.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
|---|---|
| Test URL: | http://test.look4optics.de/OrderService/PlaceOrder.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
The test URL points to a separate test project that exists for every supplier. This test project has its own users and catalogs. You will receive an account for the test systems on request at Look4.
Orders placed in the test system are not transferred to the suppliers, thus such an order won’t change its order status after the (hypothetical) transfer. If you want to test any change regarding the order status when sending an order to the supplier’s ERP system, you need a test client in the productive shop system, which need also to be created in the supplier’s ERP system. Many suppliers support the creation of such test accounts.
Instead of the usage of CGI parameters, an XML file (order format) is passed in the request’s body. This format is described in detail in the documentation of the SPECTARIS format schemes.
Crucial parameters for placement are all defined in the XML file. Important for the
correct mapping of the order are the parameters clientID, clientOrderID (unique
order number for the query of OrderResponse and ASN, that in the order e.g. can be defined
from the optician software) and clientOrderItemID (item number of an article, that
also can be defined from the optician software).
In addition, with the fields supplierID and catalogID in the order must be
defined to which catalog the order applies. The respective specifications are returned
from the Web service GetCatalogInfo.ashx.
Example¶
<?xml version="1.0" encoding="utf-8"?> <Order catalogID="catalog.xml" supplierID="DE813122224" clientOrderID="01992-987654" generationDate="2017-02-19T13:19:18.0000000+01:00" generatorInfo="Look4 Test" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://templates.look4optics.com/v_1_13/order.xsd" schemaMajorVersionID="1" schemaMinorVersionID="13"> <Client clientID="987654" clientName="Test client Look4" responseMail="info@look4.de"/> <OrderItems> <OrderItem articleID="BFNTR3" articleName="Biofinity toric (3er Box)" clientOrderItemID="123456"> <Configuration quantity="1"> <Feature templateID="AxisCylinder" selectedValue="70"/> <Feature templateID="Cylinder" selectedValue="-1.25"/> <Feature templateID="RadiusBasecurve" selectedValue="8.7"/> <Feature templateID="Sphere" selectedValue="-6.5"/> <Feature templateID="Diameter" selectedValue="14.5"/> </Configuration> </OrderItem> <OrderItem articleID="BFNTR3" articleName="Biofinity toric (3er Box)" clientOrderItemID="123457"> <Configuration quantity="1"> <Feature templateID="AxisCylinder" selectedValue="80"/> <Feature templateID="Cylinder" selectedValue="-1.75"/> <Feature templateID="RadiusBasecurve" selectedValue="8.7"/> <Feature templateID="Sphere" selectedValue="-6"/> <Feature templateID="Diameter" selectedValue="14.5"/> </Configuration> </OrderItem> </OrderItems> </Order>
Response¶
The Web service either returns an OrderResponse document, or a generic fault format. The OrderResponse format is described explicitly in the documentation of the SPECTARIS formats.
Please find here an OrderResponse for a successful order (see above):
<?xml version="1.0" encoding="utf-8"?> <OrderResponse clientOrderID="01992-DEZZ70097" orderDate="2017-03-03T13:49:56.7306250+02:00" supplierID="DE813122224" supplierName="CooperVision GmbH" clientID="987654" clientName="Test client Look4" generationDate="2017-03-03T13:49:56.8868750+02:00"> <OrderItems> <OrderItem clientOrderItemID="123456" orderItemStatus="0"/> <OrderItem clientOrderItemID="123457" orderItemStatus="0"/> </OrderItems> </OrderResponse>
If possible, errors in the order are returned in the OrderResponse file, such as
if an order only was partially successful. If an OrderResponse is returned, the
HTTP status code is always 200.
Please find here an OrderResponse for a partially faulty order:
<?xml version="1.0" encoding="utf-8"?> <OrderResponse clientOrderID="01992-DEZZ70097" orderDate="2017-03-03T14:49:56.7306250+02:00" supplierID="DE813122224" supplierName="CooperVision GmbH" clientID="987654" clientName="Test client Look4" generationDate="2017-03-03T13:49:56.8868750+02:00"> <OrderItems> <OrderItem clientOrderItemID="123456" orderItemStatus="10" errorCode="4" errorDescription="None of the delivery ranges contains given configuration" /> <OrderItem clientOrderItemID="123457" orderItemStatus="0"/> </OrderItems> </OrderResponse>
Error code and description of the fault indicate the failure (in the above Case no valid configuration).
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 |
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) |
| 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 |
If the Order is invalid or has no schema, a critical error is returned, which is
issued in a generic format (see below). These error documents are issued always with
the HTTP status code 400.
The HTTP status codes:
| 200: | OrderResponse document is returned. This document can contain errors, e.g. if
an order only was partially successful |
|---|---|
| 400: | Error document is returned (critical error, e.g. missing schema or invalid XML file) |
| 500: | Internal error has occurred |
Example for error document¶
<Error code="2" description="XmlException: Ungültige Daten auf Stammebene. Zeile 1, Position 1." />
The following special codes can appear in the error document:
| 1: | RequestType is no POST |
|---|---|
| 2: | XML error (document could not be loaded; schema infringement; schema non-existent; Order object could not be deserialized) |
Place order: PlaceSkuOrder¶
Request¶
The request is carried out as a HTTP request (POST) with ticket.
| Productive URL: | https://www.look4optics.de/OrderService/PlaceSkuOrder.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
|---|---|
| Test URL: | http://test.look4optics.de/OrderService/PlaceSkuOrder.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
The test URL points to a separate test project that exists for every supplier. This test project has its own users and catalogs. You will receive an account for the test systems on request at Look4.
Orders placed in the test system are not transferred to the suppliers, thus such an order won’t change its order status after the (hypothetical) transfer. If you want to test any change regarding the order status when sending an order to the supplier’s ERP system, you need a test client in the productive shop system, which need also to be created in the supplier’s ERP system. Many suppliers support the creation of such test accounts.
Instead of the usage of CGI parameters, an XML file (order format) is passed in the request’s body. This format is described in detail in the documentation of the SPECTARIS format schemes.
The Webservice PlaceSkuOrder offers the possibility to easily transmit orders only with SKU ID. It’s an alternate possibility to order frames from customer systems using only the SKU ID (usually EAN Code). The Webservice generates automatically the corresponding order.xml file and also checks are done in the same way as mentioned in the chapter PlaceOrder. All orders are transferred to the suppliers always in the same format.
Crucial parameters for placement are all defined in the XML file. Important for the
correct mapping of the order are the parameters clientID, clientOrderID (unique
order number for the query of OrderResponse and ASN, that in the order e.g. can be defined
from the optician software) and clientOrderItemID (item number of an article, that
also can be defined from the optician software).
In addition, with the fields supplierID and catalogID in the order must be
defined to which catalog the order applies. The respective specifications are returned
from the Web service GetCatalogInfo.ashx.
Example¶
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <SkuOrder catalogID="catalog_de_de.xml" clientOrderID="46789" generatorInfo="Test-App" supplierID="DE812671943" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://templates.look4optics.com/v_1_13/SkuOrder.xsd"> <Client clientID="10627"> </Client> <SkuOrderItems> <SkuOrderItem skuID="5055022616680" quantity="2" clientOrderItemID="1"/> <SkuOrderItem skuID="111111111113" quantity="1" clientOrderItemID="2"/> <SkuOrderItem skuID="22222222222222" quantity="3" clientOrderItemID="=3"/> </SkuOrderItems> </SkuOrder>
Order status: getOrderStatus¶
The Web service getOrderStatus allows one to retrieve the status of a previously placed order.
(Currently there are no restrictions regarding how often one wishes to check this status)
Calling this web service results in the return of an OrderResponse or, in case of an exception, an error-document.
The returned dataset is filtered with respect to the requested filters (any of clientOrderID and clientOrderItemID).
Request¶
The request is carried out as HTTP request (POST) and always requires a ticket.
| Productive-URL: | https://www.look4optics.de/OrderService/GetOrderStatus.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
|---|---|
| Test-URL: | http://test.look4optics.de/OrderService/GetOrderStatus.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f
|
Order status: getOrderStatusList¶
This web service provides an efficient way to query the current status for a list of orders and order items.
Authentication (ticket parameter) is required. Each request must include a supplierID and your
clientID (with respect to the supplier), and at least one additional type of filter from the list below.
The Web service returns up to 1000 orders. In case that you get exactly 1000 results (e.g. their are actually more than 1000 results), try to narrow down your filter set.
Available filters¶
| supplierID (required): | |
|---|---|
VAT ID of the supplier |
|
| clientID (required): | |
Your Client ID for this supplier |
|
| clientOrderID (optional): | |
Unique ID of the requested order, that has been assigned at the placement from the optician software (optional) |
|
| clientOrderItemID (optional): | |
Item ID of the requested order, that has been assigned at the placement from the optician software (optional) |
|
| articleID (optional): | |
Article ID in XML catalog |
|
| desiredDeliveryDate (optional): | |
Desired delivery date |
|
| desiredDeliveryDateFrom (optional): | |
Desired delivery date from |
|
| desiredDeliveryDateTo (optional): | |
Desired delivery date to |
|
| expectedDeliveryDate (optional): | |
Estimated delivery date |
|
| expectedDeliveryDateFrom (optional): | |
Estimated delivery date from |
|
| expectedDeliveryDateTo (optional): | |
Estimated delivery date to |
|
| orderDate (optional): | |
Date in ISO 8601 format (example: |
|
| orderDateFrom (optional): | |
Date or timestamp (CET/CEST) in ISO 8601 format (example: |
|
| orderDateTo (optional): | |
Date or timestamp (CET/CEST) in ISO 8601 format (example: |
|
| orderItemState (optional): | |
Order item state (item level). Can be either the number of the state or the name, e.g.: “Transmitted” or “1”, or “Delivered” or “5”. |
|
| orderItemStateChangedSince (optional): | |
Date or timestamp (CET/CEST) in ISO 8601 format (example: |
|
| orderItemStateFrom (optional): | |
Order item state from (item level). Field stateValue of table OrderItemStates. |
|
| orderItemStateTo (optional): | |
Order item state to (item level). Field stateValue of table OrderItemStates. States: Invalid = -1 (e.g. if an order item refers to an unkown article in the catalog) Submitted = 0 (Order item was posted in the database, by shop or order-XML) Transmitted = 1 (Order was transmitted to manufacturer) MailReceived = 2 (Manufacturer has received the mail) InProgress = 3 (Order in progress at manufacturer) DeliveryDate = 4 (Notification of the estimated delivery date) Delivered = 5 (Order was shipped by the manufacturer) Cancelled = 9 |
|
| referenceName (optional): | |
Commission, client / order no. optician (e.g. stock) |
|
| shipmentDate (optional): | |
Shipment date. All orders with status delivered on this date. |
|
| supplierOrderID (optional): | |
Supplier order ID (e.g. 2016-159874) |
|
| supplierOrderItemID (optional): | |
Supplier order item ID (e.g. Smith-WLK-01) |
|
Request¶
The request is carried out as HTTP request (POST).
| Productive-URL: | https://www.look4optics.de/OrderService/GetOrderStatusList.ashx
|
|---|---|
| Test-URL: | http://test.look4optics.de/OrderService/GetOrderStatusList.ashx
|
Example request with Url parameters¶
https://www.look4optics.de/OrderService/GetOrderStatusList.ashx?ticket=efe1cc4c-820e-4756-ade2-2aa46385eb6f&supplierID=DE813122224&orderItemStateTo=Delivered&orderDateFrom=2016-06-01
Response¶
OrderResponse:
<OrderResponses> <OrderResponse clientOrderID="00000500196" orderDate="2016-06-20T10:19:36.55" supplierID="DE813122224" supplierName="CooperVision GmbH" clientID="DEZZ12345" clientName="Testkunde Look4" generationDate="2016-07-06T13:01:42.726625"> <OrderItems> <OrderItem clientOrderItemID="0027929_VOR0_R" orderItemStatus="1"/> <OrderItem clientOrderItemID="0027929_VOR0_L" orderItemStatus="1"/> </OrderItems> </OrderResponse> <OrderResponse clientOrderID="00000500195" orderDate="2016-06-20T08:59:03.053" supplierID="DE813122224" supplierName="CooperVision GmbH" clientID="DEZZ12345" clientName="Testkunde Look4" generationDate="2016-07-06T13:01:42.726625"> <OrderItems> <OrderItem clientOrderItemID="0027910_VOR0_R" orderItemStatus="1"/> <OrderItem clientOrderItemID="0027910_VOR0_L" orderItemStatus="1"/> </OrderItems> </OrderResponse> ... </OrderResponse> </OrderResponses>
The getOrderStatus and the getOrderStatusList Web service just as the placeOrder
Web service return either one or more OrderResponse elements or a single error-document.
In difference to the other web services, an additional response/error code is created:
getOrderStatus also returns one of 3 different HTTP status codes:
| 200: | OrderResponse document is returned. This document can contain errors, e.g. if
an order only was partially successful. |
|---|---|
| 400: | Error document is returned (critical error, e.g. missing schema or invalid XML file) |
| 500: | Internal error has occured |
The following special codes can appear in the error document:
| 1: | RequestType is no POST` |
|---|---|
| 2: | XML error (document could not be loaded; schema infringement; schema nonexistent; missing attributes in the XML document) |
| 3: | Order with transferred clientID and clientOrderID doesn’t exist in the
ShopService |
Overview VAT IDS¶
| Supplier | SupplierID | Order Web service |
|---|---|---|
| Alcon Pharma GmbH | DE142102094 | https://de.easy-myalcon.com |
| Alcon Ophthalmika GmbH (AT) | ATU36778901 | https://de.easy-myalcon.com |
| Alcon Switzerland, S.A. | CHE-116.268.023 | https://de.easy-myalcon.com |
| Appenzeller Kontaktlinsen | CHE-115.341.864 | no |
| Bach Optic GH-GmbH | DE123051490 | https://www.look4optics.de/OrderService |
| Bausch & Lomb GmbH | DE811322707 | https://www.look4optics.de/OrderService |
| BILOSA Handels GmbH | ATU5304980 | https://www.look4optics.de/OrderService |
| Clearlab GmbH | DE305189523 | in planning stage |
| CONIL AG | CHE-108.169.703 | https://www.look4optics.de/OrderService |
| Conta Optic GmbH | DE146150865 | https://www.look4optics.de/OrderService |
| Contopharma AG | CHE103.696.941 | https://www.look4optics.de/OrderService |
| CooperVision GmbH | DE813122224 | https://www.look4optics.de/OrderService |
| CooperVision France | FR06392002218 | https://www.look4optics.de/OrderService |
| CooperVision Nederland BV | NL801899680B01 | https://www.look4optics.de/OrderService |
| Falco Linsen AG (CH) | CHE-103.169.788 | in planning stage |
| Falco Linsen GmbH (EU) | DE283290059 | in planning stage |
| GALIFA Contactlinsen AG | CHE-107.964.135 | in planning stage |
| Hecht Contactlinsen GmbH | DE142211934 | http://87.106.47.254:8080/placeorder |
| Johnson & Johnson Vision Care | DE134846576 | https://www.look4optics.de/OrderService |
| Johnson & Johnson NL & UK | NL001119163B01 | https://www.look4optics.de/OrderService |
| Johnson & Johnson AB | SE556063251401 | https://www.look4optics.de/OrderService |
| mark’ennovy | DE283410674 | https://www.look4optics.de/OrderService |
| Menicon GmbH Kontaktlinsen | DE113571130 | https://www.look4optics.de/OrderService |
| MPG&E-Contactlinsen GmbH | DE812969725 | https://onlineshop.mpge.de/Ordering |
| Procornea Nederland B.V. | NL006298199B01 | https://www.look4optics.de/OrderService |
| SwissLens SA | FR78494802648 | no |
| Technop | in planning stage | |
| Wöhlk-Contact-Linsen GmbH | DE813058544 | https://www.look4optics.de/OrderService |
| Wöhlk Vertriebs-GmbH (AT) | DE813058544 | https://www.look4optics.de/OrderService |
Alcon Pharma GmbH, Hecht Contactlinsen GmbH and MPG&E-Contactlinsen GmbH use own Order Web services which correspond to the one described here, but yet require a HTTP Basic authentication..
Alcon Pharma GmbH¶
Order Web service: https://de.easy-myalcon.com
For further questions please contact Florian Knirsch, Tel. +49 6026 941245 or florian.knirsch@alcon.com
Hecht Contactlinsen GmbH¶
Order Web service: http://87.106.47.254:8080/placeorder
For further questions please contact Oliver Pries: +49 (0)761 40105-37 or Oliver.Pries@hecht-contactlinsen.de
MPG&E¶
Web service data for the test system:
https://onlineshop.mpge.de/TestOrdering/PlaceOrder.ashx
https://onlineshop.mpge.de/TestOrdering/GetOrderStatus.ashx
Web service data for the live system:
https://onlineshop.mpge.de/Ordering/PlaceOrder.ashx
https://onlineshop.mpge.de/Ordering/GetOrderStatus.ashx
Both systems require an unique activation for XML orders in advance. Also both systems require an HTTP Basic authentication request header with the valid logon data for each system for the MPG&E online shop (consisting of customer number and customer password).
Users or software houses contact best:
| Contact: | Oliver Schur, Johannes Heidenreich |
|---|---|
| Telephone: | +49 4322 750 840 |
| E-Mail: | team-edv@mpge.de |