# 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](/docs/data-export/overview).

## 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](/docs/otm5/otm5-trip-profile).

See also the [planning push](/docs/data-export/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](https://realized-trip-to-otm-service.services.simacan.com/api/v5).

### Lifecycles

As explained in the general [lifecycle
page](/docs/otm5/otm5-overview#lifecycles) 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:


```md
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


```md
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


```json
{
    "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"
       }
    ]
 }
```