TruckMate 2022.2 New Features: Web / APIs

Several endpoints have been removed from the TruckMate REST API (/tm) service to the new Master Data (/masterData) service. These endpoints are related to background TruckMate configuration and are better handled by the new service. These include:

OData advanced filtering is supported in the masterData query endpoints for:

OData (Open Data Protocol) is an OASIS (Organization for the Advancement of Structured Information Standards) standard that defines the best practice for building and consuming RESTful APIs.

Deprecated fields in status/statushistory can now be set to NULL. This includes:

When a /tm API query includes an email property in the request body, the entered value is now validated to confirm it has the specified email format.

The errorText and errorCode fields in the ART error response schema have been deprecated and replaced with a new ARTError schema.

A consistent formal schema was added to all the 4xx (Client error) response codes.

The domain portion of the URL has been removed from the href value in the response body and error descriptions for 404 failure code responses. When a request is forwarded from a different server, the domain is different and not relevant.

For example:

"href": "https://artserver01.companyname.net:9999/tm/orders?expand=details"

vs

"href": "/orders?expand=details"

The error response format related for tm/trips and its endpoints have been updated for consistency. This includes pre-check validation against the openAPI document.

A proper 400 error code and description is returned if an invalid trip or order number is sent in the request.

Several updates to the error response format were made throughout the /tm/trips and tm/orders endpoints for consistency. This includes the error responses in the tm/Orders API for these endpoints:

Also, the 4xx endpoints for orders/dangerousGoods now uses the correct error format, code and description.

The '$select` oData query parameter was added to the GET tm/orders endpoint. This allows you to limit the response body to the fields included in the select query parameter.

The GET /tm/orders endpoint provides faster responses.

A new isApproved body parameter was added to the tm/orders and tm/orders/{orderId} endpoints for the POST, PUT and GET methods.

This parameter value must be True for a quote to generate freight bills. It is affected by the 'CSERVE.EXE > Approve Quotes’app config which can set this value to True automatically when quotes are created.

Now you can cancel a rate quote using the PUT tm/orders/orderId/status?type=Q method.

These capabilities have also been added for adding, editing and deleting information in order rate quotes (type=Q):

Now you can filter orders based on the orderInterlinerId using the standard OData (Open Data Protocol) query options. For example:

The proBill field was added to the interliner responseBody for:

The movementType field was added to the interliner properties included in the response returned by:

The proBill and movementType fields were added to the interliners endpoint for:

The dateTime values coming into and being returned by the APIS is now in the ISO 8601 format. For example:

Unused schema definitions were removed from the TruckMate REST API /tm service.

The limit and offset query parameters are now defined as integers. The default values are set to limit=20 and offset=0.

Proper JSON is now returned in the response body for the 5xx errors.

The APIs now allow you to retrieve reports with linked parameters.

New rules and error messages are used when a trip-based TL or a LTL status change is applied to a trip using a status code with a cancellation behavior.

The correct string format is now used for the costAllocationRule field when the carriers section in 'GET tm/trips' is expanded.

If the max length of 80 characters is exceeded when using 'POST trips/{tripNumber}/carriers', a 400 invalidstring error message is displayed instead of just cutting off the text.

If the max length of 10 characters is exceeded when using 'POST /trips/{tripNumber}/positions', a 400 invalidstring error message is displayed instead of a 500 Internal Server Error.

The description and request body schema has been updated to match the endpoint behavior for POST /trips/{tripNumber}/carriers/{loadSummaryId}/aCharges.

The currency code value is now reliably set to the correct value when assigning a carrier to a trip.

The limit and offset query parameters were removed from the /stops endpoints.

Trips are no longer cancelled when you are using the DELETE /trips/{tripNumber}/orders method and a 4xx (bad request) response code is received. The trip and orders will remain unchanged.

The 'stopType' property is now consistently defined in the schema as an Enum field.

P&D trips with a pickup at the terminal and a drop at the consignee end zone correctly creates the drop as a drop. Previously, it was creating the drop as an intermediate stop.

Only one status code defined in Codes Maintenance can have the 'Default When Planning Incomplete' additional rule option selected. This improves the underlying business logic when using the tm/trips API to create trips. Specifically, scenarios where incomplete or partially created (one or more resources could not be matched) trips are being created. One status code will be applied consistently in this case.

The PUT tripNumber/status endpoint returns the correct status code now. Previously, there were situations where the response was not waiting for the request to finish processing and returned the wrong status code.

The PUT /trips/tripNumber/carriers/loadSummaryId/aCharges/carrierAChargeId uses the same logic as the POST method now. This ensures the accessorial charge amount is calculated correctly.

Previously, POST /orders was incorrectly returning a 400 error code for valid aChargeCode entries. This has been fixed.

The actualPickup and actualDelivery fields were removed from the request body schema for POST /orders. These values are not entered during order creation.

When using POST /orders/orderId/details/orderDetailId/barcodes, these two barcode properties are now validated to ensure they only contain True or False. * intact * pieceCubing

The isVerified property was removed from the endpoint request.

The zone property for order status updates using PUT /orders/{orderId}/status was changed from a required property to a conditionally required property.

The response properties returned by GET /orders and GET /orders/orderId are now consistent for each of the T, P and Q order types.

Previously, there were some cases where the PUT /orders/orderId was incorrectly deleting customDefs entries. This has been was fixed. Also, the customLabel property was removed from the PUT /orders/{orderId}/customDefs/{customDefId} request.

The oData IN operator can now be used for filtering orders.

Previously, a SQL error message was being returned when GET /orders included traceType or traceNumbers parameters. This has been fixed.