Planningshub Push

Introduction

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.

What we need from you

First 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 or OAuth2. Next deliver us, the following details:

For Basic Access Authentication

  • HTTPS URL of your endpoint
    • We only support TLS 1.2 for now
    • We accept self-signed server certificates as well as client certificates
  • HTTP Method
    • Preferably POST
  • Username & password for your endpoint
    • Any form of two HTTP headers, like Basic Auth
    • Any other form of authorization that can be configured using a custom header
    • At least we expect a 200 response

For OAuth2

  • URL for your OAuth2 Authorization url
    • We support password grant or client credentials grant
    • We support public and confidential clients
    • For confidential clients, client credentials can be sent using a (Basic) authorization header or as part of the request body using the "client_secret" field.
  • HTTPS URL of your endpoint
    • We only support TLS 1.2 for now
    • We accept self-signed server certificates as well as client certificates
  • HTTP Method
    • Preferably POST

What we will deliver to you

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).

What is included

Trip planning data will contain planned trip, stop, drop, leg, vehicle and location data. eCMR references are included in the v5extension.

What is not included

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.

Technical notes

  • 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
  • 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

OTM versions

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.

v5b1

Deprecated version

OTM5.0

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)
e-CMR extension

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.