Uploaded Models Reporting 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:

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:

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:

https://i.materialise.com/api/demo/uploaded-models-reporting-api.htm

https://i.materialise.com/api/demo/uploaded-models-statistics-report-api.htm

Documentation

The Uploaded Models Reporting API gives detailed information per uploaded model for a specified date range. The Uploaded Models Reporting API gives detailed information per uploaded model for a specified date range. The models need to be tagged with a personal tool ID in order to show up in the report. Since models can be reused several times for different cart items, a model can have a status ‘cancelled’ and at the same time a status ‘ordered’, dependent of the status of the linked cart items. The Reporting API also allows seeing whether the uploaded model file was deleted from our server or not.

Structure of the request

Request should be done using HTTP POST request to:

https://<<server-name>>/web-api/reporting/models/uploaded

Request examples

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

Example of request in JSON

 {
   "dateFrom": "2013-01-01",
   "dateTo": "2014-12-01",
   "toolId": "418674f3-f8a5-43bd-a06d-e8e95831b2d9",
   "modelId":"79507760-3ed6-4003-bbd0-4a2062124d8f"
}

Example of request in XML

 <UploadedModelsRequest>
  <DateFrom>2013-01-01</DateFrom>
  <DateTo>2014-12-01</DateTo>
  <ToolId>418674f3-f8a5-43bd-a06d-e8e95831b2d9</ToolId>
  <ModelId>0ab3f316-5df4-4a77-a01d-46210943ac56</ModelId>
</UploadedModelsRequest>

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: 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 was used to upload the model.
If it’s not indicated, then the info for all tools registered for the partner will be shown.
modelId String (36) required format: GUID No ID of the model which allows you to check the information about a particular model.

Structure of the response

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
modelId String (36) format: GUID No The same as in the request
error String(255) No This parameter appears if there’s an error in the request

This is the list of model parameters returned into the response Models section:

What Type Required? Explanation
modelId String (36) required format: GUID Yes Unique ID of the uploaded model
toolId String (36) required format: GUID Yes Tool ID by using which model was uploaded
uploadDate String (10) format: YYYY-MM-DDThh:mm:ss.mmm Yes Date when the model was uploaded (use uploadEndTime).
modelFileName String () Yes Name of the model (file name) with model extension
wasDeleted Boolean Yes If the file with the model is deleted “true” will be shown, if not – “false”.
wasOrdered Boolean Yes Value of this parameter is set to “true” if the model was added at least to one order with the status:
- Paid
- Processing
- In Production
- Ready To Ship
- Shipped
- Delivered
Otherwise the value of this parameter is set to “false”.
wasCanceled Boolean Yes The value of this parameter is set to “true” if the model was added at least to one canceled order.
Otherwise the value of this parameter is set to “false”.
xDimMm Decimal, separated by a period Yes X dimensions in mm.
yDimMm Decimal, separated by a period Yes Y dimensions in mm
zDimMm Decimal, separated by a period Yes Z dimensions in mm
volumeCm3 Decimal, separated by a period Yes Volume of the model in cm³
surfaceCm2 Decimal, separated by a period Yes Total surface of the model in cm²
processingResult String () No One of the options:
- Succeeded
- NeededFixing
- StillNeedsFixing
- backEndException
reference String (512) No Reference sent by the API owner through the Upload Model API

Response example

Response example in JSON

{
    "modelId":"79507760-3ed6-4003-bbd0-4a2062124d8f",
    "models":[
        {
            "modelId":"79507760-3ed6-4003-bbd0-4a2062124d8f",
            "toolId":"418674f3-f8a5-43bd-a06d-e8e95831b2d9",
            "uploadDate":"2014-11-05T02:43:18.057",
            "modelFileName":"Box.stl",
            "wasDeleted":false,
            "wasOrdered":true,
            "wasCanceled":false,
            "xDimMm":10.0000000000,
            "yDimMm":10.0000000000,
            "zDimMm":10.0000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "processingResult":"Succeeded"
        }
    ],
    "dateFrom":"2013-01-01",
    "dateTo":"2014-12-01",
    "toolId":"418674f3-f8a5-43bd-a06d-e8e95831b2d9"
}

Response example in XML

<UploadedModelsResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DateFrom>2013-01-01</DateFrom>
  <DateTo>2014-12-01</DateTo>
  <ToolId>418674f3-f8a5-43bd-a06d-e8e95831b2d9</ToolId>
  <ModelId>0ab3f316-5df4-4a77-a01d-46210943ac56</ModelId>
  <Models>
    <UploadedModelDto>
      <ModelId>0ab3f316-5df4-4a77-a01d-46210943ac56</ModelId>
      <ToolId>418674f3-f8a5-43bd-a06d-e8e95831b2d9</ToolId>
      <UploadDate>2014-11-07T04:06:42.467</UploadDate>
      <ModelFileName>2print_bad.stl</ModelFileName>
      <WasDeleted>false</WasDeleted>
      <WasOrdered>false</WasOrdered>
      <WasCanceled>false</WasCanceled>
      <XDimMm>73.7159000000</XDimMm>
      <YDimMm>118.8810000000</YDimMm>
      <ZDimMm>27.3087000000</ZDimMm>
      <VolumeCm3>85.2411000000</VolumeCm3>
      <SurfaceCm2>354.9360000000</SurfaceCm2>
      <ProcessingResult>StillNeedsFixing</ProcessingResult>
    </UploadedModelDto>
  </Models>
</UploadedModelsResponse>

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 <number of models> 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=<ModelID> has not been found or was uploaded by using another ToolId.
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

{
    "error":{
        "message":"Model with ModelId=79507760-3ed6-4003-bbd0-4a2062124d8f9 has not been found or was uploaded by using another ToolId.",
        "code":207
    }
} 
 

Example of Response with error in XML

<UploadedModelsResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Error>
    <Message>Wrong request body. Check if all parameters set correctly</Message>
    <Code>205</Code>
  </Error>
</UploadedModelsResponse>