TruckMate 2024.3 New Features: Web/APIs

Required upgrade (TM-173710)

TruckMate 2024.1 and later requires DB2 version 11.5.9.

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

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 these public APIs:

  • TruckMate REST API Bundle

  • Master Data APIs

  • Imaging

  • Freight Bill Import (deprecated)

  • Profile Import (deprecated)

Freight Bill Import and Profile Import were deprecated in March 2024. These APIs will be removed in TruckMate 2025.2. Customers should convert to REST and MasterData APIs.

For more information, see TruckMate REST API service replaces TM4Web REST APIs.

The API release notes cover all changes made to 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:

These tables list issues in numerical order by case number.

Orders API

Case Issue Case Name Description

TM-161014

Orders API - invalidBusinessLogic

Corrected invalid business error code.

TM-167404

Orders API - InvalidJsonObject

Corrected error description when sending request bodies that need to be a valid JSON object.

TM-171889

REST API - orders/barcodes - Setting/Updating Length, Width or Height Not Auto-Calculating Cube

The cube value is now automatically calculated when barcode dimensions are provided in the request body (POST/PUT).

TM-172710

Sort order not incrementing properly when an order details record is created in the API.

Fixed an issue related to the Sort Order not being incremented properly.

TM-173181

ART GET - tm/orders with Vendor Web User Authorization

Fixed a 500 error encountered when using vendor web user authorization to access GET orders and orders/:orderId endpoints using the TruckMate REST API.

TM-174007

POST - IMP-04: Add 'Travel Mode' Parameter to orders/interliners Endpoint

Added travelMode field to POST orders/interliners request body. This now allows you to define a Travel Mode against a particular order.

TM-175793

GET orders/:orderId/shipInstructs should only return active shipping instruction records

This release automatically removes deleted ship instructions from the order instructions list, ensuring only active and relevant ship instructions are displayed.

TM-175876

Orders API - orderBy not working for contact fields

Orders API orderBy now working for contact fields.

TM-175885

ART - caller clientId validation response

The error message identifies the exact field where the validation failed by using a JSON path.

TM-176200

SQL Error when re-adding Shipping Instruction via API

Fixed an issue where a SQL error was encountered when using POST to re-add a ship instruction that had been previously removed from an order. The SQL error would be encountered if any custom triggers exist on the related shipping instructions table (TLSHIPINSTRUCT).

TM-176311

ART - Quotes add Active/Expiration

Added quoteStatus sub-resource to an order to show the active/expiration nature of quotes.

TM-176343

Orders API - orderBy not working for contact country fields

Fixed a typo where Country was misspelled as County. Typo has been corrected and the API is returning the requested data.

TM-176573

ART - return only orders.totalCharges for web auth user

For TID Web Client users, the fields tax1, tax2, charges, and totalCharges are always included in the response for mapping the Bill Summary section in the TMS Connector.

TM-177483

POST /orders invalidJsonObject returned when using copyOrderId option

Fixed issue where using the copyOrderId option in the POST orders endpoint was resulting in a invalidJsonObject error message.

TM-177901

Barcodes are not being created automatically when items are populated in order details.

Fixed an issue with barcodes not being created automatically when items are populated in order details.

Trips API

Case Issue Case Name Description

TM-168264

FB Assignment Unified Validation

As part of the TruckMate 2024.2 release, a large number of changes were made behind the scenes to improve validation workflows when freight bills are assigned to trips from numerous sources.

You should experience no difference in your daily workflow as part of these changes. The majority of these adjustments are behind the scenes, and were done as a priority effort to unify the workflows between Dispatch and Multi Mode Dispatch (among others) in terms of validation/warning/error messages when assigning bills to trips.

TM-174005

POST - IMP-05: Add 'Travel Mode' Parameter to trips/carriers Endpoint

Added travelMode field to POST trips/carriers request body. This allows you to define a Travel Mode against a particular trip.

TM-175046

Trips API - orderCarrierControl enum schema validation

Fixed values returned in GET trips?expand=carriers for orderCarrierControl to follow expected enum values.

TM-175046

Trips API - orderCarrierControl enum schema validation

Fixed values returned in GET trips?expand=carriers for orderCarrierControl to follow expected enum values.

TM-175145

ART - GET /trips - sortBy=status asc returns empty items[]

The order by functionality for status and statusDesc in GET trips has been corrected, ensuring accurate results for both ascending and descending orders.

TM-176040

ART - Inconsistent auth response when GET trips through TID and TM4WEB JWT

Fixed 403 response from the Trips API (GET /trips) when a client web user TID token is used for authentication.

TM-176069

ART - trips api, add expectedDate

Added the expectedDate field to the trips response. This new field will return the value of LEGSUM.LS_ETA_DATE for the active leg of a trip. Additionally, the eTA field will return the value of LEGSUM.LS_SCHEDULED_ARRIVAL for the active leg of a trip.

