Delivery Note Add/Update API

What is the Delivery Note Add/Update API?

The Delivery Note Add/Update API allows you to add or update delivery notes for your orders.

Who Should Use this API?

This API is intended to be used in white label business model approach where you want to be in control of the delivery note that is inserted in the transport box.

Try it Out

Do you have questions about how your server should add or update delivery notes for your orders? 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 Delivery Note Add/Update API on sandbox server:

https://imatsandbox.materialise.net/api/demo/documents-add-update-api.htm

The sandbox and production server contain API demo pages which send well-formed API requests to our site.

The demo page of Delivery Note Add/Update API on production server:

https://i.materialise.com/api/demo/documents-add-update-api.htm

How Does it Work?

This API requires the personal API code. It is therefore not possible to use AJAX requests.

The Delivery Note Add/Update 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 add/update Delivery Note for an order through the Delivery Note Add/Update API, POST a well-structured request via “HTTPS” to this URL:

https://i.materialise.com/web-api/order/[Order ID]/delivery-note

To use APIs of the sandbox, the POST needs to be submitted to:

https://imatsandbox.materialise.net/web-api/order/[Order ID]/delivery-note

The API code needs to be specified in the APICode HTTP header.

The Delivery Note add/update should be done using POST HTTP Method:

Request Method:POST

You should create HTTP multipart request to be able add/update Delivery Note file. HTTP multipart request is a type of HTTP request that HTTP clients construct to send file and data over to the server side.

Documentation

Structure of the Request

You can either upload the delivery note file in your request or indicate an freely accessible url where the delivery note can be found. The delivery note should be either a .doc, .docx, .pdf, .xls or .xlsx format.

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
`FileUrl`	URL	Y (if `File` is not defined)	The URL where the i.materialise server can download the delivery note from 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 `File` and `FileUrl` in the same request.
`File`	File	Y (if `FileUrl` is not defined)	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 `File` and `FileUrl` in the same request.

Request example

Request Method:POST
...
Accept:application/json
...
APICode:A1F1BAE8-3F1B-4B8D-8D95-D19E17595034
...
Content-Type:multipart/form-data; boundary=----WebKitFormBoundaryMsjJ3JrEorerhu6H
...
------WebKitFormBoundaryMsjJ3JrEorerhu6H
Content-Disposition: form-data; name="FileUrl"


------WebKitFormBoundaryMsjJ3JrEorerhu6H
Content-Disposition: form-data; name="File"; filename="DN_TEST.pdf"
Content-Type: application/octet-stream
...

Structure of the Response

In case of success, Status Code:200 is shown in the response, otherwise Error is shown.

Errors Section of the Response

In case of error in the request or when delivery note cannot be added/updated, one of following error appears in the response.

Code	Message	Description
100	Order ID is wrong	Wrong Order ID was determined in request
101	wrong API code	The order was created by using different API code.
102	No document	No delivery note file is provided by you for this order or it is not available
103	Order is already shipped or cancelled	Delivery Note Add/Update API cannot be used for shipped and cancelled orders
104	Incorrect document link format	The specified url was not recognized as a link
105	Document cannot be downloaded or timeout	The server could not download a file using the specified `fileUrl`
106	Document file format is not supported. File should be of one of formats .doc, .docx, .pdf, .xls, .xlsx	DeliveryNoteFile extention is not .doc, .docx, .pdf, .xls, .xlsx
107	No document in request	No delivery note file specified
108	Delivery note file cannot be empty	File cannot be empty.
109	Delivery note file should be not more than 10MB.	Exceeded maximum size of delivery note document 10MB.
110	Please, use either FileUrl or File, but not both within the same request.	It is not allowed to specify a `File` and `FileUrl` in the same request.

Example of Response with error in JSON

{
    "error":{
        "message":"Order is already shipped or cancelled",
        "code":103
    }
}

Example of Response with error in XML

<DeliveryNoteResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Error>
    <Message>Document cannot be downloaded or timeout</Message>
    <Code>105</Code>
  </Error>
</DeliveryNoteResponse>

Site Tools