Order (Add Attachment)

Add Order Attachment

Overview

The Add Order Attachment endpoint uploads a file and attaches it to a sales order or purchase order in cieTrade. The file is sent as part of a multipart/form-data request, together with a small JSON payload that identifies the user, the order number, and whether the order is a sales order or a purchase order.

The document is saved using the original filename of the uploaded file as its name, and the file extension is recorded from that filename. On success the endpoint returns the document ID of the new attachment, which can be used with the Download Worksheet Attachment endpoint to retrieve the file.

Authentication

All calls to this endpoint require a valid bearer token passed in the HTTP Authorization header. The token is validated together with the UserID value in the request payload, and the combination determines which client database the attachment is saved to.

<code>Authorization: Bearer YOUR_TOKEN

Endpoint Details

Method	POST
URL	`https://api.cietrade.net/AddOrderAttachment`
Headers	`Authorization: Bearer YOUR_TOKEN`
Content-Type	`multipart/form-data`

Request Body

The request body must be sent as multipart/form-data and contain the following two parts. Part names are case-sensitive.

Part Name	Type	Required	Description
file	File	Yes	The file to attach. The filename sent with this part is saved as the document name and must include a file extension (for example `packing-list.pdf`). Only one file can be uploaded per request.
request	String (JSON)	Yes	A JSON object containing the fields listed below.

Request JSON Fields

Field	Type	Required	Description
UserID	String	Yes	The email address of the cieTrade user making the request. Validated together with the bearer token to authorize the call and select the client database. Must match a user in cieTrade, and is recorded as the user who created the document.
Order	String	Yes	The order number the attachment will be added to.
Source	String	Yes	The type of order. Must be one of the values below (not case-sensitive).

Source Values

Value	Description
`SO`	Sales Order
`PO`	Purchase Order

Example request part:

{
    "UserID": "user@example.com",
    "Order": "SO-10234",
    "Source": "SO"
}

Response

Success

On success the endpoint returns 200 OK. The response body is a JSON string containing the document ID (DocID) assigned to the new attachment.

Example success body:

"10046"

Errors

Error responses return a JSON body with a Message property describing the problem.

Status	Message	Cause
400 Bad Request	ERROR: Request must be multipart/form-data.	The request was not sent as `multipart/form-data`.
400 Bad Request	ERROR: No request payload provided.	The `request` part was missing or empty.
400 Bad Request	ERROR: No file provided.	The `file` part was missing or the file was empty.
401 Unauthorized	ERROR: Request must include a bearer authorization token	The `Authorization` header is missing or does not use the `Bearer` scheme.
400 Bad Request	ERROR: Request must include an Order.	The `Order` field was missing or empty.
400 Bad Request	ERROR: Request must include an Order Source.	The `Source` field was missing or empty.
400 Bad Request	ERROR: Source must be SO or PO.	The `Source` field contained a value other than `SO` or `PO`.
400 Bad Request	ERROR: …	The bearer token and `UserID` could not be authenticated. The message contains the reason returned by the authentication service.
400 Bad Request	ERROR: User Email {UserID} not found in cieTrade.	The `UserID` does not match a user in cieTrade.
400 Bad Request	ERROR: Sales Order: {Order} not found in cieTrade.	`Source` is `SO` and no sales order exists with the given `Order` number.
400 Bad Request	ERROR: Purchase Order: {Order} not found in cieTrade.	`Source` is `PO` and no purchase order exists with the given `Order` number.
400 Bad Request	ERROR: Could not save the attached document.	An unexpected error occurred while saving the document.
500 Internal Server Error	An error has occurred.	An unexpected server error occurred, such as a filename without an extension.

Example error body:

{
    "Message": "ERROR: Sales Order: SO-10234 not found in cieTrade."
}

Usage Examples

JavaScript (fetch with FormData)

Use a FormData object to build the multipart body. Do not set the Content-Type header manually — the browser sets it automatically, including the required multipart boundary.

var fileInput = document.getElementById('fileInput');

var formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('request', JSON.stringify({
    UserID: userEmail,
    Order: orderNo,
    Source: 'SO'   // or 'PO'
}));

fetch('https://api.cietrade.net/AddOrderAttachment', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer ' + token },
    body: formData
})
    .then(function(response) {
        return response.json().then(function(body) {
            if (!response.ok) {
                throw new Error(body.Message);
            }
            return body; // the new DocID, e.g. "10046"
        });
    })
    .then(function(docId) {
        alert('File saved. Document ID: ' + docId);
    })
    .catch(function(error) {
        alert('Upload failed: ' + error.message);
    });

Server-to-server example (cURL)

curl -X POST "https://api.cietrade.net/AddOrderAttachment" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -F "file=@/path/to/packing-list.pdf" \
     -F 'request={"UserID":"user@example.com","Order":"SO-10234","Source":"SO"}'