====== Pricing by Model ID API ======
===== What are the Pricing APIs? =====
The Pricing APIs let you request prices and shipping cost calculation for 3D printing models without uploading them to our website. There are two APIs related to Pricing available on our site:
* [[pricing-by-parameters-api|Pricing by Parameters]]*. Using this API, you can receive prices for the various material and finish combinations based on the dimensions, volume and surface of the model. \\
* Pricing by Model ID. You can get price of previously uploaded models by using this API. All you need to know is ID of the model you want to calculate the price for. This API is described on current page
*Note that by using this API it is impossible to calculate prices for some materials: paintable resin, transparent resign, high delail resin and ABS.
===== Who Should Use this API? =====
The Pricing API is designed for users who have an application or website that generates models that need to be 3D printed and who wants an instant price before ordering models. If you would like prices to be calculated for your 3D models without transferring your information to i.materialise for performance, security or other reasons, this is the API for you.
===== Try it Out =====
We have created demo pages for you so you can test the tool ID and your acquired API code.
**The demo page of Pricing by Model ID API on production server**:
https://i.materialise.com/api/demo/pricing-by-model-id-api.htm
These fully functioning pages are linked to the pricing engine that is used in our 3D print lab, meaning that the API generated prices are identical to the prices generated by i.materialise’s 3D print lab.
Also, we’ve developed a sandbox server, which is an isolated server (not hooked up to a payment system or production environment, allowing you to test the service without getting billed) to try out your sandbox API code, tool ID and integration with us. This is different from our demo pages which are used to check if a particular API is working and is connected with our production site.
**The demo page of Pricing by Model ID API on sandbox server**:
https://imatsandbox.materialise.net/api/demo/pricing-by-model-id-api.htm
===== How Does it Work? =====
This API requires the personal API code. It is therefore not possible to use AJAX requests.
The Pricing API works by posting data to our service. You can use either XML (Extensible Markup Language) or JSON (JavaScript Object Notation) 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 “Documentation” section of this page.
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 supported encoding types:
* text/json
* application/json
* text/xml
* application/xml
The API code needs to be specified in the API code HTTP header.
To get prices through the Pricing API, POST a well-structured request via “HTTPS” to this URL:
https://i.materialise.com/web-api/pricing/model
To use APIs of the sandbox, the POST needs to be submitted to:
https://imatsandbox.materialise.net/web-api/pricing/model
The server will return a structured response in XML or JSON which your application can parse to retrieve pricing information.
===== Documentation =====
==== Structure of the Request ====
The request, in XML or JSON format, needs to follow a certain structure to be able to generate prices.
The structure consists of the following sections:
=== Request Header===
The header of your request needs to contain:\\
Accept: [preferred Content Type: "application/json" or "text/xml"]
API code: [API code provided by i.materialise]
=== Models Section of the Request ===
Within the same request, it’s possible to request prices for multiple quantities and multiple material and finish options.
^ Parameter ^ Type ^ Required? ^ Explanation ^
| ''modelId'' | String (36), required format: GUID | Yes | The ID of previously uploaded model. |
| ''materialId'' | String (36), required format: GUID | Yes | The ''materialId'' is retrieved from the Materials Catalog API. Read more about the [[Materials Catalog API]]. |
| ''finishId'' | String (36), required format: GUID | Yes | The ''finishId'' is retrieved from the Materials Catalog API. Read more about the [[materials-catalog-api|Materials Catalog API]]. |
| ''quantity'' | Integer | Yes | Amount of pieces for this model. |
| ''scale'' | Decimal, separated by a period | No | The scale factor of the model. If parameter is not specified, ''scaleFactor'' = 1 is used by default. This parameter allows you to get a price of previously uploaded model with different scale. |
=== Shipment Information Section of the Request ===
The section is not required. If you would like the shipping cost calculated into the quote, simply add this to the request.
^ Parameter ^ Type ^ Required? ^ Explanation ^
| ''countryCode'' | String (2) | Yes | Code of the country. |
| ''stateCode'' | String | Yes | Code of the state. {{page>Tips#statecodes&nofooter&noheader}} |
| ''city'' | String | Yes | City name. |
| ''zipCode'' | String | Yes | Zip code or postal code. |
=== Currency Section of the Request ===
The header of your request needs to contain:
^ Parameter ^ Type ^ Required? ^ Explanation ^
| ''currency'' | String (3) | No (EUR is default) | {{page>Tips#currency&nofooter&noheader}} |
==== Request Examples ====
=== Example of Request Using XML ===
28ba016b-68a6-4511-a518-2cd4dafd43b7
2e7b80e9-634b-485a-bc40-5e4324078b54
0261af53-8fed-4854-a248-4b111d759f8d
1
1.0
BE
Leuven
3001
EUR
=== Example of Request Using JSON ===
{
"models":[
{
"modelID":"28ba016b-68a6-4511-a518-2cd4dafd43b7",
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"quantity":"1",
"scale":"1.0"
}
],
"shipmentInfo":
{
"countryCode": "BE",
"stateCode": "",
"city": "Leuven",
"zipCode": "3001"
},
"currency":"EUR"
}
==== Structure of the Response ====
=== Models Section of the Response ===
This section contains a list of models with the following parameters:
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''modelID'' | String (100) | Yes | The same as in the request. |
| ''toolId'' | String (36), required format: GUID | No | The ''toolID'' you received from us. If it’s omitted, the standard 3D print lab pricing algorithms will be used (your specific price factor will not be applied). |
| ''materialId'' | String (36), required format: GUID | Yes | The ''materialId'' is retrieved from the Materials Catalog API. Read more about the [[Materials Catalog API]]. |
| ''materialName'' | String | Yes | Name of the material. |
| ''finishId'' | String (36), required format: GUID | Yes | The ''finishId'' is retrieved from the Materials Catalog API. Read more about the [[materials-catalog-api|Materials Catalog API]]. |
| ''finishingName'' | String | Yes | Name of the finishing. |
| ''quantity'' | Integer | Yes | Amount of pieces for this model. |
| ''totalPrice'' | Decimal, separated by a period | Yes | Price calculated for the indicated quantity of models. If the price cannot be calculated, the value is empty. |
| ''xDimMm'' | Decimal, separated by a period | Yes | X dimension of the model, mm. |
| ''yDimMm'' | Decimal, separated by a period | Yes | Y dimension of the model, mm. |
| ''zDimMm'' | Decimal, separated by a period | Yes | Z dimension of the model, mm. |
| ''volumeCm3'' | Decimal, separated by a period | Yes | Volume of the model, cm3. |
| ''surfaceCm2'' | Decimal, separated by a period | Yes | Total surface of the model, cm2. |
| ''pricingError'' | List of parameters | No | The section is shown only in case of pricing error. Possible pricing errors are described below. |
| ''pricingError''>''code'' | Integer | No | This parameter appears in the response if the price for a model cannot be calculated. See “Errors” section for more information. |
| ''pricingError''>''message'' | String (250) | No | This parameter appears in the response if the price for a model cannot be calculated. |
=== Disclaimer Section of the Response ===
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''disclaimer'' | String (250) | Yes | Informational section |
=== Shipment Information Section of Response ===
You’ll only see a shipping cost response if your request contains a shipment Information section.\\
Whenever there is a model for which the price could not be calculated, then the Shipment Information Section will show a shipping error.
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''services'' | List of parameters | Yes | List of shipment services |
| ''services''>''service'' | List of parameters | No | The response contains the services price, which is the basis of the shipping costs. Section is not shown if shipping address was not specified in the response. |
| ''services''>''service''>''name'' | String (100) | Yes (if parent node Service is added) | Name of the service |
| ''services''>''service''>''value'' | Decimal, separated by a period | Yes (if parent node Service is added) | The shipment cost for current service. The shipment cost is calculated for all models indicated in the request. |
| ''services''>''service''>''daysInTransit'' | Integer | No | Number of days it would take to deliver all models with current service. If number of days is not returned by UPS, this field is empty. |
| ''shipmentError'' | String (225) | No | This parameter is inserted into the response if it’s impossible to calculate the shipment cost. Possible shipment errors are described below. |
=== Currency Section of the Response ===
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''currency'' | String (3) | No (EUR is default) | {{page>Tips#currency&nofooter&noheader}} |
All prices in the response (model prices and shipment cost) are calculated and returned in currency shown in this section.
=== RequestError Section of Response ===
This response section appears only if request was NOT processed successfully.
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''requestError'' | String (250) | No | This parameter is added to the response only if the request was NOT processed successfully. Possible errors are described below. |
==== Response Examples ====
=== Example of Response in XML ===
28ba016b-68a6-4511-a518-2cd4dafd43b7
20ef6277-52f5-a1s2-a306-1282ab8bc035
2e7b80e9-634b-485a-bc40-5e4324078b54
Prime gray
0261af53-8fed-4854-a248-4b111d759f8d
Natural gray
1
5.00
1.00000000000
1.00000000000
1.00000000000
0.0010000000
0.0600000000
Standard
6.68
3
Express
8.92
1
EUR
=== Example of Response in JSON ===
{
"models":[
{
"modelID":"28ba016b-68a6-4511-a518-2cd4dafd43b7",
"toolID":"20ef6277-123b-4551-a306-1282ab8bc035",
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"materialName":"Polyamide",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"finishingName":"Natural white",
"quantity":1,
"totalPrice":12.50,
"xDimMm":1.00000000000,
"yDimMm":1.00000000000,
"zDimMm":1.00000000000,
"volumeCm3":0.0010000000,
"surfaceCm2":0.0600000000
}
],
"shipmentCost":{
"services":[
{
"name":"Standard",
"value":6.68,
"daysInTransit":3
},
{
"name":"Express",
"value":8.92,
"daysInTransit":1
}
]
},
"currency":"EUR"
}
===== Errors =====
Below described all possible errors which can appear in both Pricing APIs ([[pricing-by-parameters-api|Pricing by Parameters]] and Pricing by Model ID).
==== Wrong API Code ====
If a wrong/empty API code is used, then you’ll see a 401 error response: statusText=”Unauthorized”.
==== Messaging for RequestError Response ====
The ''RequestError'' response shows up only if the request was NOT processed successfully.
^ Code ^ Error ^ Message ^
| 206 | Wrong currency | {{page>Tips#currency&nofooter&noheader}} |
| 101 | The structure of the request is wrong (some needed parameters are not found or filled in incorrectly) | Wrong request body. Check if all parameters are set correctly. |
| - | Something else (exception for example) | Unknown Error. Try again later. If the problem persists, please contact developers@i.materialise.com. |
=== Example of Response in XML ===
This currency is not supported, please specify EUR/USD/JPY/GBP
This currency is not supported, please specify EUR/USD/JPY/GBP
206
=== Example of Response in JSON ===
{
"requestError":"This currency is not supported,
please specify EUR/USD/JPY/GBP",
"error":{
"message":"This currency is not supported,
please specify EUR/USD/JPY/GBP",
"code":206
}
}
==== Messaging for models>pricingError Response ====
The ''models''>''pricingError'' message appears if the price for a model cannot be calculated. Each model can have its own pricing error. Pricing errors appear when some parameters are filled in incorrectly, or when it’s impossible to calculate online prices according to i.materialise rules.
=== Pricing Errors Related with Wrong Request Inputs ===
^ Code ^ Error ^ Message ^
| 201 | ''toolId'' is wrong/belongs to someone else | Wrong toolID has been applied. To verify toolID, please contact developers@i.materialise.com.|
| 202 | ''modelReference'' is empty or contains more than 100 symbols | modelReference cannot be empty or more than 100 symbols. |
| 203 | ''materialID'' is empty or wrong | An unknown material ID for has been requested, please check the IDs in the [[materials-catalog-api|Materials Catalog API]]. |
| 204 | ''finishID'' is empty or wrong | An unknown ID for the color/finish has been requested, please check the IDs in the [[materials-catalog-api|Materials Catalog API]]. |
| 205 | ''quantity'' is not a positive integer | Quantity is wrong, please use only positive integer. |
| 207 | ''xDimMm'' is not a positive decimal | XDimMm is wrong, please use only positive decimals. |
| 208 | ''yDimMm'' is not a positive decimal | YDimMm is wrong, please use only positive decimals. |
| 209 | ''zDimM'' is not a positive decimal | ZDimMm is wrong, please use only positive decimals. |
| 210 | ''volumeCm3'' is not a positive decimal | VolumeCm3 is wrong, please use only positive decimals. |
| 211 | ''surfaceCm2'' is not a positive decimal | SurfaceCm2 is wrong, please use only positive decimals. |
| 212 | ''scaleFactor'' is not positive float | Wrong scaleFactor. Please make sure you set this parameter correctly. |
| 213 | ''modelID'' is wrong/empty or model was uploaded by another user/partner. | Wrong modelID. Please make sure you set this parameter. | correctly.
| 214 | ''Model'' is deleted from database. | Your model has been deleted from database. Please upload model to get a price. |
|215|''toolId'' was deactivated |Specified toolID is no more active. |
=== Pricing Errors Related to Price Calculation ===
^ Code ^ Error ^ Message ^
| 220 | No online price for this material through the API | We don’t offer an online price for this material/finish through the API. |
| 221 | Dimensions are too large for the priority service | The dimensions of the model are outside the allowed range to offer it as a priority model. The allowed range is – mm. |
| 222 | Dimensions are too large, too small for a specific finish (e.g. velvet) | The dimensions of the model are outside the allowed range for model. The allowed range is – mm. |
| 223 | Dimensions too large or too small | The dimensions of the model are outside the allowed range for . The allowed range is – mm. |
| 224 | Price is too high | The price for this model is too high, so we are unable to offer an online price. Please request an offline price through our website. |
| 225 | If the requested material is “Ceramics” and X+Y+Z is larger than 400 mm | The dimensions of the model are outside the allowed range for ceramics. The sum of the X,Y and Z dimensions should be below 400 mm. |
| 226 | If the requested material is “Ceramics” and X+Y+Z is below 120 mm | The dimensions of the model are outside the allowed range for ceramics. The sum of the X,Y and Z dimensions should be greater than 120 mm. |
| 227 | Dimensions for Ceramics are too large or too small | The dimensions of the model are outside the allowed range for ceramics. The model should fit the range of . |
| 228 | If requested material is “Ceramics” and wall thickness is too small | The dimensions of the model are outside the allowed range for ceramics. Please make sure the wall thickness of your model is at least mm. |
| 229 | If parameter IfSuccessfulyProcessed is “false” (model fixing is still needed after autofixing) | Unfortunately price cannot be calculated for this model through the API. Model needs to be fixed first. |
| 231 | |Dimensions of the model are too small for Mammoth Resin. The allowed range is – mm. You can try another resin.|
| 0 | Something else | Unknown Error. Try again later. If the error keeps occurring, please contact developers@i.materialise.com. |
=== Example of PricingError in XML ===
d7ed51be-aaa1-40ea-8ca7-8763c65fc66e
496ce425-aaa1-4320-b78a-2dfa7c41657b
1
0
10
10
10
1
6
We don’t offer an online price for this material
220
some model.xml
=== Example of pricingError in JSON ===
"models":[
{
"modelReference":"some model.xml",
"toolID":"20ef6277-52f5-4551-a306-1282ab8bc035",
"materialID":"d7ed51be-aaa1-40ea-8ca7-8763c65fc66e",
"finishID":"496ce425-aaa1-4320-b78a-2dfa7c41657b",
"quantity":1,
"totalPrice":0.0,
"xDimMm":10.0,
"yDimMm":10.0,
"zDimMm":10.0,
"volumeCm3":1.0,
"surfaceCm2":6.0,
"pricingError":{
"message":"We don’t offer an online price for this material",
"code":220
}
}
],
==== Messaging for ShipmentCost > ShipmentError parameter ====
^ Error ^ Message ^
| The price is not calculated for at least one model from the list of requested models | We cannot calculate the shipment cost because the price for some models you requested cannot be calculated. |
| The country code is not indicated or left blank | countryCode is required. Please use an international country code (e.g. BE for Belgium). |
| The country code is not found in our database | Wrong countryCode. Please use an international country code (e.g. BE for Belgium). |
| The state code is required for the indicated country | stateCode is required for the requested country. Please use an American/Canadian state code (e.g. MI for Michigan). |
| The state code is not found in our database for the requested country | Wrong stateCode is is required for the requested country. Please use an American/Canadian state code (e.g.: MI for Michigan). |
| City is not indicated or left blank | City is required |
| Zip code is not indicated or left blank | Zip code is required |
| Shipment can't be done to the specified country | Shipping service is not provided for this country. Please specify different shipping country. |
| UPS returns an error message. It can occur when there’s a wrong combination of zip code, city and country, or when the model’s weight is over the UPS limit, or some other UPS errors. | UPS error message |
| Something else (exception for example) | Unknown error. Please try again later. |
=== Example of ShipmentError in XML ===
ZipCode is required.
=== Example of ShipmentError in JSON ===
"shipmentCost":{
"shipmentError":"Wrong CountryCode. Please use international country code (e.g.: BE for Belgium)."
},