Transsmart has one active API version: APIv2. This article explains how to integrate with it.

Transsmart also has 3 publicly available environments. These can be found here.

The examples in the documentation below will always reference the user acceptance environment.

Sections in this article:

1. Authentication
   - 1.1 Token retrieval
   - 1.2 Token usage
   - 1.3 Token lifetime
2. Booking a shipment
   - 2.1 Request content
   - 2.2 Request example
3. Printing the label
   - 3.1 Trigger the print action
   - 3.2 SmartPrint

1. Authentication

The APIv2 uses token-based authentication. This means that before any request can be sent a new token needs to be retrieved and used for sending the subsequent requests.

1.1 Token retrieval

Before a token can be retrieved you need a valid username and password. Speak with your Transsmart contact if you have not yet received any. Connect to https://accept-api.transsmart.com/login with basic authentication. The response will be a JSON formatted text containing a single name/value pair.

{"token": "eyJhbGciOiJIUzUxM...FHPrZw"}

1.2 Token usage

Every other request that you send to the APIv2 will need to contain a specific HTTP header field: Authorization. The value of this field needs to be the token value, prefixed with Bearer.

1.3 Token lifetime

Tokens have a limited lifetime of 24 hours.
For applications integrating with our platform this is irrelevant, because typically tokens are retrieved at the beginning of an application process (e.g. book and print a shipment), used for the subsequent calls (e.g. book shipment, check status, issue label print) and dropped after the process has completed.

2 Booking a shipment

By booking a shipment your system sends all relevant information to our APIv2, the Transsmart platform then does its magic and a number of things happen, all depending on the actual configuration of your account. Below are some examples of actual use cases:

1. Information is forwarded to the carrier, the carrier responds with label information, and label information is returned to your system as part of the response.
    
2. Information is stored in Transsmart and only forwarded to the carrier in a Manifest at a fixed point during the day, but the response will nevertheless contain a label to be printed.
    
3. Information is stored in Transsmart and used to make a label. All relevant information the carrier needs is filtered out and put in a barcode which generates a label. The printing of the barcode will transfer the information to the carrier.
    
4. Information is stored in Transsmart and no information is sent to a carrier and only a label is generated. This is used for postlabels or own transport

2.1 Request content

A booking consists of several information blocks. Most of the information in those blocks comes from your application, the other parts typically are Transsmart codes for carriers, service levels, etc.

There is one exception field: the shipment reference. The content of this field needs to be unique throughout all the shipments you make. In most cases, this will be an autonumber value from your application. Besides the basic shipment information (addresses, pickup date and time, package information, etc) several optional fields must contain values depending on the selected carrier/service level/service option.

In the next sections, we will highlight the most important parts of the shipment information. At the end, a complete example request is included.

2.1.1 Shipment details

This is the first part of the request.

"reference": "TESTv2",
"carrier": "EEX",
"value": 25,
"valueCurrency": "EUR", 
"pickupDate": "2024-03-14", 
"service": "NON-DOCS", 
"serviceLevelTime": "EUROPLUS", 
"serviceLevelOther": "", 
"incoterms": "CPT", 
"numberOfPackages": 1, 
"measurements": { 
   "length": 30.0, 
   "width": 20.0, 
   "height": 10.0, 
   "weight": 1.0, 
   "linearUom": "CM", 
   "massUom": "KG" 
   } 

2.1.2 Address information

Next are the addresses. Basically, the carrier needs to know where the shipment has to be picked up and where it has to be delivered. These address segments are called the SEND and RECV addresses, from sender and receiver respectively.

There are 2 additional address types: INV for the invoice and 3PTY for the 3rd party billing details.

Regardless of the type, every address can contain the same data fields.

"addresses": [ 
   { 
   "type": "RECV", 
   "name": "Transsmart",
   "addressLine1": "Ellen Pankhurststraat", 
   "addressLine2": "2de etage", 
   "houseNo": "1c", "city": "Tilburg", 
   "zipCode": "5032MD", 
   "country": "NL", 
   "contact": "Jan Voorbeeld", 
   "email": "jan@test.com" 
   }, { 
   "type": "SEND", 
   "name": "Transsmart B.V.", 
   "addressLine1": "Ellen Pankhurststraat", 
   "addressLine2": "1e verdieping Entrada", 
   "houseNo": "1A", 
   "city": "Tilburg", 
   "zipCode": "5032 MD", 
   "country": "NL", 
   "contact": "Piet Voorbeeld", 
   "email": piet@voorbeeld.nl 
   } 
]

