====== Cart Checkout API ====== ===== What is the Cart Checkout API? ===== The Cart Checkout API allows you to checkout carts and order them. The carts to check out have to be created through the [[cart-creation-api|Cart Creation API]]. {{ :cart_api.png?nolink |}} ===== Who Should Use this API? ===== The Cart Checkout API is meant for applications that place orders directly to **i.materialise** without redirecting the users of the application to the i.materialise.com site. ===== Try it Out ===== Do you have questions about how your server should checkout carts and order them? 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 Checkout API on sandbox server:** https://imatsandbox.materialise.net/api/demo/cart-checkout-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 Checkout API on production server:** https://i.materialise.com/api/demo/cart-checkout-api.htm Try out your API code on the demo page. Make sure you don’t mix up API codes of the sandbox and the production site. ===== How Does it Work? ===== This API requires the personal API code. It is therefore not possible to use AJAX requests. The Cart Checkout 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\\ The API code needs to be specified in the APICode HTTP header. To checkout and order cart through the Cart Checkout API, POST a well-structured request via “HTTPS” to this URL: https://i.materialise.com/web-api/order/post To use APIs of the sandbox, the POST needs to be submitted to: https://imatsandbox.materialise.net/web-api/order/post The server will return a structured response in XML or JSON which your application can parse. You should create HTTP multipart request to be able to send Delivery Note and Invoice files. HTTP multipart request is a type of HTTP request that HTTP clients construct to send file and data over to the server side. ===== Documentation ===== The Cart Checkout API requires that minimally following info is inserted to check out the cart: - The cart ID that was obtained through the [[cart-creation-api|Cart Creation API]]. The shipment and billing info needs to be filled in in the Cart. \\ - The shipment service you prefer. ==== Structure of the Request ==== **Request header** ^ What ^ Type ^ Required ^ Explanation ^ | ''ApiCode'' | String (36) required format: Guid | Y | ApiCode received from i.materialise. This parameter should be sent in header of request. | | ''Accept'' | String | N (“text/xml” is used by default) | Preferred Content Type: multipart/form-data. This parameter should be sent in header of request. | **Request body** ^What ^Type ^Required ^Explanation^ |''MyInvoiceFile''|File|N |File of invoice. \\ \\ The invoice will be inserted into the shipment box. \\ \\ If no invoice is available at the time of shipment, an autogenerated invoice by i.materialise will be added in case this is required for custom declarations. \\ \\ It is not allowed to specifiy an ''MyInvoiceLink'' and ''MyInvoiceFile'' in the same request. | |''MyDeliveryNoteFile''|File|N |File of Delivery Note. \\ \\ The delivery note will be inserted into the shipment box. \\ \\ If no delivery note is available at the time of shipment, an autogenerated DN will be inserted \\ \\ It is not allowed to specify a ''MyDeliveryNoteLink'' and ''MyDeliveryNoteFile'' in the same request. | **Request example** Accept:text/xml ... APICode:A1F1BAE8-3F1B-4B8D-8D95-D19E17595034 .. Content-Type:multipart/form-data; boundary=----WebKitFormBoundarywjsY9C5toeYrThmi ... ------WebKitFormBoundarywjsY9C5toeYrThmi Content-Disposition: form-data; name="data"; filename="blob" Content-Type: text/xml ------WebKitFormBoundarywjsY9C5toeYrThmi Content-Disposition: form-data; name="MyInvoiceFile"; filename="INVOICE_TEST.pdf" Content-Type: application/octet-stream ------WebKitFormBoundarywjsY9C5toeYrThmi Content-Disposition: form-data; name="MyDeliveryNoteFile"; filename="DN_TEST.pdf" Content-Type: application/octet-stream **General parameters** ^ What ^ Type ^ Required ^ Explanation ^ | ''CartId'' | GUID | Y | ''CartId'' that was created through the [[cart-creation-api|Cart Creation API]] . The ''CartID'' needs to be linked to the same ApiCode as applied in the header | | ''MyOrderReference'' | String (100) | Y | Your Order Reference. A reference that is generated by you to identify the order that will be placed, like e.g. a purchase order number. This field will be echoed in the response. | | ''DirectMailingAllowed'' | Boolean (true/false) | N | If the flag is set to true, then i.materialise can send automated production information mails to the available email addresses in billing and shipping info. \\ \\ If set to false then only emails are send to the ‘account’ email, which is the email address that is linked to the API Code. \\ \\ With production information mails is meant: \\ -Order confirmation mail \\ -In production mail \\ -Cancellation mail \\ -Shipment mail \\ -Delivery mail \\ \\ In production and Shipment emails are never sent to billing email. \\ \\ The default value will be “false” in case that the flag is not set. | | ''ShipmentService'' | String (100) | Y | Name of service returned in [[cart-creation-api|Cart Creation API]] (ShipmentCost>Services>Service>Name). | | ''MyInvoiceLink'' | String (255) | N | Link to the Invoice that is generated by your application. Invoice should be able for downloading by this link. The invoice will be inserted into the shipment box. \\ \\ NOTE: it should be a direct link to file so that it could be downloaded. \\ (e.g. Dropbox provides link in format __dropbox.com/[...].pdf?dl=0__ but it is not direct. \\ The direct should be in format __dropbox.com/[...].pdf?dl=1__ ) \\ \\ If no invoice is available at the time of shipment, an autogenerated invoice will be inserted. \\ \\ It is not allowed to specify a ''MyInvoiceLink'' and ''MyInvoiceFile'' in the same request. | | ''MyDeliveryNoteLink'' | String (255) | N | Link to the Delivery Note that is generated by your application. Delivery Note should be able for downloading by this link.The delivery note will be inserted into the shipment box. \\ \\ NOTE: it should be a direct link to file so that it could be downloaded. \\ (e.g. Dropbox provides link in format __dropbox.com/[...].pdf?dl=0__ but it is not direct. \\ The direct should be in format __dropbox.com/[...].pdf?dl=1__ ) \\ \\ If no delivery note is available at the time of shipment, an autogenerated DN will be inserted. \\ \\ It is not allowed to specify a ''MyDeliveryNoteLink'' and ''MyDeliveryNoteFile'' in the same request. | | ''Remarks'' | String (250) | N | You can put remarks to your order there. The remarks are intended as additional info to the order. \\ \\ The remarks are should not be in conflict with earlier given info or agreements. | | ''LanguageCode'' | String (3) | N | Language of the site pages: {{page>Tips#language&nofooter&noheader}} Default is EN. | === Request examples === **Example of request in JSON** { "cartID":"847b8092-8662-4c78-bcc5-5b7099fecb9d", "myOrderReference":"test", "directMailingAllowed":"false", "shipmentService":"SecondDayAir", "myInvoiceLink":"http://mysite.com/invoice.pdf", "myDeliveryNoteLink":"http://mysite.com/deliverynote.pdf", "remarks":"qwerty", "languageCode":"de" } **Example of request in XML** 847b8092-8662-4c78-bcc5-5b7099fecb9d OrderReferenceTest false Ground Test fr ==== Structure of the Response ==== **General Information** ^ What ^ Type ^ Always shown? ^ Explanation ^ | ''RequestError'' | List | N | Show if it is impossible to create order | | RequestError>''Code'' | Integer | N | Code of error | | RequestError>''Message'' | String (255) | N | Message of error | | ''Warning'' | List | N | Warning message and code. See details in "Warnings" section. | | Warning>''Code'' | Integer | N | Code of warning | | Warning>''Message'' | String (255) | N | Warning message | | ''OrderNumber'' | String (10) | Y | IMC number of the order. The order number will not be provided in case of an error. | | ''OrderID'' | Guid | Y | | | ''RequestNumber'' | String (10) | Y | Request number (REQXXXXXX). The same as returned in [[cart-creation-api|Cart Creation API]]. This is something like purchase order number. | | ''DirectMailingAllowed'' | Boolean (true/false) | Y | Echoed from the request. If this flag is not set then use “false” as value. | | ''CartId'' | GUID | Y | Echoed from the request. | | ''MyOrderReference'' | String (100) | Y | Echoed from the request. | | ''Currency'' | String (3) | Y | Echoed currency from the cart. | | ''Remarks'' | String (250) | N | The same as in request. | | ''MyInvoiceLink'' | String (255) | N | Echoed from the request. | | ''MyDeliveryNoteLink'' | String (255) | N | Echoed from the request. | | ''IMatConfirmationUrl'' | String (255) | Y | Link to the order confirmation page on general website (with header and footer). | | ''IMatConfirmationUrlIframe'' | String (255) | Y | Link to the order confirmation page that can be inserted in iframe | | ''HasInvoiceFile'' | Boolean | Y | Will be set to false in case file is not provided or attempt to send an invoice file was not successful. | | ''HasDeliveryNoteFile'' | Boolean | Y | Will be set to false in case file is not provided or attempt to send a delivery note file was not successful. | | ''SubtotalPrice'' | Decimal, 2 digits after “.” | Y | Sum of the all order items prices. | | ''ShipmentCost'' | Decimal, 2 digits after “.” | Y | Calculated Shipment cost | | ''Discount'' | Decimal, 2 digits after “.” | Y | Discount amount. Should 0 if promocode is not used | | ''VatTax'' | Decimal, 2 digits after “.” | Y | VAT / Tax value. Return 0 if Vat is not taken | | ''TotalPrice'' | Decimal, 2 digits after “.” | Y | Total order price. | **OrderItem information** (''OrderItems''>''OrderItem'' section) This section is shown for all items added to the cart. ^What ^Type ^Always shown? ^Explanation^ |''CartItemId'' |String (36) required format: Guid |Y |Id of related CartItem.| |''CartItemReference'' |String (100) |Y |Reference provided during CartItem registration request.| |''ToolId'' |String (36) required format: Guid |Y |ToolId of related CartItem.| |''ModelId'' |String (36) required format: Guid |Y |Id of model. | |''OrderItemName'' |String (100) |Y |Name of order item in order. By default it is equal to ModelFileName.| |''PreviewPictureUrl'' |String (255) |Y |Link to the preview picture| |''MaterialId'' |String (36) required format: Guid |Y |The material id as retrieved from the material catalog| |''MaterialName'' |String (100) |Y |Name of material.| |''FinishID'' |String (36) required format: Guid |Y |The finish id as retrieved from the material catalog| |''FinishName'' |String (100) |Y |Name of finish| |''XDimMm'' |Decimal (mm) |Y |Calculated after processing request X dimension of model.| |''YDimMm'' |Decimal (mm) |Y |Calculated after processing request Y dimension of model.| |''ZDimMm'' |Decimal (mm) |Y |Calculated after processing request Z dimension of model.| |''VolumeCm3'' |Decimal (cm3) |Y |Calculated after processing request Volume of the model.| |''SurfaceCm2'' |Decimal (cm2) |Y |Calculated after processing request Total surface of the model.| |''Quantity'' |Int |Y |The same as in related CartItem.| |''OrderItemPrice'' |Decimal, 2 digits after “.” |Y |Price Tool owner going to sell this CartItem (for number of models indicated in''Quantity''). Equal to MySalesPrice in related Cart Item Creation API.| |''OrderItemUnitPrice'' |Decimal, 2 digits after “.” |Y |Unit sales price, calculate as ''OrderItemPrice''/''Quantity''| **Shipment Information** (ShipmentInfo section) ^What ^Type ^Always shown? ^Explanation^ |''FirstName'' |String(100) |Y |As provided during the cart creation| |''LastName'' |String(100) |Y |As provided during the cart creation| |''Email'' |String(255) |Y |As provided during the cart creation| |''Phone'' |String(100) |Y |As provided during the cart creation| |''Company'' |String(100) |N |As provided during the cart creation| |''Line1'' |String(100) |Y |As provided during the cart creation| |''Line2'' |String(100) |N |As provided during the cart creation| |''CountryCode'' |String(2) |Y |As provided during the cart creation| |''StateCode'' |String(2) |N |As provided during the cart creation| |''ZipCode'' |String(100) |Y |As provided during the cart creation| |''City'' |String(100) |Y |As provided during the cart creation| This section is not added to the response if ''RequestError'' appers. **Billing Information** (BillingInfo section) ^What ^Type ^Always shown? ^Explanation^ |''FirstName'' |String(100) |Y |As provided during the cart creation| |''LastName'' |String(100) |Y |As provided during the cart creation| |''Email'' |String(255) |Y |As provided during the cart creation| |''Phone'' |String(100) |Y |As provided during the cart creation| |''Company'' |String(100) |N |As provided during the cart creation| |''VatNumber'' |String(100) |N |As provided during the cart creation| |''Line1'' |String(100) |Y |As provided during the cart creation| |''Line2'' |String(100) |N |As provided during the cart creation| |''CountryCode'' |String(2) |Y |As provided during the cart creation| |''StateCode'' |String(2) |N |As provided during the cart creation| |''ZipCode'' |String(100) |Y |As provided during the cart creation| |''City'' |String(100) |Y |As provided during the cart creation| This section is not added to the response if ''RequestError'' appers. === Response Examples === **Example of Response in JSON** { "orderNumber":"IMC975574", "orderID":"e1754c8d-2ed1-43ba-a9b3-3e22314600c1", "requestNumber":"REQ696922", "directMailingAllowed":false, "cartID":"847b8092-8662-4c78-bcc5-5b7099fecb9d", "myOrderReference":"test", "currency":"EUR", "remarks":"qwerty", "myInvoiceLink":"http://mysite.com/invoice.pdf", "myDeliveryNoteLink":"http://mysite.com/deliverynote.pdf", "iMatConfirmationUrl":"https://i.materialise.com/de/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1", "iMatConfirmationUrlIframe":"https://i.materialise.com/embeded/general/de/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1", "hasInvoiceFile":true, "hasDeliveryNoteFile":true, "subTotalPrice":26.0000, "shipmentCost":12.88, "discount":10.0000, "vatTax":0.00, "totalPrice":28.88, "warning":{ "message":"If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences for what is on the document and what is actually shipped", "code":200 }, "orderItems":[ { "cartItemID":"01ebe0b0-caf4-4f1e-9ad5-abd28f141944", "cartItemReference":"some reference", "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1", "modelID":"489eb85e-4c64-457c-a1fe-83187b8e52d8", "orderItemName":"Box.stl", "previewPictureUrl":"https://i.materialise.com/Storage/Models/2014/11/489eb85e-4c64-457c-a1fe-83187b8e52d8/Original/preview_small.jpg", "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb", "materialName":"Polyamide", "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597", "finishName":"Natural white", "xDimMm":10.00000000000000000000, "yDimMm":10.00000000000000000000, "zDimMm":10.00000000000000000000, "volumeCm3":1.0000000000, "surfaceCm2":6.0000000000, "quantity":2, "orderItemPrice":26.0000, "orderItemUnitPrice":13.0000 } ], "shippingInfo":{ "firstName":"John", "lastName":"Smith", "email":"test@test.com", "phone":"1234567", "company":"No company", "line1":"North Street", "line2":"", "countryCode":"US", "stateCode":"", "zipCode":"10001", "city":"New York" }, "billingInfo":{ "firstName":"John", "lastName":"Smith", "email":"test@test.com", "phone":"1234567", "company":"No company", "vatNumber":"BE0999999922", "line1":"North Street", "line2":"", "countryCode":"BE", "stateCode":"", "zipCode":"1020", "city":"Brussels" } } **Example of Response in XML** IMC975575 d6399ee3-7465-4ada-9726-eeba1861aaf2 REQ696922 false 847b8092-8662-4c78-bcc5-5b7099fecb9d OrderReferenceTest EUR Test https://i.materialise.com/fr/ordering/order-confirmation/d6399ee3-7465-4ada-9726-eeba1861aaf2 https://i.materialise.com/embeded/general/fr/ordering/order-confirmation/d6399ee3-7465-4ada-9726-eeba1861aaf2 true true 26.0000 8.78 10.0000 0.00 24.78 If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences for what is on the document and what is actually shipped 200 01ebe0b0-caf4-4f1e-9ad5-abd28f141944 some reference 2054608d-b469-4cab-adeb-cf1c0569e7a1 489eb85e-4c64-457c-a1fe-83187b8e52d8 Box.stl https://i.materialise.com/Storage/Models/2014/11/489eb85e-4c64-457c-a1fe-83187b8e52d8/Original/preview_small.jpg 035f4772-da8a-400b-8be4-2dd344b28ddb Polyamide bba2bebb-8895-4049-aeb0-ab651cee2597 Natural white 10.00000000000000000000 10.00000000000000000000 10.00000000000000000000 1.0000000000 6.0000000000 2 26.0000 13.0000 John Smith test@test.com 1234567 No company North Street US 10001 New York John Smith test@test.com 1234567 No company BE0999999922 North Street BE 1020 Brussels === Errors Section of the Response === The parameter ''RequestError'' will be added if request was NOT processed successfully. If the request was NOT processed successfully, the ''OrderItems'', ''ShippingInfo'', ''BillingInfo'' and ''ShipmentCost'' sections will be empty. **API Code verification** If a wrong/empty API Code is used, then Error 401 is returned with response statusText=”Unauthorized”. **General errors** Those errors are added to the request only if it is impossible to register order. Value of this parameter is set according to the table below. ^ Code ^ Message ^ Description ^ | HTTP/1.1 500 Internal Server Error (sent in header) | Unknown Error. Try again later. If the problem persists, please contact us. | Something went wrong (exception for example) | | 101 | Wrong request body. Check if all parameters are set correctly . | The structure of request is wrong (some needed parameters are not found or filled in incorrectly) | | 103 | DirectMailingAllowed should be set to “true” or “false” | ''DirectMailingAllowed'' flag is not “true” or “false” | | 105 | Order reference cannot be empty or more than 100 symbols. | Order reference is empty or more than 100 symbols. | | 107 | Please, use either the MyInvoiceLink or an InvoiceFile, but not both within the same request | Both ''MyInvoiceLink'' and ''InvoiceFile'' are not empty | | 108 | File “MyInvoiceFile” is not provided. | File with the name indicated in ''MyInvoiceFile'' is not sent (only if ''MyInvoiceFile'' is not empty) | | 109 | It is allowed to send only .doc, .docx, .pdf, .xls, .xlsx files as Invoice file. | ''InvoiceFile'' extension is not .doc, .docx, .pdf, .xls, .xlsx | | 110 | File “MyInvoiceFileName” should be not more than 5MB. | Size of file ''InvoiceFile'' is more than 5MB (5MB should be taken from config) | | 111 | Please, use either the MyDeliveryNoteLink or a DeliveryNoteFile, but not both within the same request. | Both ''MyDeliveryNoteLink'' and'' DeliveryNoteFile'' are not empty | | 112 | File “MyDeliveryNoteFile” is not provided. | File with the name indicated in ''MyDeliveryNoteFile'' is not sent (only if ''MyDeliveryNoteFile'' is not empty) | | 113 | It is allowed to send only .doc, .docx, .pdf, .xls, .xlsx files as Delivery note file. | ''DeliveryNoteFile'' extention is not .doc, .docx, .pdf, .xls, .xlsx | | 114 | File “MyDeliveryNoteFileName” should be not more than 10MB. | Size of file ''DeliveryNoteFile'' is more than 10MB (10MB should be taken from config) | | 115 | Our server can’t reach the delivery note document using the provided link | ''MyDeliveryNoteLink'' is not reachable | | 116 | Our server can’t reach the Invoice document using the provided link | ''MyInvoiceLink'' is not reachable | | 117 | Please, specify CartId. | ''CartId'' is empty | | 118 | Wrong CartId has been applied. | ''CartId'' is not found or belong to another partner | | 119 | Cart validity period expired on XX.XX.XXXX | Cart is no more valid (validity period expired) | | 120 | Validity period of some CartItems are expired. | One or more CartItems in specified Cart are no more valid | | 121 | Validity period of some model files are expired. Please use Cart Item Creation/Cart Creation API to upload them one more time. | One or more models in order are marked as deleted | | 122 | Please, specify ShipmentService in request | ''ShipmentService'' is not set or empty | | 123 | Wrong ShipmentService has been applied. | ''ShipmentService'' is not available for the applied addres in the Cart | | 124 | Shipping info is incomplete in related cart. Please create new cart. | ShippingInfo section is not filled correctly in Cart | | 125 | Billing info is incomplete in related cart. Please create new cart. | BillingInfo section is not filled correctly in Cart | | 126 | Invoice filename cannot be empty. | Invoce filename not specified when ''InvoiceFile'' is set. | | 127 | Delivery note filename cannot be empty. | DeliveryNote filename not specified when ''DeliveryNoteFile'' is set. | | 128 | Invoice filename contains invalid characters. | Invoce filename contains invalid characters | | 129 | Delivery note filename contains invalid characters. | DeliveryNote filename contains invalid characters | | 130 | The format of the MyInvoiceLink could not be determined. | ''MyInvoiceLink'' is not a valid url | | 131 | The format of the MyDeliveryNoteLink could not be determined. | ''MyDeliveryNoteLink'' is not a valid url | | 132 | Maximum number of symbols for Remarks parameter of 250 symbols is exceeded. | ''Remarks'' string length is too large. | | 133 | CartItem from the Cart and provided APICode belong to different Partners. | ''CartItem'' from the Cart and provided ''APICode'' belong to different Partners. | **Warnings** Parameter “Warning” is added according to the table below. ^Code ^Message ^Warning^ |135 |This language code is not supported. Please indicate one of the following: {{page>Tips#language&nofooter&noheader}} | | |200 |If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences for what is on the document and what is actually shipped |Shown only when one of following request parameters is not empty: \\ \\ - MyInvoiceLink \\ - MyDeliveryNoteLink \\ - MyInvoiceFile \\ - MyDeliveryNoteFile | **Example of Response with error in JSON** { "orderID":"00000000-0000-0000-0000-000000000000", "directMailingAllowed":false, "cartID":"00000000-0000-0000-0000-000000000000", "hasInvoiceFile":false, "hasDeliveryNoteFile":false, "subTotalPrice":0.0, "shipmentCost":0.0, "discount":0.0, "vatTax":0.0, "totalPrice":0.0, "requestError":{ "message":"Wrong ShipmentService has been applied.", "code":123 }, "warning":{ "message":"If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences for what is on the document and what is actually shipped", "code":200 }, "orderItems":[ ], "shippingInfo":{ }, "billingInfo":{ } } **Example of Response with error in XML** 00000000-0000-0000-0000-000000000000 false 00000000-0000-0000-0000-000000000000 false false 0 0 0 0 0 Please, use either a MyDeliveryNoteLink or a DeliveryNoteFile, but not both. 111 If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences for what is on the document and what is actually shipped 200