Realized Trip 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.
The goal of this page is to explain the structure of the OTM5 messages that are shared using the realized-push. For further information on how to initiate a connection see the overview page.
Note that this pages replaces the outdated, but still supported older realization push.
What is not included
Data which is enriched along the way, like the eCMR status, vehicle location, estimated times, operationally made comments as can be seen in Control Tower.
Message Structure
The messages in the planning push follow the OTM5 Trip Profile.
See also the planning push since it uses the same data. It only adds more data regarding realized delivery times & optionally proof of deliveries.
The exact OpenAPI specification can be found here.
Lifecycles
As explained in the general lifecycle page lifecycles are added to actions to indicate whether the action is planned to happen, projected to happen (ETAs) or did actually happen (realized). Since the realized trip push is mostly used for analysing the planned vs the realized times & whether the planning was realisatic or needs improvements for next iterations, the realized trip push includes both the planned and realized actions.
As a result the general (action) structure looks like this:
trip
actions
stop
id = 1
lifecycle = planned
start/end time
other fields..
stop
id = 1
lifecycle = realized
start/end time (potentially different)
other fields..
move
lifecycle = planned (we do not track realized moves within Simacan)
stop
id = 2
... etc.Every stop occurs thus twice in each trip, once for the planned lifecycle and once for the realized lifecycle.
Proof of Deliveries
Some parties also explicitely track that consignments have been delivered by providing a document such as a photo. The handover looks as follows
HandOver
uuid
externalAttributes
status (optional): whether the consignment was delivered, delivered at the
neigbours, or not delivered
message (optional): accompanying message with the status about how or why
remark (optional): any additional remarks about the proof of delivery
time
consignment
documents (optional): pointing towards an online photo document showing the
consignment was delivered.Full Message Example
{
"id": "9e376f56-5ecd-733e-83c4-124297f0f398",
"name": "Trip 1234",
"externalAttributes": {
"customer_data_standPlaats": "Hendrik-Ido-Ambacht (Plus)",
"tripId": "trip-1234"
},
"creationDate": "2022-09-13T09:45:22.019Z",
"vehicle": {
"entity": {
"id": "22f2ddb1-4d51-39ed-91de-89170ede0697",
"vehicleType": "truck",
"fuel": "EURO_6_DIESEL",
"licensePlate": "ZZZ-666"
},
"associationType": "inline"
},
"actors": [
{
"entity": {
"id": "04fda035-c5a9-5d98-b2f4-fef915fbfb89",
"name": "Carrier",
"externalAttributes": {
"externalId": "carrier_bv"
}
},
"roles": [ "carrier" ],
"associationType": "inline"
},
{
"entity": {
"id": "9c96409a-03a1-5675-a362-6238bdb7b6f1",
"name": "Shipper & Co",
"externalAttributes": {
"externalId": "shipper_and_co"
}
},
"roles": [ "shipper" ],
"associationType": "inline"
},
{
"entity": {
"id": "85cf6415-29e2-3250-a8c6-888c563e954e",
"name": "Elvis Presley"
},
"roles": [ "driver" ],
"associationType": "inline"
}
],
"actions": [
{
"entity": {
"id": "60aee7f6-3f01-588e-9021-baa6c018d92d",
"name": "1",
"externalAttributes": {
"customer_data_mutated": "false",
"stopId": "20874316"
},
"lifecycle": "planned",
"sequenceNr": 1,
"location": {
"entity": {
"id": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"name": "PLUS Retail West",
"externalAttributes": {
"locationId": "158775415"
},
"geoReference": {
"lat": 51.84697,
"lon": 4.65331,
"type": "latLonPointGeoReference"
},
"administrativeReference": {
"name": "Location Display name",
"street": "street",
"postalCode": "1234AB",
"city": "Amsterdam",
"country": "NL"
}
},
"associationType": "inline"
},
"startTime": "2022-09-13T06:21:00Z",
"endTime": "2022-09-13T07:20:00Z",
"actions": [
{
"entity": {
"id": "60025719-7255-3089-8210-0f62a1b3b39a",
"lifecycle": "planned",
"transportEquipment": {
"entity": {
"id": "ce636013-32fc-31bb-baa1-66cad70dab4d",
"equipmentType": "trailer",
"equipmentSubType": "EURO_13_60",
"licensePlate": "AA-BB-CC"
},
"associationType": "inline"
},
"actionType": "attachTransportEquipment"
},
"associationType": "inline"
},
{
"entity": {
"id": "623dbba9-6e38-454a-88ac-be04a22c8e25",
"lifecycle": "planned",
"consignment": {
"entity": {
"id": "b711847c-96d7-db34-843d-6bbba8af513e",
"externalAttributes": {
"orderId": "12308478",
"orderReference": "DC50032676",
"trackTraceCode": "20874316"
},
"type": "OVERIG",
"goods": [
{
"entity": {
"id": "7b19aab9-7fba-3149-ac6b-5cadceb8c64a",
"description": "EUR",
"quantity": 12,
"equipmentType": "loadCarrier",
"type": "transportEquipment"
},
"associationType": "inline"
}
],
"actors": [
{
"entity": {
"id": "6cf8cac0-3ce5-35ee-8f46-32a4383b1fab",
"name": "Some consignee"
},
"roles": [ "consignee" ],
"associationType": "inline"
},
{
"entity": {
"id": "6cf8cac0-3ce5-35ee-8f46-32a4383b1fab",
"name": "Another Consignor"
},
"roles": [ "consignor" ],
"associationType": "inline"
}
]
},
"associationType": "inline"
},
"startTime": "2022-09-13T06:21:00Z",
"endTime": "2022-09-13T07:20:00Z",
"actionType": "load"
},
"associationType": "inline"
}
],
"constraint": {
"entity": {
"id": "b140e433-6956-30b1-baa0-1bf4632d6267",
"value": {
"startTime": "2022-09-13T06:21:00Z",
"endTime": "2022-09-13T07:20:00Z",
"type": "timeWindowConstraint"
}
},
"associationType": "inline"
},
"actionType": "stop"
},
"associationType": "inline"
},
{
"entity": {
"id": "60aee7f6-3f01-588e-9021-baa6c018d92d",
"name": "1",
"externalAttributes": {
"stopId": "s1"
},
"lifecycle": "realized",
"sequenceNr": 1,
"location": {
"uuid": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"entityType": "location",
"associationType": "reference"
},
"actions": [
{
"entity": {
"id": "60025719-7255-3089-8210-0f62a1b3b39a",
"lifecycle": "realized",
"transportEquipment": {
"entity": {
"id": "ce636013-32fc-31bb-baa1-66cad70dab4d",
"equipmentType": "trailer",
"equipmentSubType": "EURO_13_60",
"licensePlate": "OR-72-BB"
},
"associationType": "inline"
},
"actionType": "attachTransportEquipment"
},
"associationType": "inline"
},
{
"entity": {
"id": "623dbba9-6e38-454a-88ac-be04a22c8e25",
"lifecycle": "realized",
"consignment": {
"entity": {
"id": "b711847c-96d7-db34-843d-6bbba8af513e",
"externalAttributes": {
"orderId": "12308478",
"trackTraceCode": "20874316",
},
"type": "OVERIG",
"goods": [
{
"entity": {
"id": "7b19aab9-7fba-3149-ac6b-5cadceb8c64a",
"description": "EUR",
"quantity": 16,
"equipmentType": "loadCarrier",
"type": "transportEquipment"
},
"associationType": "inline"
}
],
"actors": [
{
"entity": {
"id": "6cf8cac0-3ce5-35ee-8f46-32a4383b1fab",
"name": "Some consignee"
},
"roles": [ "consignee" ],
"associationType": "inline"
},
{
"entity": {
"id": "6cf8cac0-3ce5-35ee-8f46-32a4383b1fab",
"name": "Another Consignor"
},
"roles": [ "consignor" ],
"associationType": "inline"
}
]
},
"associationType": "inline"
},
"startTime": "2022-09-13T06:21:00Z",
"endTime": "2022-09-13T07:20:00Z",
"actionType": "load"
},
"associationType": "inline"
}
],
"constraint": {
"entity": {
"id": "b140e433-6956-30b1-baa0-1bf4632d6267",
"value": {
"startTime": "2022-09-13T06:21:00Z",
"endTime": "2022-09-13T07:20:00Z",
"type": "timeWindowConstraint"
}
},
"associationType": "inline"
},
"actionType": "stop"
},
"associationType": "inline"
},
{
"entity": {
"id": "c9a5a8cc-196b-30e9-be2b-a710eec82462",
"lifecycle": "planned",
"from": {
"uuid": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"entityType": "location",
"associationType": "reference"
},
"to": {
"entity": {
"id": "434bf7d2-ef0b-bc3d-bf30-eafc41153da9",
"name": "Some place",
"externalAttributes": {
"groupingAddressId": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"locationId": "1382390970"
},
"geoReference": {
"lat": 52.12079,
"lon": 5.28407,
"type": "latLonPointGeoReference"
},
"administrativeReference": {
"name": "Another location",
"street": "Neude",
"postalCode": "9999ZZ",
"city": "Utrecht",
"country": "NL"
}
},
"associationType": "inline"
},
"actionType": "move"
},
"associationType": "inline"
},
{
"entity": {
"id": "c9a5a8cc-196b-30e9-be2b-a710eec82462",
"lifecycle": "planned",
"from": {
"uuid": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"entityType": "location",
"associationType": "reference"
},
"to": {
"entity": {
"id": "434bf7d2-ef0b-bc3d-bf30-eafc41153da9",
"name": "Some place",
"externalAttributes": {
"groupingAddressId": "b82cfaf7-38b9-d230-9c81-dacd15624a7d",
"locationId": "1382390970"
},
"geoReference": {
"lat": 52.12079,
"lon": 5.28407,
"type": "latLonPointGeoReference"
},
"administrativeReference": {
"name": "Another location",
"street": "Neude",
"postalCode": "9999ZZ",
"city": "Utrecht",
"country": "NL"
}
},
"associationType": "inline"
},
"actionType": "move"
},
"associationType": "inline"
},
{
"entity": {
"id": "dfea3ae5-b018-51ff-8001-e5cb241caa65",
"name": "2",
"externalAttributes": {
"stopId": "20874317"
},
"lifecycle": "planned",
"sequenceNr": 2,
"location": {
"uuid": "434bf7d2-ef0b-bc3d-bf30-eafc41153da9",
"entityType": "location",
"associationType": "reference"
},
"startTime": "2022-09-13T08:27:03Z",
"endTime": "2022-09-13T09:15:03Z",
"actions": [
{
"entity": {
"id": "b5db4f58-b11d-40e4-8b34-93e30120dc57",
"lifecycle": "planned",
"consignment": {
"entity": {
"id": "57fd1792-3a4f-cd3e-a846-f855a62265b9",
"externalAttributes": {
"plannedStart": "0001-01-01T00:00:00Z",
"externalOrderId": "12308478",
"orderId": "12308478",
"shipmentNumber": "1",
"plannedEnd": "0001-01-01T00:00:00Z",
"cancelled": "false",
"customer_data_orderReference": "DC50032676",
"trackTraceCode": "20874317",
"externalShipmentId": "51542539-b257-3730-88eb-3f9a6c85139d"
},
"type": "OVERIG",
"goods": [
{
"entity": {
"id": "8923eee7-d06a-3210-aa1f-f3b9e87dce40",
"description": "unknown",
"quantity": 29,
"equipmentType": "loadCarrier",
"type": "transportEquipment"
},
"associationType": "inline"
}
]
},
"associationType": "inline"
},
"startTime": "0001-01-01T00:00:00Z",
"endTime": "0001-01-01T00:00:00Z",
"actionType": "unload"
},
"associationType": "inline"
}
],
"constraint": {
"entity": {
"value": {
"startTime": "2022-09-13T08:23:00Z",
"endTime": "2022-09-13T09:11:00Z",
"type": "timeWindowConstraint"
}
},
"associationType": "inline"
},
"actionType": "stop"
},
"associationType": "inline"
},
{
"entity": {
"id": "dfea3ae5-b018-51ff-8001-e5cb241caa65",
"name": "2",
"externalAttributes": {
"stopId": "20874317"
},
"lifecycle": "realized",
"sequenceNr": 2,
"location": {
"uuid": "434bf7d2-ef0b-bc3d-bf30-eafc41153da9",
"entityType": "location",
"associationType": "reference"
},
"actions": [
{
"entity": {
"id": "b5db4f58-b11d-40e4-8b34-93e30120dc57",
"lifecycle": "realized",
"consignment": {
"entity": {
"id": "57fd1792-3a4f-cd3e-a846-f855a62265b9",
"externalAttributes": {
"orderId": "12308478",
"orderReference": "DC50032676",
"trackTraceCode": "20874317"
},
"type": "OVERIG",
"goods": [
{
"entity": {
"id": "8923eee7-d06a-3210-aa1f-f3b9e87dce40",
"description": "EUR",
"quantity": 57,
"equipmentType": "loadCarrier",
"type": "transportEquipment"
},
"associationType": "inline"
}
]
},
"associationType": "inline"
},
"startTime": "0001-01-01T00:00:00Z",
"endTime": "0001-01-01T00:00:00Z",
"actionType": "unload"
},
"associationType": "inline"
}
],
"constraint": {
"entity": {
"value": {
"startTime": "2022-09-13T08:23:00Z",
"endTime": "2022-09-13T09:11:00Z",
"type": "timeWindowConstraint"
}
},
"associationType": "inline"
},
"actionType": "stop"
},
"associationType": "inline"
}
]
}