TruckMate 2023.4 New Features: Web/APIs

Required upgrade (TM-162557)

TruckMate 2022.x and later requires DB2 version 11.5.6.

You must upgrade your instance of DB2 to this version before upgrading TruckMate.

Support for DB2 version 11.1.3 ended as of TruckMate 2021.4.

The TruckMate ART Server is a high-performance, multi-threaded HTTP server running TruckMate API services designed using Representational State Transfer (RESTful) API principles.

The ART Server currently supports the following public APIs:

TruckMate REST API Bundle
Master Data APIs
Freight Bill Import
Profile Import
Imaging

The API release notes cover all changes made to all TruckMate public APIs.

TruckMate API

Public link: https://truckmatecloudhub.trimble-transportation.com/tm/documentation

The TruckMate REST APIs are a comprehensive set of RESTful services, allowing developers to integrate TruckMate with custom or third-party applications, automate tasks, and much more.

Some ways you can use these APIs include:

Internal systems: Share data and streamline internal business processes
External data sharing and connection: Share TruckMate data with third party systems
Application integrations: Access TruckMate data in real time
Embedded content: Request TruckMate data to include onto your site

Available endpoints and methods differ depending on the license keys and authorization methods used.

To use the TruckMate REST APIs, we recommend upgrading directly to the latest version of TruckMate instead of an earlier release. This gives you access to the most current, improved, and expanded set of API methods and endpoints.

The following additional information is available on the Trimble Transportation Learning Center:

TruckMate REST API Service Getting Started
The TM4Web OpenAPI JSON information can be viewed as a website.

This may be especially useful if you are in the early stages of implementing REST APIs and do not have an ART Server running yet.
The OpenAPI JSON file itself is available for downloading.
ART Server Administrator Guide

These tables list issues in alphabetical order by case number.

Orders API

Case Issue	Case Name	Endpoint	Description
TM-140285	POST /orders API using webUser credentials	POST /orders?type=T POST /orders?type=Q	Added support for web user authorization for POST /orders for type P and Q records. The caller used in the request body must be a related client ID for the web access code linked to the web user. The auto post, accept and update settings from WebAdmin > Order Entry > PUR > Auto Approve, Post and Update tab are taken into account when an order is created using Web user authorization.
TM-169529	Orders API authorized expand fields - details	GET /orders?expand=details GET /orders/:orderId?expand=details	Added support for the order details to only return selected detail fields configured in WebAdmin > Bill Details > Details when using web user authentication to expand details from the orders API.
TM-171105	TMS_ORDERS_SEARCH_VW Remove PODD_SIGNED_BY and PODD_SIGNED_ON	GET /orders GET /orders/:orderId	Removed two POD related fields that are no longer being used in the orders API. The related fields can be retrieved using the orders POD child resource (orders/:orderId/pods).
TM-171307	orders.statusHistory - Web User Auth	GET /orders?type=T&expand=statusHistory GET /orders/:orderId/statusHistory?type=T	When a 'Web User' retrieves the status history of an order through GET-orders endpoint, only the status history records with the status codes that are listed the 'Shown Status Codes' panel in WebAdmin will be returned in statusHistory array field in the response. For example: If an order has multiple status history records but only some of them (e.g., 2 of 6) has the 'Shown Status Code', only those 2 records will be returned in the response. If all the status history records do not have the 'Shown Status Code', the statusHistory will be an empty array. The 'Shown Status Codes' panel is located in Web Administration app (WebAdmin.exe) - Client Features - Bill Details - Standard Viewing - Status History - Status Code tab. In the GET endpoint, the type must be set to T.
TM-171456	ART - add filter support for caller, shipper, consignee, otherContact, pickupAt and careOf	GET /orders GET /orders/:orderId	Added support for $filter for caller, shipper, otherContact, pickupAt, careOf fields at the orders parent level in the Orders API
TM-171940	Orders API - GET - PTLORDER Custom Defined fields	GET /orders?expand=customDefs&type=P GET /orders?expand=customDefs&type=P&$filter=orderId eq :orderId GET /orders/:orderId?expand=customDefs&type=P GET /orders/:orderId/customDefs?type=P GET /orders/:orderId/customDefs/:customDefId?type=P	The orders endpoints now return 'custom defined fields' for 'pickup request' orders. The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor. Note that the type=P must be included in the endpoint url.
TM-171941	Orders API - POST - PTLORDER Custom Defined fields	POST /orders?type=P POST /orders/:orderId/customDefs?type=P	Creating a new 'pickup request' order can now included the customDefs. The customDefs can also be added to after the 'pickup request' order is created as long as the order doesn’t have any custom defined fields. If custom defined fields exists, users should use the PUT endpoint instead. The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor. Note that the type=P must be included in the endpoint url.
TM-171942	Orders API - PUT - PTLORDER Custom Defined fields	PUT /orders/:orderId?type=P PUT /orders/:orderId/customDefs/:customDefId?type=P	In the Orders API allow updating Custom Defined fields on a Pickup Request, from the following endpoints: PUT /orders/:orderId?type=P PUT /orders/:orderId/customDefs/:customDefId?type=P
TM-171943	Orders API - DELETE - PTLORDER Custom Defined fields	DELETE /orders/:orderId?type=P DELETE /orders/:orderId/customDefs/:customDefId?type=P	The custom defined fields of 'pickup request' orders can now be deleted by specifying the orderId. A particular custom defined field can be deleted by specifying the 'customDefId'. The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor. Note that the type=P must be included in the endpoint url.

