Realised Trips Push

Introduction

Simacans Control Tower can push its realisation data and all its updates via HTTP POST method to your platforms HTTPS endpoint. We call this the Realised Trips 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 all completed trip details. 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. On the next pages we will go into detail on all fields.

Trip details available after completion of trip and they are available for four days. 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).

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
  • Trip updates like comments, planning updates and manual sign-offs will trigger resending the realised trip
  • Be ready for peak consumption

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. See our previous documentation.

OTM5.0

The version we currently have documented on this developer portal for Realised Trips

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