Add or Upload Documents to Shipments

Documents and files may be added to a shipment via API or UI upload. Attaching or uploading documents (i.e. invoices, bills of lading, receipts, customs forms, etc.), to a shipment enables that document to be grouped with the shipment and makes the document available for additional functionality.

File uploads in the Shipwell API follow the same consistent upload pattern and utilize multipart/form-data since it is foundational to file uploads on the internet (i.e. it has wide support in every known web accessible programming language). If you have uploaded a file in through the Shipwell API, then uploading a document for a shipment will be similar with additional properties that are related to the file (i.e. the file description, type, etc.)

Upload document to shipment via API

Watch the following video with audio enabled to see how quick and easy it is to upload a document/file to a shipment using the Shipwell API.

To create (aka upload) a document for a shipment, a POST API request will need to be made to the Create a document on a shipment API endpoint with the shipment id/identifier for the already existing shipment and a file (or that file's bytes) that should be added to the shipment as a file or document.

Shipment documents also have properties like a description and a document type. You may optionally specify if the document is_carrier_document (boolean), For this example, we will use a document type of INVOICE. The exhaustive and up-to-date list of supported document types is available by making a GET request to the API endpoint that lists supported document types. Other reference data for a shipment, like document types, may be found here.

Below are examples of sending multipart/form-data data with a file upload using the file's bytes or data as part of the request. Remember to replace the variables like {shipmentId} with the shipment id.

curl 'https://sandbox-api.shipwell.com/v2/shipments/{shipmentId}/documents/' \
  --header 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  --header 'Content-Type: multipart/form-data; boundary=---abc12345678' \
  --data-raw $'---abc12345678\r\nContent-Disposition: form-data; name="description"\r\n\r\nTesting. 123.\r\n---abc12345678\r\nContent-Disposition: form-data; name="type"\r\n\r\nINVOICE\r\n---abc12345678\r\nContent-Disposition: form-data; name="file"; filename="example.pdf"\r\nContent-Type: application/pdf\r\n\r\n\(content of the uploaded file example.pdf as a string of bytes)\r\n---abc12345678--\r\n'

import requests

shipment_id = "YOUR_shipmentId_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/shipments/"
    + shipment_id
    + "/documents/"
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

payload = {
    "description": "Testing 123.",
    "type": "INVOICE",
    # Optional
    # "is_carrier_document": False
}
file_bytes = open("path/to/file/example.pdf", "rb")
files = [
    ("file", ("example.pdf", file_bytes, "application/pdf"))
]

response = requests.request("POST", target_url, headers=headers, data=payload, files=files)
print(response.json())

import java.io.IOException;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

byte [] fileData;
// byte [] fileData =  FileUtils.readFileToByteArray(file);

String shipmentId = "YOUR_shipmentId_PARAMETER";
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/shipments/" +
  shipmentId + 
  "/documents/";

RequestBody requestBody = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("description", "Testing 123.")
    .addFormDataPart("file", 
        "example.pdf",
        RequestBody.create(MediaType.parse("application/pdf"), fileData))
    .addFormDataPart("type", "INVOICE")
    .build();

Request request = new Request.Builder()
    .url(targetUrl)
    .post(requestBody)
    .header("Authorization", "YOUR_API_KEY_OR_AUTH_VALUE_HERE")
    .header("Content-Type", "multipart/form-data")
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
    response.body().string();
}

Interactive and Runnable Code

Below is an interactive and runnable Google Colab code notebook that allows you to run code and see the results. The python notebook demonstrates how to upload a file or the file bytes to an existing shipment using the patterns and principles in the file uploads API concepts.

• Shipwell Google Colab Notebook for Uploading a File to a Shipment
  • https://colab.research.google.com/drive/1IvzNbjOhba6FInFWcsVuWesCb8Aw1ykG?usp=sharing

Document Types

For convenience, here is a list of some of the supported document types that may be set as the document type property when uploading a shipment document. This is not an up-to-date or exhaustive list. The exhaustive and up-to-date list of supported document types is available by making a GET request to the API endpoint that lists supported document types. Other reference data endpoints for a shipment may be found here.

When uploading a shipment document and setting the type, the id value of the document type should be used, i.e. BOL and not Bill of Lading (BOL).