Case Issue

Case Name

Endpoint

Description

TM-140285

POST /orders API using webUser credentials

POST /orders?type=T
POST /orders?type=Q

Added support for web user authorization for POST /orders for type P and Q records.

The caller used in the request body must be a related client ID for the web access code linked to the web user.

The auto post, accept and update settings from WebAdmin > Order Entry > PUR > Auto Approve, Post and Update tab are taken into account when an order is created using Web user authorization.

TM-169529

Orders API authorized expand fields - details

GET /orders?expand=details
GET /orders/:orderId?expand=details

Added support for the order details to only return selected detail fields configured in WebAdmin > Bill Details > Details when using web user authentication to expand details from the orders API.

TM-171105

TMS_ORDERS_SEARCH_VW Remove PODD_SIGNED_BY and PODD_SIGNED_ON

GET /orders
GET /orders/:orderId

Removed two POD related fields that are no longer being used in the orders API. The related fields can be retrieved using the orders POD child resource (orders/:orderId/pods).

TM-171307

orders.statusHistory - Web User Auth

GET /orders?type=T&expand=statusHistory
GET /orders/:orderId/statusHistory?type=T

When a 'Web User' retrieves the status history of an order through GET-orders endpoint, only the status history records with the status codes that are listed the 'Shown Status Codes' panel in WebAdmin will be returned in statusHistory array field in the response. For example:

If an order has multiple status history records but only some of them (e.g., 2 of 6) has the 'Shown Status Code', only those 2 records will be returned in the response.
If all the status history records do not have the 'Shown Status Code', the statusHistory will be an empty array.

The 'Shown Status Codes' panel is located in Web Administration app (WebAdmin.exe) - Client Features - Bill Details - Standard Viewing - Status History - Status Code tab.

In the GET endpoint, the type must be set to T.

TM-171456

ART - add filter support for caller, shipper, consignee, otherContact, pickupAt and careOf

GET /orders
GET /orders/:orderId

Added support for $filter for caller, shipper, otherContact, pickupAt, careOf fields at the orders parent level in the Orders API

TM-171940

Orders API - GET - PTLORDER Custom Defined fields

GET /orders?expand=customDefs&type=P
GET /orders?expand=customDefs&type=P&$filter=orderId eq :orderId
GET /orders/:orderId?expand=customDefs&type=P
GET /orders/:orderId/customDefs?type=P
GET /orders/:orderId/customDefs/:customDefId?type=P

The orders endpoints now return 'custom defined fields' for 'pickup request' orders. The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor.

Note that the type=P must be included in the endpoint url.

TM-171941

Orders API - POST - PTLORDER Custom Defined fields

POST /orders?type=P
POST /orders/:orderId/customDefs?type=P

Creating a new 'pickup request' order can now included the customDefs.

