TruckMate 2022.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.

This guide covers changes made to all TruckMate public APIs.

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

This table lists issues in alphabetical order by case number.

Case Number	Case Name	Release Notes
TM-139500	allow DELETE /orders/:orderId/details/:orderDetailId	Added support for the DELETE method to delete a specified detail record (orderDetailId) for the specified order (orderId).
TM-155207	create openAPI doc for connectedDock	Add openAPI doc for ConnectedDock endpoints.
TM-155812	Authentication changes for Back Office APIs	Session ID authentication has been removed from these APIs: FB Import Profile Imaging In addition, the login and logout endpoints have been removed. Now, the only supported authentication method involves the use of an API key as a bearer token.
TM-165475	Dev 3: orders.interliners add aCharges resource response only	Add the aCharges child resource under interliners. It will be returned in GET interliners API call if it is specified in the expand url parameter as 'expand=aCharges'; i.e., it won’t be returned in the GET API call by default.
TM-165599	Update openAPI documentation in Orders API to reflect new functionality added for waterfall tendering	Updated documentation for /interliners and /xrefCode in /orders based on the latest functionalities from waterfall tendering
TM-165647	TM API order request crash’s with CUSTOMDEF or TRACE filed value containing "SELECT" wording	Resolved an issue with the REST API Order request crashing when CUSTOMDEF or TRACE were being filled with the text "SELECT".
TM-165662	DEV: Orders API - POST POD	Added support for the POST method to creating a new order with pods, and add pods to existing orders. The three CSERV - Allow Edit of OS&D/POD Fields security settings are also considered for this POST method.
TM-165664	Dev: Orders Orders API - PUT POD	Added support for the PUT method to update a proof of delivery (POD) record on an order.
TM-165665	DEV: Orders API - DELETE POD	Added support for the DELETE method to delete a proof of delivery (POD) record from an order.
TM-165691	Add disclaimer to filter description	The following disclaimer is added to the $filter description for the relevant GET APIs in OpenAPI doc such as Appointments, Orders and Trips: "Filter items by property values, see Filtering. Note, not all features of oData filter syntax are supported."
TM-165692	Add RATE fields when creating/updating	Allow POST or PUT on rates related fields only when manuallyRate field is set to True. The fields are: ratePer, rate, rateUnits, asRate and asBreak
TM-165698	Add extra disclaimer regarding documentation on openAPI document for Profile, FB Import and Imaging	Added extra disclaimer regarding latest released version of TruckMate on Open API Document for MasterData, Imaging, FB Import and Profile.
TM-165732	Add to masterData GET /commodities endpoint to return more CMODTY data	Retrieve more info from the GET commodities APIs
TM-165827	Handle rate fields for creating order from an exist order/quote	When manuallyRated is set to 'False', the "rate","ratePer", "rateUnits", "asRate","asBreak" fields will be set to 0 or empty string in the new order even they’re specified in the POST request. When manuallyRated is set to 'True', and if the "rate","ratePer", "rateUnits", "asRate","asBreak" fields are specified in the POST request, the above fields will be saved to the new order. Otherwise, these fields will be set to 0 or empty string.
TM-165908	details.barcodes issues when copying an existing Quote or Order	Copying an existing Quote will skip to copy the details.barcodes.cubePolicyValue. Copying an existing Order will include the details.barcodes.cubePolicyValue. In both cases, the details.barcodes.location fields will be populated by the internal logic as 'BCLAN' - related to the terminal zone, order.current_zone and order.current_status.
TM-166029	500 error raised from barcodes EArtControllerException	Fixed an issue where 500 server error returns sending POST details barcode request.
TM-166134	Upgrade PHP	Upgraded PHP version to 8.1.12 for TM4Web and installer.
TM-166172	Add 'clientCountry' to /trips/{tripNumber}/stops API resource	Add a new field called 'clientCountry' to the 'stop' schema, and it is part of the stops child resources.
TM-166203	Update WorkOptima URL to allow for new query string parameter "Document Type"	Allow to search images by specifying the 'Document Type' parameter in the WorkOptima URL.
TM-166306	getMatchingOpenApiPath() matches the first path found with duplicated path name	Fixed the issue with util function, getMatchingOpenApiPath() matching incorrect paths
TM-166486	Error response updated	The Imaging API error response now follows TruckMate standards.
TM-166508	Orders API does not allow custom pickupAT name and address if the pickupAT clientId is null	Fixed the issue with pickupAt data gets replaced with shippers when pickupAt contains no clientId
TM-166523	aChargeCodes API - Add new field freeStopsCount to aChargeDetail	Added support for the freeStopsCount field in the masterData API for accessorial charges.
TM-166594	ConnectedDock auth endpoint	Added OAuth2 security scheme to ConnectedDock Open API. Decorated all endpoints with the new security scheme.

