====== Uploaded Models Statistics Report API ======
===== What is the Reporting API? =====
The Reporting API allows you to retrieve information about the uploaded models that were tagged with your personal tool IDs. This is done through 2 separate APIs:
* The [[uploaded-models-reporting-api|Uploaded Models Reporting API]] which provides in depth information per model
* The Uploaded Models Statistics Report API which provides a summary per status of the models
===== Who Should Use this API? =====
The Order Status API is for users that want to retrieve information about their tagged models that have been uploaded to the i.materialise server.
If you are using the 3D print lab connection API and the Cart API, this API will provide you in a quick way with the information of how many models were uploaded and which of them converted into an order.
The Cart Ordering API users might find this API less interesting since they control the ordering flow of models from beginning till the end. The Reporting API will reflect what they already know and it can come in handy when analyzing statistics.
===== How Does it Work? =====
This API requires the personal API code. It is therefore not possible to use AJAX requests.
The Reporting API works by posting data to our service.
You can use either XML or JSON formats for posting. The HTTP encoding type of a particular request depends on the type of API you are going to use. This will be described in the corresponding documentation.
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 Reporting API can be tried out over our demo pages:
* **The Uploaded Models Reporting API demo page: **\\
https://i.materialise.com/api/demo/uploaded-models-reporting-api.htm
* **The Uploaded Models Statistics Report API demo page:** \\
https://i.materialise.com/api/demo/uploaded-models-statistics-report-api.htm
===== Documentation =====
The Uploaded Models Statistics Report API gives statistics information about uploaded models. It returns how many of the uploaded models were ordered, cancelled or just uploaded within the requested date range.
If the report doesn’t return the info per model, it returns a summary of the statuses. To get info on model level, you need to use the [[uploaded-models-reporting-api|Uploaded Models Reporting API]].
==== Structure of the request ====
Request should be done using HTTP POST request to:
https://<>/web-api/reporting/models/uploadedstatistics
=== Request example ===
The request will look like this //(parameters names are not case-sensitive)//:
=== 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 ===
This is the list of model parameters the requester has to pass in order to get an uploaded models statistics.
^ What ^ Type ^ Required? ^ Explanation ^
| DateFrom | String (10) required format: YYYY-MM-DD | Yes | Start date of date range for which to select results. This parameter indicates date of upload. |
| DateTo | String (10) required format: YYYY-MM-DD | Yes | Finish date of date range for which to select results. This parameter indicates the date of upload. |
| ToolId | String (36) required format: GUID | No | The Tool ID which is created for the partner. \\ If it’s not indicated, then the info for all tools registered for the partner will be shown. |
**Example of request in JSON**
{
"dateFrom": "2013-01-01",
"dateTo": "2014-12-01",
"toolId": "418674f3-f8a5-43bd-a06d-e8e95831b2d9"
}
**Example of request in XML**
2013-01-01
2014-12-01
418674f3-f8a5-43bd-a06d-e8e95831b2d9
==== Structure of the response ====
=== Response parameters ===
This is the list of model parameters returned into the response Filter/Error sections:
^ What ^ Type ^ Required? ^ Explanation ^
| DateFrom | String (24) format: YYYY-MM-DD | Yes | The same as in the request |
| DateTo | String (24) format: YYYY-MM-DD | Yes | The same as in the request |
| ToolId | String (36) format: GUID | No | The same as in the request. Shown only when indicated in the request. |
| TotalUploads | Integer | Yes (if no error appears in the response) | Total number of models uploaded during the indicated period. |
| UploadsOrdered | Integer | Yes (if no error appears in the response) | Calculated number of model instances which were added to at least one order with statuses: \\ - Paid\\ - Processing\\ - In Production\\ - Ready To Ship\\ - Shipped\\ - Delivered \\ \\ //Example:// One model was added in 3 orders in such way: \\ **Order1:** Quantity: 5 \\ **Order2:** Quantity: 6 \\ **Order3:** Quantity: 3 \\ Then value of ''UploadsOrdered =1'' |
| UploadsCancelled | Integer | Yes (if no error appears in the response) | Calculated number of model instances which were added to at least one order with status Cancelled. \\ \\ //Example:// \\ One model was added in 3 orders in such way: \\ - **Order1**: \\ Quantity: 5 \\ Status: Cancelled\\ - **Order2**: \\ Quantity: 6 \\ Status: different from Cancelled\\ - **Order3**: \\ Quantity: 3 \\ Status: Cancelled \\ Then value of ''UploadsCancelled=1'' |
| UploadedOnly | Integer | Yes (if no error appears in the response) | Number of models which were not added to any order. |
| Error | String () | No | This parameter appears if there’s an error in the request. |
=== Response example ===
If the request is processed successfully, the response looks like this:
**Response example in JSON**
{
"totalUploads":36,
"uploadsOrdered":1,
"uploadsCancelled":0,
"uploadedOnly":35,
"dateFrom":"2013-01-01",
"dateTo":"2014-12-01"
}
**Response example in XML**
2013-01-01
2014-12-01
418674f3-f8a5-43bd-a06d-e8e95831b2d9
36
1
0
35
==== 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 ^
| 201 | Tool ID is wrong/belongs to someone else | A wrong Tool ID has been applied. To verify your Tool ID, please contact developers[at]i.materialise.com |
| 202 | Incorrect format of DateFrom or DateFrom is empty | Please provide DateFrom in format YYYY-MM-DD |
| 203 | Incorrect format of DateTo or DateTo is empty | Please provide DateTo in format 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 |
| 206 | The number of models needs to be returned in the response more than 1000 | The result holds about models. Please limit the date range so the result holds a maximum of 1000 models. |
| 207 | ModelId is wrong or do not match ToolId | Model with ModelID= has not been found or was uploaded by using another Tool ID. |
| HTTP/1.1 500 Internal Server Error (sent in header) | Something else (exception, for example) | Unknown Error. Try again later. If the problem persists, please contact developers[at]i.materialise.com. |
**Example of Response with error in JSON**
{
"totalUploads":0,
"uploadsOrdered":0,
"uploadsCancelled":0,
"uploadedOnly":0,
"error":{
"message":"Please provide DateFrom in format YYYY-MM-DD",
"code":202
}
}
**Example of Response with error in XML**
DateFrom should be less or equal to DateTo
204
0
0
0
0