The customDefs can also be added to after the 'pickup request' order is created as long as the order doesn’t have any custom defined fields. If custom defined fields exists, users should use the PUT endpoint instead.

The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor.

Note that the type=P must be included in the endpoint url.

TM-171942

Orders API - PUT - PTLORDER Custom Defined fields

PUT /orders/:orderId?type=P
PUT /orders/:orderId/customDefs/:customDefId?type=P

In the Orders API allow updating Custom Defined fields on a Pickup Request, from the following endpoints:
PUT /orders/:orderId?type=P
PUT /orders/:orderId/customDefs/:customDefId?type=P

TM-171943

Orders API - DELETE - PTLORDER Custom Defined fields

DELETE /orders/:orderId?type=P
DELETE /orders/:orderId/customDefs/:customDefId?type=P

The custom defined fields of 'pickup request' orders can now be deleted by specifying the orderId. A particular custom defined field can be deleted by specifying the 'customDefId'.

The custom defined fields must be defined in Codes Maintenance. The custom defined fields can be viewed and edited using the Order Preprocessor.

Note that the type=P must be included in the endpoint url.

Trips API

Case Issue	Case Name	Endpoint	Description
TM-166170	Add count to GET /trips response body		Added count field to the response body for trips and all trips child resource endpoints when the GET method is used.

Case Issue

Case Name

Endpoint

Description

TM-166170

Add count to GET /trips response body

Added count field to the response body for trips and all trips child resource endpoints when the GET method is used.

Master Data API

Public link: https://truckmatecloudhub.trimble-transportation.com/masterData/documentation

The Master Data management API allows an external system to create, retrieve, update or delete TruckMate configuration data. Some data types include client, vendor and driver profiles, as well as sites, zones, commodity codes, etc.

These tables list issues in alphabetical order by case number.

Clients

Case Issue	Case Name	Endpoint(s)	Description
TM-168323	clients and vendors aChargeCodes - sort and filter	GET /clients/clientId/aChargeCodes GET /vendors/vendorId/aChargeCodes GET /drivers	The following 3 sets of endpoints now support the $orderby and $filter url parameters: GET /clients/clientId/aChargeCodes GET /vendors/vendorId/aChargeCodes GET /drivers
TM-171745	MasterData GET /clients - Web User Auth	GET /clients GET /clients/:clientId	When a TM4WEB user invokes the GET clients endpoint, the result will only return client profiles with 'webEnabled' field is set to true.

Case Issue

Case Name

Endpoint(s)

Description

TM-168323

clients and vendors aChargeCodes - sort and filter

GET /clients/clientId/aChargeCodes
GET /vendors/vendorId/aChargeCodes
GET /drivers

The following 3 sets of endpoints now support the $orderby and $filter url parameters:

GET /clients/clientId/aChargeCodes
GET /vendors/vendorId/aChargeCodes
GET /drivers

TM-171745

MasterData GET /clients - Web User Auth

GET /clients
GET /clients/:clientId

When a TM4WEB user invokes the GET clients endpoint, the result will only return client profiles with 'webEnabled' field is set to true.

Zones

Case Issue	Case Name	Endpoint	Description
TM-170390	DEV: MasterData GET /zones - MOVE FROM TM	GET /zones Get /zones/:zoneId	The zones endpoint retrieves zone code records that can be used to specify zones for a freight bill or a trip. It supports $orderBy zoneId and $filter.

Case Issue

Case Name

Endpoint

Description

TM-170390

DEV: MasterData GET /zones - MOVE FROM TM

GET /zones
Get /zones/:zoneId

The zones endpoint retrieves zone code records that can be used to specify zones for a freight bill or a trip. It supports $orderBy zoneId and $filter.

ART

