Streamed Statuses offer a way of quickly finding out about status changes of your shipments. No need to fetch with a getStatus call; we will deliver the data to you by a streaming push mechanism. You can subscribe to events and when an update occurs, we will post status data to the URL you specify in MyTranssmart in menu Manage account > Streamed Statuses.
First step is to reach out to our support department to activate it for you. We will first activate it on our Accept environment so you can configure and test the integration. When it's successful we will activate it on Production.
Setup
First, make sure you have an authenticated endpoint that can receive status updates.
Next, is enabling and completing the configuration in the setup page.
- URL = your endpoint
- Authentication = choose between None, Header or Basic depending on your own choice of configuration.
- Status push method = choose between Package level (default) or Shipment level. See explanation below
Important note: (please also read the update of December 2024 below)
In your mapping, make sure to read the status value from the field genericStatusCode in the shipmentLines and not from the shipmentStatus in the shipment header. The reason is that for some carriers we don't receive the status update on the shipment header level and by an algoritm we change the status on the shipment header level after checking the status per shipment line.
Example:
A shipment has 3 lines:
Line 1: package with status DONE
Line 2: package with status TRNS
Line 3: package with status TRNS
The shipment header status is TRNS
We receive the status update of package line 2 which changes to DONE. Because there is still a package with status TRNS in line 3, the algoritm doesn't change the shipment header status, so it stays TRNS.
We receive the status update of package line 3 which changes to DONE. Because there are no more packages with status TRNS, the algoritm changes the shipment header status to DONE. But, at the moment we received the status update, we already pushed the status message to your endpoint. At that moment, the field shipmentStatus in the header was still TRNS, while the genericStatusCode in the shipmentLine was status DONE. If you would map to the shipment header status, the shipment will stay on TRNS in your system instead of changing to DONE. So, therefor it's important to map to the status value from the field genericStatusCode in the shipmentLines.
Update: in December 2024 we have added a setting to decide if the message we push should be triggered by the package lines or the shipment header.
The default setting is still per package line. If you wish to change it to shipment header, change the setting. You will need to this if you're unable to map to the genericStatusCode field in the shipmentLines.
The new setting is available on the configuration page in Manage account > Streamed Statuses
Message format
The payload sent in the status notification is the same as the response to status retrieval requests, chapter 5.1 of our DevDocs: https://devdocs.transsmart.com/#_5_2_status_stream
isIncremental
The parameter isIncremental which is used in the Status Retrieval API endpoints is not affected by the messages that are pushed by our system. If you still wish to pull status requests to your own system, or maybe a second system, that is still possible.
Sub accounts
If you have a configuration with one main account and one or more sub accounts, it depends on the endpoint configuration how to set it up. If you have one endpoint where you want to receive all status messages of all accounts, it's enough to only configure it on the main account. The setting will automatically be inherited to all sub accounts.
If you have a different endpoint per sub account, you can configure it per sub account.