TM-176327

ART - GET /trips - count is incorrect when $filter is used

Fixed the issue where the GET trips count was incorrect when using $filter.

TM-176358

ART - GET trips - Allow $filter on carriers/accepted field

Added support to filter trips by carriers/accepted field.

TM-176425

ART Load Offers - Correcting GET /trips for Web Vendors to include trips assigned to the vendor

Fixed the GET trips and GET trips/tripNumber endpoints to only return trips currently assigned to the related vendor for vendor web users and not include trips with completed or cancelled carrier records.

TM-176447

ART Load Offers -ACCEPT/DECLINE Offer

Added support for accepting or rejecting a carrier load offer for both vendor web users and TruckMate users.

TM-176665

ART Load Offers - Filter probill, cancelled, rejected, completed carrierId of carriers

Added support for OData filtering of trips using the following filters:

  • carriers/probill

  • carriers/cancelled

  • carriers/rejected

  • carriers/completed

  • carriers/carrierId.

TM-176721

ART Load Offers - GET comment in trips.carriers

Added comment field for trip carriers

  • GET trips/:tripNumber/carriers

  • GET trips/:tripNumber/carriers/:loadSummaryId

TM-176781

ART Load Offers - trips/carriers add distance

Added distance and distanceUnits fields to trips/:tripNumber/carriers endpoint. Also added support for oData filtering ($filter) on carriers/distance from GET trips endpoint.

TM-177074

Art: Dispfunc status updates should not be hardcoded to MOBILE userid

Fixed an issue where location history entries made by the TruckMate REST API were showing MOBILE for the UPDATED_BY field. It will now populate the username corresponding to the authentication method used to make the API call.

TM-177805

'Route ID' not exposed to GET method of /trips API

Added routeId field to the trips API

  • GET /trips

  • GET /trips/:tripNumber

TM-178051

TM Rest api trips stops/resources do not expand and show

Fixed an issue where stop resources were not being returned correctly in the trips API for some trip records.

Finance API

Case Issue Case Name Description

TM-176910

ART Finance - Driver Payments - GET

Added support for retrieving driver payment records using the Finance API.

  • GET/finance/driverPayments

  • GET/finance/driverPayments/:paymentId

TM-177010

ART Finance - Driver Deductions - GET

Added support to retrieve driver deduction records using the Finance API.

  • GET/finance/driverDeductions

  • GET/finance/driverDeductions/:deductionId

TM-177011

ART Finance - Checks - GET

Added support to retrieve check records through the Finance API

  • GET/finance/checks

  • GET/finance/checks/:checkId

TM-177012

ART Finance - Taxes - GET

Added support to retrieve tax code records through the Finance API.

  • GET/finance/taxes

  • GET /finance/taxes/:taxId

TM-177013

ART Finance - Vendor Payments - GET

Added support for retrieving vendor payments through the Finance API.

  • GET/finance/vendorPayments

TM-177106

ART Finance - Driver Payment Codes - Get

Added support to retrieve driver payment code records through the Finance API.

  • GET/finance/driverPaymentCodes

TM-177107

ART Finance - Checks Bills - GET

Added support to retrieve check bill records through the Finance API.

  • GET/finance/checks/:checkId/bills

  • GET/finance/checks/:checkId/bills/:checkBillId

TM-177117

ART Finance - Driver Deduction Codes - GET

Added support for retrieving driver deduction code records through the Finance API.

  • GET/finance/driverDeductionCodes

TM-177144

ART Finance - Tax Rates - GET

Added support to retrieve tax rates through the Finance API.

  • GET/finance/taxes/:taxId/taxRates

  • GET/finance/taxes/:taxId/taxRates/:taxRateId

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, and so on.

Case Issue Case Name Description

TM-173986

ART web user - Update GET /clients to return records only for related client Ids for access code

Fixed an issue where GET /clients was returning client records for clients not related to the web access code associated with the client web user used for authentication.

TM-174532

IMP-06: masterData "GET vendors" add sub-resource "travelModes"

Added support for the travelModes in the GET vendors and GET vendors/:vendorId endpoints in the masterData API.

TM-175890

ART - MasterData - webUser Vendor Auth should return 403

webUser Vendor Auth will now return 403 for the endpoints:

  • /aChargeCodes

  • /commodities

  • /serviceLevels

TM-177014

ART Finance - MasterData Clients

Added the creditBalance field to GET clients and GET clients/clientId endpoints.

TM-177243

ART Service Startup and TID authentication

Implemented lazy fetching of JWKs until TID validation is triggered, speeding up ART server startup.

Other APIs

Case Issue Case Name Description

TM-161761

Update Documents descriptions

The documents description has been updated in the openAPI documentation to provide better clarification around Document Type and where the types can be configured.