Case Issue	Case Name	Description
TM-170511	Multiple /tm (REST API) endpoints are returning 404 instead of 400 errors first	Fixed multiple occurrences where a 404 error was being returned first instead of a 400 schema validation errors. This is in an effort to make the error response handling more consistent.
TM-170819	POST /login endpoint returns a 200 instead of a 201	Fixed an issue where the POST login endpoint was returning a 201 response code instead of 200 in the TruckMate and masterData REST APIs
TM-171751	Investigate: Connection string(RemoteDatabase) missing	Fixed an issue with the ART service where database missing error was encountered when creating a mileserver client.
TM-171943	Orders API - DELETE - PTLORDER Custom Defined fields	The custom defined fields of 'pickup request' orders can now be deleted by specifying the orderId. A particular custom defined field can be deleted by specifying the 'customDefId'.
TM-171987	Web user authentication - orderDetailId should always be returned in expanded details section	Fixed an issue with orderDetailId was not always being returned in the order details section in the orders API when using web user authentication.
TM-172277	DEV: MasterData DELETE /zones
TM-172291	TM API Trips Stops are missing time component value for field appointmentTime	When the stop records are retrieved via GET-trip endpoints, the appointmentTime and appointmentTimeEnd fields are populated in DateTimeToISO8601 format based on the stop type. If the stop type is 'pick', the two date-time fields are populated with the 'Pick Up' time fields set in CServ. If the stop type is 'drop', the two date-time fields are populated with the 'Deliver' time fields set in CServ.
TM-172316	Creating orders with two or more dangerous goods flag set and UN numbers via API causes same UN Number to be assigned on the Dangerous Goods tab	Fixed an issue where creating orders with detail lines that referenced distinct UN Numbers through the orders API would result in duplicate records on the dangerous goods section of the order.

Case Issue

Case Name

Description

TM-170511

Multiple /tm (REST API) endpoints are returning 404 instead of 400 errors first

Fixed multiple occurrences where a 404 error was being returned first instead of a 400 schema validation errors. This is in an effort to make the error response handling more consistent.

TM-170819

POST /login endpoint returns a 200 instead of a 201

Fixed an issue where the POST login endpoint was returning a 201 response code instead of 200 in the TruckMate and masterData REST APIs

TM-171751

Investigate: Connection string(RemoteDatabase) missing

Fixed an issue with the ART service where database missing error was encountered when creating a mileserver client.

TM-171943

Orders API - DELETE - PTLORDER Custom Defined fields

The custom defined fields of 'pickup request' orders can now be deleted by specifying the orderId. A particular custom defined field can be deleted by specifying the 'customDefId'.

TM-171987

Web user authentication - orderDetailId should always be returned in expanded details section

Fixed an issue with orderDetailId was not always being returned in the order details section in the orders API when using web user authentication.

TM-172277

DEV: MasterData DELETE /zones

TM-172291

TM API Trips Stops are missing time component value for field appointmentTime

When the stop records are retrieved via GET-trip endpoints, the appointmentTime and appointmentTimeEnd fields are populated in DateTimeToISO8601 format based on the stop type.

If the stop type is 'pick', the two date-time fields are populated with the 'Pick Up' time fields set in CServ.
If the stop type is 'drop', the two date-time fields are populated with the 'Deliver' time fields set in CServ.

TM-172316

Creating orders with two or more dangerous goods flag set and UN numbers via API causes same UN Number to be assigned on the Dangerous Goods tab

Fixed an issue where creating orders with detail lines that referenced distinct UN Numbers through the orders API would result in duplicate records on the dangerous goods section of the order.

TM4Web

Case Issue	Case Name	Description
TM-171920	TM4Web Microdea Imaging Email button failing to send	Fixed an issue where the email button used for sending imaging documents by email was encountering an error.
TM-171964	TM4Web error after Post cannot convert undefined or null to object	Fixed an issue where a PHP error would be encountered when posting a shipment using TM4Web.
TM-172001	Weight and Dim Weight are dropped from Web Quote Pickup Request	Fixed an issue where weight and dimension information was not being transferred when creating a pickup request from a quote.

Case Issue

Case Name

Description

TM-171920

TM4Web Microdea Imaging Email button failing to send

Fixed an issue where the email button used for sending imaging documents by email was encountering an error.

TM-171964

TM4Web error after Post cannot convert undefined or null to object

Fixed an issue where a PHP error would be encountered when posting a shipment using TM4Web.

TM-172001

Weight and Dim Weight are dropped from Web Quote Pickup Request

Fixed an issue where weight and dimension information was not being transferred when creating a pickup request from a quote.