Simacans Control Tower can push its known planning and all its updates via HTTP POST method to your platforms HTTPS endpoint. We call this the planningshub push service. Using this service you can process our data into your own, or partner platform. Updates are real-time. Once you've set up this push service, no further manual action required.
First of all you need to set up an endpoint where we can POST our data to. To be safe, please secure your endpoint with basic access authentication. Next deliver us, the following details:
- HTTPS URL of your endpoint (with TLS 1.2 or higher encryption)
- Username & password for your endpoint
- HTTP Method (preferably POST)
Once we have the correct details of your endpoint, we can start sending you planning data. Our data will be in JSON hierarchical structure. Keep in mind that almost all fields are optional, so every trip can have its own combination of objects.
All updates are sequential, they will always been sent to you in the order of which updates were made. Even if the connection was lost for whatever reason, we will still send you all updates, so that you get a complete picture of the changes and how they were made (within a time frame of less than 96 hours).
Trip planning data will contain planned trip, stop, drop, leg, vehicle and location data. eCMR references are included in the v5extension.
Data which is enriched along the way, like the eCMR status, vehicle location update metadata, realised or estimated times, operationally made comments as can be seen in Control Tower. Our updates will always contain the complete state of the planning.
- We will use the OTM5 standard, however, most fields are optional. So what you receive can be different per trip.
- An individual message will always contain a single trip
- An individual message can be up to 128kb in size
- A trip likely gets updates, due to f.i. vehicle couplings, added remarks, or stop mutations, so this can be tens of updates
- Be ready for peak consumption (most plannings are prepared in bulk, which we will send in rapid sequence)
- Updates can still be pushed after a trip has been finished
Since we started this development with OTM still in beta, we included versioning from the start. A major but breaking improvement can be offered as a version on-the-side, so that -if needed- you can upgrade on your own timeline.
The version we currently have documented on this developer portal for Planningshub push.
- Shipment has been replaced by TransportOrder, Consignment & Goods. A TransportOrder is a group of Consignments that belong together. A Consignment is an administrative entity that models something that needs to be shipped. The Goods are the actual physical things being shipped, with dimensions, weight, quantity, etc. Goods fall into two groups: items or transportEquipment
- Lifecycles are removed from times and added to actions. All times in actions have a startTime and endTime (instead of time, arrival/departure)
- Remarks has been renamed to remark, since it is a single string value
- More keys for ContactDetails for an actor (VATCode, GLN ID, IBAN)
The e-CMR extension is an extension of our OTM5.0 profile. It adds freight-documents to the messages. This extension has been developed in-house by Simacan and is not offical part of the OTM specification yet.