Case Number

Case Name

Release Notes

TM-139500

allow DELETE /orders/:orderId/details/:orderDetailId

Added support for the DELETE method to delete a specified detail record (orderDetailId) for the specified order (orderId).

TM-155207

create openAPI doc for connectedDock

Add openAPI doc for ConnectedDock endpoints.

TM-155812

Authentication changes for Back Office APIs

Session ID authentication has been removed from these APIs:

FB Import
Profile
Imaging

In addition, the login and logout endpoints have been removed.

Now, the only supported authentication method involves the use of an API key as a bearer token.

TM-165475

Dev 3: orders.interliners add aCharges resource response only

Add the aCharges child resource under interliners. It will be returned in GET interliners API call if it is specified in the expand url parameter as 'expand=aCharges'; i.e., it won’t be returned in the GET API call by default.

TM-165599

Update openAPI documentation in Orders API to reflect new functionality added for waterfall tendering

Updated documentation for /interliners and /xrefCode in /orders based on the latest functionalities from waterfall tendering

TM-165647

TM API order request crash’s with CUSTOMDEF or TRACE filed value containing "SELECT" wording

Resolved an issue with the REST API Order request crashing when CUSTOMDEF or TRACE were being filled with the text "SELECT".

TM-165662

DEV: Orders API - POST POD

Added support for the POST method to creating a new order with pods, and add pods to existing orders. The three CSERV - Allow Edit of OS&D/POD Fields security settings are also considered for this POST method.

TM-165664

Dev: Orders Orders API - PUT POD

Added support for the PUT method to update a proof of delivery (POD) record on an order.

TM-165665

DEV: Orders API - DELETE POD

Added support for the DELETE method to delete a proof of delivery (POD) record from an order.

TM-165691

Add disclaimer to filter description

The following disclaimer is added to the $filter description for the relevant GET APIs in OpenAPI doc such as Appointments, Orders and Trips: "Filter items by property values, see Filtering. Note, not all features of oData filter syntax are supported."

TM-165692

Add RATE fields when creating/updating

Allow POST or PUT on rates related fields only when manuallyRate field is set to True. The fields are: ratePer, rate, rateUnits, asRate and asBreak

TM-165698

Add extra disclaimer regarding documentation on openAPI document for Profile, FB Import and Imaging

Added extra disclaimer regarding latest released version of TruckMate on Open API Document for MasterData, Imaging, FB Import and Profile.

TM-165732

Add to masterData GET /commodities endpoint to return more CMODTY data

Retrieve more info from the GET commodities APIs

TM-165827

Handle rate fields for creating order from an exist order/quote

When manuallyRated is set to 'False', the "rate","ratePer", "rateUnits", "asRate","asBreak" fields will be set to 0 or empty string in the new order even they’re specified in the POST request.

When manuallyRated is set to 'True', and if the "rate","ratePer", "rateUnits", "asRate","asBreak" fields are specified in the POST request, the above fields will be saved to the new order. Otherwise, these fields will be set to 0 or empty string.

TM-165908

details.barcodes issues when copying an existing Quote or Order

Copying an existing Quote will skip to copy the details.barcodes.cubePolicyValue. Copying an existing Order will include the details.barcodes.cubePolicyValue. In both cases, the details.barcodes.location fields will be populated by the internal logic as 'BCLAN' - related to the terminal zone, order.current_zone and order.current_status.

TM-166029

500 error raised from barcodes EArtControllerException

Fixed an issue where 500 server error returns sending POST details barcode request.

TM-166134

Upgrade PHP

Upgraded PHP version to 8.1.12 for TM4Web and installer.

TM-166172

Add 'clientCountry' to /trips/{tripNumber}/stops API resource

Add a new field called 'clientCountry' to the 'stop' schema, and it is part of the stops child resources.

TM-166203

Update WorkOptima URL to allow for new query string parameter "Document Type"

Allow to search images by specifying the 'Document Type' parameter in the WorkOptima URL.

TM-166306

getMatchingOpenApiPath() matches the first path found with duplicated path name

Fixed the issue with util function, getMatchingOpenApiPath() matching incorrect paths

TM-166486

Error response updated

The Imaging API error response now follows TruckMate standards.

TM-166508

Orders API does not allow custom pickupAT name and address if the pickupAT clientId is null

Fixed the issue with pickupAt data gets replaced with shippers when pickupAt contains no clientId

TM-166523

aChargeCodes API - Add new field freeStopsCount to aChargeDetail

Added support for the freeStopsCount field in the masterData API for accessorial charges.

TM-166594

ConnectedDock auth endpoint

Added OAuth2 security scheme to ConnectedDock Open API. Decorated all endpoints with the new security scheme.