TM-165806

All log levels/debug are enabled by default in ARTAdmin

Updated Art Server Administration so that only error and warning log levels are set by default when adding a new service.

TM-174546

PUT /orderCustomsData

Added support for the PUT method on the /orderCustomsData endpoint in the TruckMate REST API, which allows orders customs information to be updated through the REST API.

TM-174547

DEV: DELETE /orderCustomsData

Added support for the DELETE method on the /orderCustomsData/:customsId endpoint. This allows specific order customs information records to be deleted.

TM-174601

TruckMate 404 response

Fixed an issue where 400 errors were being returned before 404 in the TruckMate REST API (tm) endpoints.

TM-174805

TruckMate API missingRequiredField

Fixed several endpoints in the TruckMate REST API that did not properly return the missingRequiredFields response when the request body was missing required fields.

TM-175596

ART - Add imagingVendor field to GET /documents

Added imagingVendor field to GET documents response body. Also added support for the $filter, $select and $orderBy parameters for the GET /documents endpoint.

TM-175639

New endpoint GET /tm/userFieldsData

Added support to retrieve user field data through the REST API. It currently supports retrieval of user fields data for order interliner or trip carrier records.

TM-175641

New endpoint PUT userFieldsData

Added support to update user field data through REST API.

TM-176029

GET documents/:documentType/searchValues/:documentIdentifier/:documentFormat is returning a 403 for a valid token

Fixed an issue where a 403 error was being returned by endpoint GET documents/:documentType/searchValues/:documentIdentifier/:documentFormat when using a valid token.

TM-176116

POST /orderCustomsData - Remove invalidDBValue validations for certain fields

Removed InvalidDBValue 400 error response validation for certain ace and aci related fields in POST /orderCustomsData and PUT orderCustomsData/customsId in the TruckMate REST API to more closely match the behavior in the Customer Service application.

TM-176117

POST /ordersCustomsData - Default customs broker is not being assigned

Added logic to the TruckMate REST API POST /orderCustomsData endpoint, such that the customsBrokerId is automatically assigned if a default customsBroker is specified in the related client profile on the order and if a value for customsBrokerId is not included in the request body

TM-176118

POST /orderCustomsData - Autopopulation of cargoControlNumber and improvements needed around validation

Added logic for the cargoControlNumber field to populate automatically if not provided in the request body for POST /orderCustomsData endpoint.

TM-176123

POST /ordersCustomsData - Add isDefaultBroker to POST request body

Added the isDefaultBroker field to the request body for the POST /orderCustomsData endpoint which allows for a customs broker to be designated as the default when creating the order customs information record.

TM-176184

ART - GET /documents - Error Descriptions

Fixed error messages returned by documents related endpoints to be more consistent and detailed.

TM-176297

PUT /ordersCustomsData/customsId - Add isDefaultBroker to PUT request body

Added isDefaultBroker field to the PUT orderCustomsData/customsId endpoint, which allows a customs broker record to be set as the default when updating an order customs information record.

TM-176631

ART - Contract Tests - pathParameter validation

Fixed an issue where exceedsMaxLength error code was not being returned for multiple endpoints if the related string value in the URL/path exceeds the maximum possible length for that value.

TM-176953

ART Service connection to DB cannot recover after DB2 is restarted

Fixed an issue where the ART service was not recovering properly if the connection to the database is lost.

TM-177143

Fix link to openAPI to use production URL instead of dev

Updates summaries and descriptions of the OpenAPIs for TruckMate and MasterData services.

TM4Web

Case Issue Case Name Description

TM-175991

TM4Web Quote header fields and the Quote result columns are duplicated

Fixed an issue where fields and columns were being duplicated if the database has related TM4Web tables defined multiple schemas.

TM-176049

TM4Web page vendor_agent_assigned_deliveries does not load

Fixed an issue on the page vendor_agent_assigned_deliveries page on TM4WEB. The issue was that the grid would not load, and would show a continuous loading icon.

TM-176356

Able to sent delivery notifications to email address 'NONE' via TM4Web

Fixed an issue in TM4Web where invalid email address values could be submitted for order entry confirmation emails.

TM-176370

Update PHP version in ISO to PHP 8.2.20

PHP version for TM4Web was upgraded to 8.2.20. The ISO installation portion related to Web Server now includes the PHP 8.2.20 version.

TM-176578

TM4Web Orders do not get AVAIL in Status History and LTL Term Plan records

Fixed an issue where the GV_TMSCHEMA global variable was not being set correctly by TM4Web in all scenarios, which caused some order related records to not be created properly during order entry.

TM-176662

TM4Web Vendor Acc charge is applied to A movement type instead of B

Fixed an issue where accessorial charges were being applied to the incorrect interliner record on an order through the vendor assigned deliveries and pickups pages in TM4Web.