2.1.3 Package details

The next block is for the package details and contains one line for every kind of package. A package can be of several types, for example, a pallet or a box.

A single package is also referred to as a shipment line. You can set your own identifier to the package in the field shipmentLineId.

The quantity is the amount of unique packages you are shipping. For example, if you are shipping 2 identical boxes with the same measurements you can set quantity to 2. This will generate 2 labels with 2 different airwaybills. Please note, that a response will always give a shipmentline per package although you have provided quantity 2. This is because every package will have its own unique airway bill (or barcode).

"packages": [
   {
   "lineNo": 1,
   "packageType": "BOX", 
   "description": "Doos", 
   "shipmentLineId": "4567", 
   "quantity": 1, 
   "measurements": {
   "length": 30.00, 
   "width": 20.00, 
   "height": 10.00, 
   "weight": 1.00, 
   "linearUom": "CM", 
   "massUom": "KG" 
   } ] 

2.1.4 Delivery note information

Every package can contain delivery note information. This information is not mandatory, but might be needed in particular situations for cross-border shipments or when Transsmart has to make additional documentation like invoices or pack slips.

2.2 Request example

Below is a complete example of what a single booking request could look like.

{
"reference": "TESTv2",
"carrier": "EEX",
"value": 25,
"valueCurrency": "EUR",
"pickupDate": "2024-03-14",
"service": "NON-DOCS",
"serviceLevelTime": "EUROPLUS",
"serviceLevelOther": "",
"incoterms": "CPT",
"numberOfPackages": 1,
"measurements": {
   "length": 30.0,
   "width": 20.0,
   "height": 10.0,
   "weight": 1.0,
   "linearUom": "CM",
   "massUom": "KG"
   },
"addresses": [
   {
   "type": "RECV",
   "name": "Transsmart",
   "addressLine1": "Ellen Pankhurststraat",
   "addressLine2": "2de etage",
   "houseNo": "1c",
   "city": "Tilburg",
   "zipCode": "5032MD",
   "country": "NL",
   "contact": "Jan Example",
   "email": "jan@example.com"
   }, {
   "type": "SEND",
   "name": "Transsmart B.V.",
   "addressLine1": "Ellen Pankhurststraat",
   "addressLine2": "1e verdieping Entrada",
   "houseNo": "1A",
   "city": "Tilburg",
   "zipCode": "5032 MD",
   "country": "NL",
   "contact": "Piet Example",
   "email": "piet@example.nl"
   }
   ],
"packages": [
   {
   "lineNo": 1,
   "packageType": "BOX",
   "description": "Doos",
   "shipmentLineId": "4567",
   "quantity": 1,
   "measurements": {
      "length": 30.00,
      "width": 20.00,
      "height": 10.00,
      "weight": 1.00,
      "linearUom": "CM",
      "massUom": "KG"
      }
   }
   ]
}

3 Printing the label

The description below is valid for both labels and all other transport documents related to your shipments.

3.1 Trigger the print action

There are three ways to print the documents:

1. For an existing shipment, retrieve the actual documents and send them to your application printer.
    
2. For an existing shipment, send a separate print request and print via SmartPrint.
    
3. For a new shipment, send a booking request including a print action and print via SmartPrint

Below, you will find a detailed explanation of each option. At the end of the chapter, there is some extra information about SmartPrint, the Transsmart printing tool.

3.1.1 Document retrieval

Retrieving the documents for a specific shipment is easy. Simply send a request to v2/prints as described in the developer documentation and set the rawJob parameter to true.

The response will contain a base64 encoded string. The actual content can be zpl code or a pdf document, depending on your account configuration.

3.1.2 Send print request

This works exactly as in the previous paragraph, except for the rawJob parameter that needs to be set to false.

This way the documents to be printed are queued within Transsmart, picked up by SmartPrint installed in your network, and sent to your printers that way.

3.1.3 Give a print action together with the booking and print via the Transsmart tools.

Have a look at the booking request details as described in the developer documentation. To automatically trigger a print action at the moment of sending the booking request, you need to change the path v2/shipments/BOOK to v2/shipments/PRINT.

3.2 SmartPrint

SmartPrint is the Transsmart printing tool that we have integrated in our platform.

You can download the latest version via MyTranssmart. Once logged in click the Printer icon and select the desired download. 

More information about SmartPrint can be found here.