====== Cart Item Creation API ======
===== What is the Cart Item Creation API? =====
The Cart Item Creation API allows you to create cart items. Preparing a cart is a 2 step approach. First, cart items need to be created . Then these cart items need to be added to a cart . These 2 actions are done through 2 separate APIs: the Cart Item Creation API and [[cart-creation-api|Cart Creation API]]. The split up is done to allow maximum flexibility in the creation of a cart. However, one cannot be used without the other one.
{{ :cart_api.png?nolink |}}
===== Who Should Use this API? =====
The Cart Item Creation API is for users that have an application or website that generates 3D models. The 3D models can be uploaded or retrieved by our server. You either want to add a 3D print service to your application as an option, or you want to make models 3D printing the core of your business.
The Cart Item Creation API can be used for the following business flows:
* **White label approach:** Your application or website uses the Cart Item Creation API and [[cart-creation-api|Cart Creation API]] in combination with the [[cart-checkout-api|Cart Checkout API]] to place the order on your behalf at our back end system. The payment of your customer will then be handled by your application or website.
* **Controlled cart approach:** After the creation of a cart, your server reroutes the customer to i.materialise where the customer proceeds with the order. Our server will provide rerouting URLs to the i.materialise cart or the i.materialise shipping info page. There will also be links to embeddable pages.
===== Try it Out =====
Do you have questions about how your server should upload a 3D model and create cart item? Visiting our demo page will help you out.
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 code and integration with us. As the sandbox server is an isolated server, it requires different credentials than the production site.
**The demo page of Cart Item Creation API on sandbox server:**
https://imatsandbox.materialise.net/api/demo/cart-item-creation-api.htm
The sandbox and production server contain API demo pages which send well-formed API requests to our site.
**The demo page of Cart Item Creation API on production server:**
https://i.materialise.com/api/demo/cart-item-creation-api.htm
Try out your toolID on the demo page. Make sure you don’t mix up the toolIDs of the sandbox and the production site.
===== How Does it Work? =====
The Cart Item Creation 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 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 following encoding types:
• text/json\\
• application/json\\
• text/xml\\
• application/xml\\
To create cart item through the Cart Item Creation API, POST a well-structured request via “HTTPS” to this URL:
https://i.materialise.com/web-api/cartitems/register
To use APIs of the sandbox, the POST needs to be submitted to:
https://imatsandbox.materialise.net/web-api/cartitems/register
The server will return a structured response in XML or JSON which your application can parse.
All requests to the Cart Item Creation API should be made through a secure connection (e.g. SSL). Cart and cart items will stay valid for a period of 15 days.
===== Documentation =====
Cart items can be created one by one but it’s also possible to create several items at once.
A cart item section consists of following data:
• **Production data:** This data is obligatory. Your request need to specify the desired material, finishing, model file measure units, quantity and scale factor to be applied to the model in the file.
• **Model dimensional information:** This information is optional. Providing the dimensional information in the request will allow our service to verify them and warn you about any inconsistencies between the provided and i.materialise’s calculated model parameters. Since the information is used in the sales price calculation, it might be useful to be warned when the dimensional information sets differ too much. This info doesn’t need to be exact. Till further notice, the request needs to have at least the model information fields with dummy values like “1”.
• **Pricing:** The pricing data foresees to specify an estimated price and the price your customer should see. The estimated price can be retrieved from one of Pricing API's. Whenever the customer should see the regular sales price, the field ''mySalesPrice'' needs to be set to zero.
• **Auxiliary info:** Additionally, a cart item reference field is foreseen to tag your own reference to this cart item.
An example of a cart item section request can be found on the demo page for the Cart Item Creation API: https://i.materialise.com/api/demo/cart-item-creation-api.htm
==== Structure of the Request ====
=== HTTP Headers ===
Content-Type : multipart/form-data
=== Structure of the Request ===
^ Parameter ^ Type ^ Required? ^ Explanation ^
| ''currency'' | String (3) | Yes | Currency of cart items. {{page>Tips#currency&nofooter&noheader}} |
| ''cartItems'' | List of parameters | Yes | List of cart items to be created. |
| ''toolID'' | String (36) | Yes | The tool ID you got from developers@i.materialise.com |
| ''myCartItemReference'' | String (100) | Yes | Your reference by means of which you can identify a particular cart item in the API response. |
| ''modelID'' | String (36) | Yes (if ''modelFileName'' was not specified) | The ID of a previously uploaded model, retrieved from the response. \\ \\ Use this parameter to prevent uploading the same file again. All model parameters are retrieved from the previous uploaded model, speeding up the response. \\ \\ Use either ''modelID'' or upload a new file and specify ''modelFileName''. Specifying both ''modelID'' and a ''modelFileName'' will result in an error. |
| ''modelFileName'' | String | Yes (if ''modelID'' was not specified) | Model file name by means of which we can identify file in request body. |
| ''fileScaleFactor'' | Decimal, separated by a period | Yes | Scale factor needs to be applied to the model geometry. (1 = 100% scale) |
| ''fileUnits'' | String | No (“mm” is used by default if parameter is not specified”) | File units of the model file. The value should be “mm” or “inch”. If this parameter is not sent or its value is empty, “mm” is used. \\ \\ This parameter only indicates the unit system in which the physical model is saved in. They will not set the desired unit for the response parameters.\\ \\ The values in the request for the parameters ''xDimMm'', ''yDimMm'', ''zDimMm'', ''volumeCm3'', ''surfaceCm2'' should be sent in metric unit system as the names indicate. |
| ''materialID'' | String (36) | Yes | Material identifier from [[materials-catalog-api|Materials Catalog API]] |
| ''finishID'' | String (36) | Yes | Material identifier from [[materials-catalog-api|Materials Catalog API]] |
| ''quantity'' | Integer | Yes | How many physical items you want to order |
| ''xDimMm'' | Decimal, separated by a period | Yes | The expected X dimension of model in mm after the ''fileScaleFactor'' is applied on the model that’s present in the uploaded file. \\ \\ Set to 1 if unknown. |
| ''yDimMm'' | Decimal, separated by a period | Yes | The expected Y dimension of model in mm after the ''fileScaleFactor'' is applied on the model that’s present in the uploaded file. \\ \\ Set to 1 if unknown. |
| ''zDimMm'' | Decimal, separated by a period | Yes | The expected Z dimension of model in mm after the ''fileScaleFactor'' is applied on the model that’s present in the uploaded file. \\ \\ Set to 1 if unknown. |
| ''volumeCm3'' | Decimal, separated by a period | Yes | The expected volume of the model in cm³ after the ''fileScaleFactor'' is applied on the model that’s present in the uploaded file. \\ \\ Set to 1 if unknown |
| ''surfaceCm2'' | Decimal, separated by a period | Yes | The expected model surface area in cm² after the ''fileScaleFactor'' is applied on the model that’s present in the uploaded file. \\ \\ Set to 1 if unknown |
| ''iMatApiPrice'' | Decimal, separated by a period | Yes | The estimated total price that was returned by [[pricing-by-parameters-api|Pricing by Parameters]] or [[pricing-by-model-id-api|Pricing by Model ID]] API. Set to 0 (zero) if unknown. The total price is the price for the number of models indicated in the field ''quantity'', so it is not a unit price. |
| ''mySalesPrice'' | Decimal, separated by a period | Yes | The total sales price the customer should see on the i.materialise pages. \\ \\ Use 0 (zero) as value for ''mySalesPrice'' and ''iMatAPIPrice'' if: \\ * you don’t know your sales price yet \\ * you don’t need to show a different price than the calculated one in the response \\ * you will place the order using the [[cart-checkout-api|Cart Checkout API]] \\ \\ The total price is the price (excl. VAT/taxes/shipment) for the number of models indicated in the field ''quantity''. |
==== Request Examples ====
=== Example of Request Using JSON ===
{
"cartItems":[
{
"toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
"MyCartItemReference":"some reference",
"modelID":"",
"modelFileName":"Box.stl",
"fileUnits":"mm",
"fileScaleFactor":"1",
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"quantity":"1",
"xDimMm":"1",
"yDimMm":"1",
"zDimMm":"1",
"volumeCm3":"1",
"surfaceCm2":"1",
"iMatAPIPrice": "0",
"mySalesPrice": "0",
}
],
"currency":"EUR"
}
=== Example of Request Using XML ===
2054608d-b469-4cab-adeb-cf1c0569e7a1
some reference
06515f8e-5d08-4fcb-912a-b87380d69927
mm
1
035f4772-da8a-400b-8be4-2dd344b28ddb
bba2bebb-8895-4049-aeb0-ab651cee2597
1
10
10
10
1
6
0
0
EUR
The '''' block can be repeated more than once in the request. At this moment, 5 models per request are allowed.
==== Structure of the Response ====
=== General Parameters of the Response ===
^ Parameter ^ Type^ Always shown?^Explanation^
| ''currency''| String (3) | Yes | Currency provided in the request |
| ''error'' | List of parameters | No | Appears only in case of request error |
| ''cartItems'' | List of parameters | No | See detailed explanation of each parameter later in documentation |
=== Cart Items Section of the Response ===
The rule of thumb is when you get a ''cartItemID'' in response you are free to use it when you’re registering the cart.
^Parameter ^Type ^Always shown? ^Explanation^
|''myCartItemReference'' |String (100) |Yes |The cart item reference as provided in the request|
|''cartItemError'' |List of parameters |No |This parameter shown only in case cart item error appears|
|''cartItemError''>''Message''|String (100) |No |Error message. Explained in detailed later on in the documentation.|
|''cartItemError''>''Code''|Integer |No |Error code. Explained in detailed later on in the documentation.|
|''cartItemID'' |String (36) |No |The ID of the cart item. This ID is required for adding the item to the cart.|
|''toolID'' |String (36) |Yes |Product type as provided in the request|
|''modelID'' |String (36) |No |Model file ID. This ID can be used in future requests to eliminate upload and processing of the same file.|
|''modelFileName'' |String |No |File name of the model|
|''fileUnits'' |String |Yes |Mm or inch as provided in the request|
|''fileScaleFactor'' |Decimal, separated by a period |Yes |Model scale factor as provided in the request|
|''uploadStatus'' |String |Yes |Status of uploaded model. Possibilities are: \\ *** Succeeded** \\ *** NeededFixing:** Successful. There were some issues with model but the file was successfully fixed. \\ *** StillNeedsFixing:** Failed. The model has holes, inverted normals or other errors. \\ *** BackEndException:** Failed. There was a failure during the processing of the file.|
|''materialID'' |String (36) |Yes |Material ID as provided in the request|
|''materialName'' | String | Yes | Name of the material |
|''finishID'' |String (36) |Yes |Finishing ID as provided in the request|
|''finishName'' | String | Yes | Finish name |
|''quantity'' |Integer |Yes |Parts quantity as provided in the request|
|''xDimMm'' |Decimal, separated by a period |No |Calculated X dimension size in mm|
|''yDimMm'' |Decimal, separated by a period |No |Calculated Y dimension size in mm|
|''zDimMm'' |Decimal, separated by a period |No |Calculated Z dimension size in mm|
|''volumeCm3'' |Decimal, separated by a period |No |Calculated model volume in cm³|
|''surfaceCm2'' |Decimal, separated by a period |No |Calculated model surface area in cm²|
|''iMatApiPrice'' |Decimal, separated by a period |Yes |''iMatApiPrice'' as provided in the request|
|''mySalesPrice'' |Decimal, separated by a period |Yes |''mySalesPrice'' as provided in the request. If ''mySalesPrice'' and ''iMatAPIPrice'' were set to 0 in the request, then ''mySalesPrice'' and ''iMatAPIPrice'' would be set to ''iMatPrice''.|
|''mySalesUnitPrice'' |Decimal, separated by a period |Yes |Unit sales price, calculated as ''mySalesPrice''/''quantity''|
|''imatPrice'' |Decimal, separated by a period |No |Calculated total price for the requested cart item after processing the request. The ''totalPrice'' is for the requested ''quantity''. \\ \\ If ''xDimMm'', ''yDimMm'', ''zDimMm'', ''volumeCm3'', ''surfaceCm2'' parameters in request differ from real parameters of uploaded model, Cart Item Creation API calculates ''iMatPrice'' according to real parameters of model which you can find in response (taking into account ''fileScaleFactor''). |
|''validUntil'' |Date (CET) |Yes |Cart item validity end date. Currently 15 days.|
=== Response Examples ===
**Example of Response in XML**
EUR
some reference
333095fc-6ab2-4c30-b0d1-baecfd708f69
2054608d-b469-4cab-adeb-cf1c0569e7a1
06515f8e-5d08-4fcb-912a-b87380d69927
Box.stl
Mm
1
035f4772-da8a-400b-8be4-2dd344b28ddb
bba2bebb-8895-4049-aeb0-ab651cee2597
1
10.0000000000
10.0000000000
10.0000000000
1.0000000000
6.0000000000
15.00
15.00
15.00
15.00
2014-11-26T00:00:00+02:00
**Example of Response in JSON**
{
"currency":"EUR",
"cartItems":[
{
"myCartItemReference":"some reference",
"cartItemID":"ef7ee059-55cf-43b2-9413-3dd8e6dff49e",
"toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
"modelID":"eaba63a6-f9a0-4103-9d84-3c6e07ba282a",
"modelFileName":"Box.stl",
"fileUnits":"mm",
"fileScaleFactor":1.0,
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"quantity":10,
"xDimMm":10.0000000000,
"yDimMm":10.0000000000,
"zDimMm":10.0000000000,
"volumeCm3":1.0000000000,
"surfaceCm2":6.0000000000,
"iMatAPIPrice":69.00,
"mySalesPrice":69.00,
"mySalesUnitPrice":6.90,
"iMatPrice":69.00,
"validUntil":"2014-11-26T00:00:00+02:00"
}
]
}
=== Errors Section of the Response ===
^Code ^Message ^Error^
|1 |Unknown error | |
|101 |Wrong ToolID has been applied. To verify your ToolID, you should contact us at developers@i.materialise.com. |Tool ID has wrong format, doesn’t exist or doesn’t belong to you.|
|102 |ModelReference cannot be empty or more than 100 symbols. | |
|103 |This FileUnits value is not supported, please specify mm or inch. | |
|104 |FileScaleFactor is wrong. | |
|105 |An unknown ID for the Material has been requested; please check the ID’s in the materials Catalog API. |''MaterialID'' is of wrong format or the material with the provided ID doesn’t exist|
|106 |An unknown ID for the color/finish has been requested; please check the ID’s in the materials catalog API. |''FinishID'' is of wrong format or the finishing with the provided ID doesn’t exist|
|107 |Quantity is wrong, please use only positive integers. |Invalid value for ''quantity'' or ''quantity'' is not a positive value|
|108 |XDimMm is wrong, please use only positive decimal. |''XDimMm'' is of a wrong format or is not a positive value|
|109 |YDimMm is wrong, please use only positive decimal. |''YDimMm'' is of a wrong format or is not a positive value|
|110 |ZDimMm is wrong, please use only positive decimal. |''ZDimMm'' is of a wrong format or is not a positive value|
|111 |VolumeCm3 is wrong, please use only positive decimal. |''VolumeCm3'' is of a wrong format or is not a positive value|
|112 |SurfaceCm2 is wrong, please use only positive decimal. |''SurfaceCm2'' is of a wrong format or is not a positive value|
|113 |IMatPrice is wrong, please use only positive decimals. |''IMatAPIPrice'' is of a wrong format or is not a positive value|
|114 |SalesPrice is wrong, please use only positive decimal. |''MySalesPrice'' is of a wrong format or is a negative value|
|115 |Please, send ModelId of previously uploaded model or new ModelFileName. |Both ''ModelID'' and ''ModelFileName'' are empty.|
|116 |Please, send or ModelId of previously uploaded model or new ModelFile, but not both. |Both ''ModelID'' and ''ModelFileName'' are set.|
|117 |Model with ID «ModelID» is not found. |''ModelID'' is not a valid GUID or model with the provided ID was not found|
|118 |File «fileName» is not provided. |''ModelFileName'' was set but the corresponding model file was not posted|
|120 |Wrong combination of MaterialID and FinishingID |The finish specified in the request belongs to different material.|
|121|Specified toolID is no more active. |toolId was deactivated |
|122 |Specified ModelID was created with another ToolID. | Specified ''ModelID'' was created with another ''ToolID''. |
|123|Model file name is too long. It should not exceed 120 characters.| |
|124|The requested Material/Finish is no longer offered in the material catalog| |
|200 |We don’t offer an online price for this material/finish through the API. | |
|201 |The dimensions of the model are outside the allowed range to offer it as a priority model. The allowed range is «X»x«Y»x«Z» – «X»x«Y»x«Z» mm. | |
|202 |The dimensions of the model are outside the allowed range for «Material» «Finishing» model. The allowed range is «X»x«Y»x«Z» – «X»x«Y»x«Z» mm. | |
|203 |The dimensions of the model are outside the allowed range for «Material». The allowed range is «X»x«Y»x«Z» – «X»x«Y»x«Z»mm. | |
|204 |The price for this model is too high, so we are unable to offer an online price. Please request an offline price at our site. | |
|205 |The dimensions of the model are outside the allowed range for ceramics. The allowed sum of the X,Y and Z dimensions should be not greater than «size» mm. | |
|206 |The dimensions of the model are outside the allowed range for ceramics. The allowed sum of the X,Y and Z dimensions should be not below «size» mm. | |
|207 |The dimensions of the model are outside the allowed range for ceramics. The model should fit the range «X»x«Y»x«Z» mm. | |
|208 |The dimensions of the model are outside the allowed range for ceramics. Please make sure the wall thickness of your model is at least «thickness» mm. | |
|209 |SalesPrice cannot be less than IMatPrice. |''MySalesPrice'' is less than the provided ''IMatAPIPrice''|
|210 |Calculated IMatPrice for the current CartItem is «amount» «currency». It’s very different from the value you sent. Please verify your price with our pricing API. |The provided ''IMatAPIPrice'' is not equal to the recalculated price with allowed tolerance|
|211 |Calculated IMatPrice for the current CartItem is «amount» «currency». SalesPrice cannot be less than recalculated IMatPrice. Please verify your price with our pricing API. |''MySalesPrice'' is less than the recalculated price|
| 212 | Dimensions of the model are too small for Mammoth Resin. The allowed range is – mm. You can try another resin. | |
|302 |We don’t support «fileExtension» files. | |
|303 |We cannot process this model. Check if model is correct. | |
|304 |We do not process models over «size» Kb. | |
|3061 |Calculated XDimMm for the current CartItem is «size» mm. It’s very different from the value you sent. Please verify your model parameters. | |
|3062 |Calculated YDimMm for the current CartItem is «size» mm. It’s very different from the value you sent. Please verify your model parameters. | |
|3063 |Calculated ZDimMm for the current CartItem is «size» mm. It’s very different from the value you sent. Please verify your model parameters. | |
|307 |Calculated VolumeCm3 for the current CartItem is «volume» cm³. It’s very different from the value you sent. Please verify your model parameters. | |
|308 |Calculated SurfaceCm2 for the current CartItem is «area» cm². It’s very different from the value you sent. Please verify your model parameters. | |
|401 |Wrong request body. Check if all parameters set correctly | |
|402 |Currency is not supported, please specify EUR/USD/JPY/GBP. | |
|403 |You can’t create more than «N» CartItems in a single request. |Currently N=5|
|404 |At least one item in the request contains an error |This error is shown for all cart. Occurs when at least one item in the cart contains errors.|
**Example of Response with error in JSON**
{
"currency":"EUR",
"error":{
"message":"At least one of item in the request contains an error.",
"code":404
},
"cartItems":[
{
"myCartItemReference":"some reference",
"cartItemError":{
"message":"We cannot process this model. Check if model is correct.",
"code":303
},
"toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
"modelID":"3e64b3ed-e591-49d1-bac4-266571c7b2a7",
"modelFileName":"2print_bad.stl",
"fileUnits":"mm",
"fileScaleFactor":1.0,
"uploadStatus":"StillNeedsFixing",
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"quantity":1,
"xDimMm":73.7159000000,
"yDimMm":118.8810000000,
"zDimMm":27.3087000000,
"volumeCm3":85.2411000000,
"surfaceCm2":354.9360000000,
"iMatAPIPrice":0.0,
"mySalesPrice":0.0,
"mySalesUnitPrice":0.0
}
]
}
**Example of Response with error in XML**
EUR
At least one of item in the request contains an error.
404
some reference
SalesPrice cannot be less than IMatPrice.
209
2054608d-b469-4cab-adeb-cf1c0569e7a1
Mm
1
035f4772-da8a-400b-8be4-2dd344b28ddb
bba2bebb-8895-4049-aeb0-ab651cee2597
1
15
14
14