TruckMate 2021.3 New Features: Web / APIs
TM4Web
Expanded TruckMate REST API service (TM-155438)
A more feature rich, extensive and centralized TruckMate REST API service has been enhanced to provide the same set of API methods, endpoints and authorization processes currently available within the TM4Web and other REST API services as part of an expanding set of additonal endpoints. Several of the existing TM4Web API service features have been already been merged into the TruckMate REST API service as part of an ongoing enhancement process. This includes:
-
TM4Web SOAP API
-
TM4Web REST API
-
Freight Search API
The TruckMate 2021.2 version released on July 16th, 2021 already includes a complete alternative to the TM4Web REST APIs within the TruckMate REST API service. All of the TM4Web APIs can be accessed by migrating your integrations over to the TruckMate REST APIs, which include all the same features and data currently available in the TM4Web REST APIs along with several enhancements.
Starting with TruckMate 2021.2, notice messages are displayed in the TM4Web REST API responses in the form of a Sunset tag. The Sunset response header tag will be included within all TM4Web REST API request calls to bring this notice about the change deadline to the attention of your API Developers.
Sunset: "Thu, 31 Mar 2022 23:59:59 GMT"
| The existing TM4Web REST web service and SOAP web service will remain unchanged until March 31, 2022. |
After the sunset period, the API being retired will remain available for an additional (1 year) along with a deprecation header. No revisions, enhancements or functional fixes will be applied to these services after the sunset period and you will need to migrate the API to the newest “TruckMate REST API” web service configuration before March 31, 2023.
Frequently asked questions
Questions about long term changes to TruckMate APIs and the Migration to new TruckMate REST API:
- Why is Trimble TruckMate making this change?
-
The consolidation of API endpoints will allow Trimble to improve quality control and allow TruckMate team members to respond more quickly to emerging customer requests regarding the API.
- How will this affect me?
-
The TruckMate 2021.2 release in July 2021 provides a complete alternative to the TM4Web REST & SOAP APIs by migrating your integrations over to the TruckMate REST API, which provides all the same access to features and data previously available in the TM4Web REST APIs along with several new ones.
You will need to migrate the API to the newest “TruckMate REST API” web service configuration before March 31, 2023.
Note: The existing TM4Web REST web service and SOAP web service will be unchanged until March 31, 2022. (The SOAP web services were merged with the TM4Web REST API’s previously in TruckMate version 2019.2 so the SOAP APIs are also avaialble in the new TruckMate REST API service.)
- When can I start using the new API?
-
With the July 2021 TruckMate 2021.2 release.
- How do I access the new API?
-
-
Set up and launch the TruckMate REST API Service via the ART Administrator.
-
All previously available TM4Web REST API endpoints will now also be available through the TruckMate service so the only change required to your integrations is to change the “tm4web” endpoint to “tm".
For example change
DOMAIN/tm4web/orderstoDOMAIN/tm/orders -
Additional documentation regarding the REST APIs can be found at learn.transportation.trimble.com under “The ART Server Admin Guide”.
-
- When will the existing APIs no longer be accessible?
-
Starting on July 16th, 2021 the TM4Web REST APIs will enter the sunset phase. The alternative TruckMate REST APIs are already a fully equivalent alternative. The sunset phase will last until the end of 2022 Q1 (March 31, 2022) and after this time the TM4Web REST APIs will no longer be enhanced and bug fixes are not guaranteed and therefore should not be relied on.
- What type of support will I have for my existing APIs?
-
All enhancements will be added to the the TruckMate API web service. Bug fixes for the Freight Search API, TM4Web SOAP, and TM4WEb REST API will no longer be supported after March 31, 2022.
- Will this affect my license and billing?
-
-
TM4WEB Client customers licensed for TM4Web API web service will be able to access the same functionality using their existing license (61140) with no additional cost.
-
For an added bonus at no cost to you, additional features are already available in the enhanced TruckMate REST API and more will be added in future releases. To access these features please contact TruckMate support to request the 69000 TruckMate REST API license.
Note: This update offer is only available to TM4Web client customers.
-
APIs
Since the initial introduction in TruckMate 19.4, the TruckMate REST API endpoints and methods continue to be added, refined and streamlined in TruckMate 21.3. More endpoints will continue to be added and refined in future releases.
If you are interested in using the TruckMate REST APIs, it is strongly recommended that you upgrade directly to the latest version of TruckMate (i.e., 21.3) instead of an earlier release to take advantage of the most current, improved and expanded set of API methods and endpoints.
If you are in the early stages of implementing REST APIs and do not have an ART Server running yet, a snapshot of the swagger JSON information is available as a reference web site available on the Trimble Transportation Learning Center.
You can also find a getting started document, TM4Web APIs Getting Started Guide, and a sample collection of TM4Web API requests to use as reference examples.
The TM4Web API Documentation web site link available on the Learning Center provides the swagger.JSON file information.
New features
The following methods and endpoints were either revised or added to the TruckMate REST API service in the TruckMate 2021.3 release.
Additions and revisions to TruckMate REST API service > Orders
These API requests were added to the orders path endpoint in TruckMate 2021.3.
| POST | /orders/{orderId}/details/{orderDetailId}/barcodes |
|---|---|
POST |
/orders/{orderId}/details/{orderDetailId}/barcodes/{barcodeId} |
These API requests were replaced (renamed) from TruckMate 2021.2 to 2021.3.
| Version | Method | Endpoint |
|---|---|---|
2021.2 |
GET |
/orders/{orderId}/osds/{osdDtlId} |
2021.2 |
PUT |
/orders/{orderId}/osds/{osdDtlId} |
2021.2 |
DELETE |
/orders/{orderId}/osds/{osdDtlId} |
replaced by: |
||
2021.3 |
GET |
/orders/{orderId}/osds/{osdId} |
2021.3 |
PUT |
/orders/{orderId}/osds/{osdId} |
2021.3 |
DELETE |
/orders/{orderId}/osds/{osdId} |
---------------------------------------- |
||
2021.2 |
GET |
/orders/{orderId}/barcodes |
replaced by: |
||
2021.3 |
GET |
/orders/{orderId}/details/{orderDetailId}/barcodes |
2021.3 |
GET |
/orders/{orderId}/details/{orderDetailId}/barcodes/{barcodeId} |
Additions and revisions to TruckMate REST API service > Trips
These API requests were added to the trips path endpoint in TruckMate 2021.3.
| PUT | /trips/{tripNumber}/seals/{sealId} |
|---|---|
DELETE |
/trips/{tripNumber}/seals/{sealId} |
GET |
/trips/{tripNumber}/carriers |
GET |
/trips/{tripNumber}/orders/{orderId}/contacts |
GET |
/trips/{tripNumber}/orders/{orderId}/consignee |
GET |
/trips/{tripNumber}/orders/{orderId}/barcodes |
POST |
/trips/{tripNumber}/orders/{orderId}/details/{orderDetailId}/barcodes |
The following API requests were replaced (renamed) in TruckMate 2021.3.
| Version | Method | Endpoint |
|---|---|---|
2021.2 |
GET |
/trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId} |
2021.2 |
PUT |
/trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId} |
2021.2 |
DELETE |
/trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId} |
replaced by: |
||
2021.3 |
GET |
/trips/{tripNumber}/orders/{orderId}/osds/{osdId} |
2021.3 |
PUT |
/trips/{tripNumber}/orders/{orderId}/osds/{osdId} |
2021.3 |
DELETE |
/trips/{tripNumber}/orders/{orderId}/osds/{osdId} |
General bug fixes
All osdDtlId endpoints renamed to osdId (TM-140224)
TruckMate 2021.3 has updated the osd endpoints to reflect the standard naming conventions so osdDtlId was replaced with osdId.
Orders
-
GET /orders/{orderId}/osdsosdDtlId}
-
PUT /orders/{orderId}/osds/{osdDtlId}
-
DELETE /orders/{orderId}/osds/{osdDtlId}
replaced by:
-
GET /orders/{orderId}/osds/{osdId}
-
PUT /orders/{orderId}/osds/{osdId}
-
DELETE /orders/{orderId}/osds/{osdId}
Trips
-
GET /trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId}
-
PUT /trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId}
-
DELETE /trips/{tripNumber}/orders/{orderId}/osds/{osdDtlId}
replaced by:
-
GET /trips/{tripNumber}/orders/{orderId}/osds/{osdId}
-
PUT /trips/{tripNumber}/orders/{orderId}/osds/{osdId}
-
DELETE /trips/{tripNumber}/orders/{orderId}/osds/{osdId}}
REST API: inserting and updating barcode details (TM-155860)
Several new REST API endpoints will be created to support the creation (POST), retrieval (GET), updating (PUT) and removal (DELETE) of barcode information in TruckMate from external sources.
-
Insert barcodes
-
POST /orders/{orderId}/details/
-
POST /orders/{orderid}/details/{orderDetailId}/barcodes
-
-
Modify barcodes
-
Get barcodes
-
via expansion
-
GET /orders/{orderId}?expand=details/barcodes
-
GET /orders/{orderId}/details/{orderDetailId}?expand=barcodes
-
-
direct lookup
-
GET /orders/{orderId}/details/{orderDetailId}/barcodes
-
GET /orders/{orderId}/details/{orderDetailId}/barcodes/{barcodeId}
-
GET /trips/{tripNumber}/orders/{orderId}/details/{orderDetailId}/barcodes
-
GET /trips/{tripNumber}/orders/{orderId}/details/{orderDetailId}/barcodes/{barcodeId}
-
-
TruckMate REST API: Inserting and updating trailer seal details (TM-155861)
The Truckmate REST API service POST and PUT methods for the trips endpoint now allows an external system to add and u[date] seal information to an existing TruckMate trip within the TruckMate trip’s details.
The DELETE method allows for an external system to remove seal number information from a TruckMate trip.
A new Allow Deletion of Trip Seal Numbers security option was added to the Security > Business Events > Misc > Multi Mode / Dispatch tab to control whether the API is able to delete Seal Numbers.
Consistent errorCodes when updating aChargeId (TM-156605)
The errorCodes and errorTexts are now consistent between orders and pickup requests (PUR) in the /tm and /tm4web services when updating an aChargeId on an order that has not been posted.
ART Server - Irrelevant query parameters and data removed (TM-156721)
Query parameters such as offset, limit, sort, filter, href have been removed from all POST/PUT/Delete method responses. Previously some endpoints were generating the responses with some of these parameters which are irrevant for these methods.
TruckMate REST API bug fixes
Request body validation when updating an order OSD (TM-155598)
Added request body validation for specific fields when updating an osdId and also when creating order OSD (over, shortage and damaged) entries in the /tm and /tm4web REST API services.
Order contact now includes shipper.zone (TM-156827)
The shipper.zone and shipper.zoneDescription have been added to the response body for a number of TruckMate REST API endpoints to allow the startZone to be updated through the shipper.zone.
Resolved an error where startZone could not be updated through shipper.zone.
-
GET: /orders
-
POST: /orders
-
GET: /orders/:orderId
-
PUT: /orders/:orderId
-
GET: /orders/:orderId/caller
-
GET: /orders/:orderId/shipper
-
GET: /orders/:orderId/consignee
-
GET: /orders/:orderId/otherContact
-
GET: /orders/:orderId/careOf
-
GET: /orders/:orderId/pickupAt
If the startZone and shipper.zone both are sent in the request body, the startZone will take precedence.
Update consignee.zone through an order (TM-156830)
Both the startZone and endZone can now be updated correctly through consignee.zone and shipper.zone and an API request like PUT: /orders/:orderId is able to update the consign.zone.
POST /orders/order_id/osds updates all fields (TM-156911)
An issue that prevented reportedDate, quantityUnits, and description fields from updating when performing a POST to orders/orderId/osds has been resolved.
GET /tm/trips/:tripNumber/carriers - DB2 Error (TM-157132)
Resolved an issue where the GET trip carriers request would return a DB2 error.
Include drivers where Active Dispatch is False and Active Driver pay is True (TM-157963)
The TruckMate Imaging REST API > GET /drivers endpoints have been modified to include drivers who are not active in dispatch so that you can pick up drivers where 'Active (in) Dispatch' is False but 'Active (in) Driver Pay' is True.
PUT /orders/orderId/aCharges/aChargeId - string quantity 500 errorCode (TM-158092)
Resolved an issue that occurred when a string was placed in the quantity field when updating an aChargeId. It has been correctly updated to a 400 errorCode and with more specific errorText.
POST /Orders response body (TM-158530)
The offset and limit query parameters were removed from POST /orders within the openAPI.JSON documentation and the orderId was added for each order to the POST /orders response body for consistency between the API Document and the API responses.
POST > osds endpoints updated (TM-159021)
-
POST /orders/orderId/osds issues
The ability to POST OSDS records through the /orders endpoint was removed. Now you are required to POST an OSDS record through /orders/orderId/osds.