====== Order Statistics API ======

===== What is the Order Statistics API? =====
The Order Statistics API allows you to retrieve the details of all the orders placed through our platform. The response returns a list of all the orders for a given time period.

===== Who Should Use this API? =====
The Order Statistics API is for for referral partners to follow up the orders of customers they have been forwarding to i.materialise.

===== How Does it Work? =====
This API requires the personal API code. It is therefore not possible to use AJAX requests.

The Order Statistics API works by retrieving data from our service.
To specify the exact content type which your client can accept and parse, the Accept header in your request has to be set to one of the following encoding types:
  * text/json
  * application/json
  * text/xml
  * application/xml
The API code needs to be specified in the API code HTTP header.

===== Try it Out =====
The Order Statistics API can be tried out over our demo page:
  
https://i.materialise.com/api/demo/order-statistics-api.htm

===== Documentation =====
The Order Statistics API gives a detailed information about all orders for a specified date range that were placed with different toolIDs linked to one API code.

==== Structure of the request ====

Request should be done using HTTP GET request to:
<code>https://<<server-name>>/web-api/orders</code>

=== Request header ===
^ What ^ Type ^ Required? ^ Explanation ^
| Header>\\ ApiCode | String (36) required format: GUID | Yes | API code received from i.materialise. This parameter should be sent in the **header** of the request. |
| Header>\\ Accept | String | No (“text/xml” is used by default) | Preferred Content Type: “application/json” or “text/xml”. This parameter should be sent in the **header** of the request. |

=== Request parameters ===
^ What ^ Type ^ Required? ^ Explanation ^
| dateFrom | String (10) required format: DD-MM-YYYY | No | Start date of date range for which to select results. This parameter indicates date of upload. |
| dateTo | String (10) required format: DD-MM-YYYY | No | Finish date of date range for which to select results. This parameter indicates the date of upload. |
| status | String | No | Order status code. Should be one of: Cancelled, Invalid, Ordered, InProduction, ReadyToShip, ReadyToPickUp, Shipped, Delivered. \\ If it’s not indicated, then the info about orders in all statuses will be shown. |
| currency | String (3) | No | Currency of prices in response: EUR or USD. \\ If it’s not indicated, USD is a default one. |
| skip | Integer | No | Indicates number of entities to be skipped while fetching data from API. \\ If it’s not indicated, 0 is a default value. |
| take | Integer | No | Indicates number of entities to be taken from API \\ If it’s not indicated, 50 is a default value. Maximum is 200. |

=== Request example ===
The request will look like this //(parameters names are not case-sensitive)//:

<code>
https://<<server-name>>/web-api/orders?dateFrom=01-10-2016&dateTo=31-10-2016&status=InProduction&currency=EUR&skip=10&take=20
</code>

==== Structure of the Response ====

=== General Section of the Response ===
^Parameter	^Type	^Always shown?	^Description^
|''dateFrom''	|Date	|Yes	|The same as in the request|
|''dateTo''	|Date	|Yes	|The same as in the request or the current date if it wasn't specified|
|''currency''	|String (3)	|Yes	|The same as in the request or the default one|
|''total''	|Integer	|Yes	|Total number of Orders that match the request|
|''orders''	|List of parameters	|Yes	|Information about the Orders that match the request|

=== Orders Section of the Response ===
^Parameter	^Type	^Always shown?	^Description^
|''orderID''	|String (36) format: GUID	|Yes	|Order ID|
|''orderDate''	|Date	|Yes	|The same as in the request|
|''status''	|String	|Yes	|Order status code: Cancelled, Invalid, Ordered, InProduction, ReadyToShip, ReadyToPickUp, Shipped or Delivered|
|''cartItems''	|List of parameters	|Yes	|Information about items of this Order|

=== Cart Items Section of the Response ===
^Parameter	^Type	^Always shown?	^Description^
|''cartItemID''	|String (36) format: GUID	|Yes	|Cart Item ID|
|''modelID''	|String (36) format: GUID	|Yes	|Model ID of corresponding Cart Item|
|''scale''	|Decimal	|Yes	|Scale of ordered item|
|''materialID''	|String (36) format: GUID	|Yes	|Material ID|
|''finishID''	|String (36) format: GUID	|Yes	|Finish ID|
|''quantity''	|Integer	|Yes	|Number of ordered items|
|''unitPrice''	|Decimal(2)	|Yes	|Unit Price|
|''totalPrice''	|Decimal(2)	|Yes	|Total Price = Unit Price * Quantity|
|''isOrderItemCancelled''	|Boolean	|Yes	|Indication if an Item was cancelled by Support Engineer|

=== Response example ===

If the request is processed successfully, the response looks like this:

**Response example in JSON**
<code>
{
    "dateFrom":"29-09-2016",
    "dateTo":"31-10-2016",
    "currency":"EUR",
    "total":2,
    "orders":[
        {
            "orderID":"ebdf4bd6-5ccb-42c6-8bca-24794f1d3cc6",
            "orderDate":"25-10-2016",
            "status":"InProduction",
            "cartItems":[
                {
                    "cartItemID":"9c72be41-a7a2-47b3-9e5a-e8a040817967",
                    "modelID":"9796b4b6-3623-492a-9f43-464b3981cd5a",
                    "scale":1,
                    "materialID":"12a65a42-df49-47a9-8828-0efaf84c5509",
                    "finishID":"c9c27ce3-eee4-47e4-a896-a9010a7971fd",
                    "quantity":1,
		    "unitPrice":57.56,
                    "totalPrice":57.56,
                    "isOrderItemCancelled":false
                }
            ]
        },
        {
            "orderID":"fcf3ecba-6f53-4c03-9cd9-16c6fd20302a",
            "orderDate":"30-09-2016",
            "status":"InProduction",
            "cartItems":[
                {
                    "cartItemID":"944f12d8-8c01-4ff7-aa15-c3851a9b127a",
                    "modelID":"ca285452-cb4f-42ac-a49a-264e025a2d7c",
                    "scale":1,
                    "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
                    "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
                    "quantity":1,
		    "unitPrice":12.75,
                    "totalPrice":12.75,
                    "isOrderItemCancelled":false
                }
            ]
        }
    ]
}
</code>

**Response example in XML**
<code>
<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DateFrom>29-09-2016</DateFrom>
  <DateTo>31-10-2016</DateTo>
  <Currency>EUR</Currency>
  <Total>2</Total>
  <Orders>
    <Order>
      <OrderID>ebdf4bd6-5ccb-42c6-8bca-24794f1d3cc6</OrderID>
      <OrderDate>25-10-2016</OrderDate>
      <Status>InProduction</Status>
      <OrderItems>
        <CartItem>
          <CartItemID>9c72be41-a7a2-47b3-9e5a-e8a040817967</CartItemID>
          <ModelID>9796b4b6-3623-492a-9f43-464b3981cd5a</ModelID>
          <Scale>1.0000000000</Scale>
          <MaterialID>12a65a42-df49-47a9-8828-0efaf84c5509</MaterialID>
          <FinishID>c9c27ce3-eee4-47e4-a896-a9010a7971fd</FinishID>
          <Quantity>1</Quantity>
	  <UnitPrice>57.5600</UnitPrice>
          <TotalPrice>57.5600</TotalPrice>
          <IsOrderItemCancelled>false</IsOrderItemCancelled>
        </CartItem>
      </OrderItems>
    </Order>
    <Order>
      <OrderID>fcf3ecba-6f53-4c03-9cd9-16c6fd20302a</OrderID>
      <OrderDate>30-09-2016</OrderDate>
      <Status>InProduction</Status>
      <OrderItems>
        <CartItem>
          <CartItemID>944f12d8-8c01-4ff7-aa15-c3851a9b127a</CartItemID>
          <ModelID>ca285452-cb4f-42ac-a49a-264e025a2d7c</ModelID>
          <Scale>1.0000000000</Scale>
          <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
          <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
          <Quantity>1</Quantity>
          <UnitPrice>12.7500</UnitPrice>
	  <TotalPrice>12.7500</TotalPrice>
          <IsOrderItemCancelled>false</IsOrderItemCancelled>
        </CartItem>
      </OrderItems>
    </Order>
  </Orders>
</Response>

</code>

==== Errors ====

=== API code verification ===
If a wrong/empty API code is used, then a 401 error is returned with the response statusText=”Unauthorized”.

=== General errors ===
The parameter “Error” is added to the request only if the request wasn’t processed successfully. The value of this parameter is set according to the table below. If the request wasn’t processed successfully, the list of models will be empty.

^ Code ^ Description ^ Message ^
| 1 | API code not recognized | API code not recognized |
| 202 | Incorrect format of DateFrom or DateFrom is empty | Please provide DateFrom in format DD-MM-YYYY or YYYY-MM-DD |
| 203 | Incorrect format of DateTo or DateTo is empty | Please provide DateTo in format DD-MM-YYYY or YYYY-MM-DD |
| 204 | Wrong date range | DateFrom should be less or equal to DateTo |
| 205 | The structure of the request is wrong (some needed parameters are not found or filled in incorrectly) | Wrong request body. Check if all parameters set correctly |
| 250 | Wrong/empty Currency | Wrong Currency. Acceptable values are “EUR”, “USD”. |
| 252 | Wrong status code | An unknown Status has been requested; please make sure you request only following status: Cancelled, Invalid, Ordered, Processing, InProduction, ReadyToShip, Shipped, Delivered. |
| 253 | Skip parameter is too large | Skip request parameter is bigger than Total , please choose more suitable value. Total is response parameter. |
| 254 | Take parameter is larger than maximum take value | Value of take request parameter is bigger than maximum Take value. Please choose more suitable value. |
| 255 | Take parameters is less than 0 | Value of take request parameter is less than 0, please choose more suitable value. |

**Example of Response with error in JSON**
<code>
{
    "error":{
        "message":"This Currency is not supported,
         please specify EUR/USD.",
        "code":250
    }
}
</code>

**Example of Response with error in XML**
<code>
<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Error>
    <Message>DateFrom should be less or equal to DateTo</Message>
    <Code>204</Code>
  </Error>
  <Total xsi:nil="true" />
</Response>
</code>