Core - Movement Authorities =========================== .. Last update: 22/11/2021 Movement Authorities represent the trip reservations; the system can propose many items, and the user can confirm some of them. The base url for the APIs in this page is at:: /api/mobile/ A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded :download:`here `. Asking for proposals -------------------- Once a Transportation Request has been successfully posted, the User Agent receives the Guid of the entity. With this, the User Agent can ask for the proposed Movement Authorities that can fulfill the request. Such a request produces a **streaming response** of JSON arrays. There are 15 update events in total, one per second. The arrays are separated by a newline character. It is up to the User Agent to handle the streaming. Each array contains the Movement Authority proposals that have arrived until the moment the array was issued, so every update event supersedes the previous ones. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/movement-authorities/{tr} An example of the stream of responses may look like this:: [] /* then the channel remains silent for 1 second */ [] /* then the channel remains silent for 1 second */ [] /* then the channel remains silent for 1 second */ [{ "Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid "TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid "OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String "OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid "LastUpdated": "2020-09-01T09:21:32Z", // DateTime "IsConfirmed": false, // Boolean "IsReadyToStart": false, // Boolean "DeletionDate": null, // DateTime (nullable) "StartTime": "2020-09-01T09:31:29Z", // DateTime "EndTime": "2020-09-01T09:51:29Z", // DateTime "MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime "MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime "MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime "EquipmentReference": null, // String (nullable) "ServiceReference": null, // String (nullable) "StartLocationName": "Milan", // String "StartLocationAddress": "Piazza Duomo, 1", // String "StartLocationLatitude": 45.46018980653452, // Double (nullable) "StartLocationLongitude": 12.21862968891009, // Double (nullable) "EndLocationName": "Milan", // String "EndLocationAddress": "Piazza Duomo, 1", // String "EndLocationLatitude": 45.46018980653452, // Double (nullable) "EndLocationLongitude": 12.21862968891009, // Double (nullable) "MaxTripCount": 1, // Int "RemainingTripCount": 1, // Int "Details": null, // Object array (nullable) "EstimatedCost": "10 - 20" // String (nullable) }, ... ] In this response example JSON data is formatted for clarity, but in the actual data stream there are no newlines inside JSON objects. The newline character is used to separate the streaming event data. The User Agent should start this long-running request as soon as it receives the Guid after a successful Transportation Request submission. As soon as some data is received, the User Agent is expected to present and update a list of processed Movement Authority proposals for the user to choose from. The streaming is composed of 15 events 1 second apart; as soon as the user selects and chooses to confirm a proposal the User Agent can close the connection and/or ignore further events. The value of the ``OriginatorKey`` property of the authority's details can be one of the value described in :ref:`details-movementauthority`. Confirm a proposal ------------------ .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/movement-authorities/confirm/{ma} As soon as the user decides to confirm one of the proposed Movement Authorities retrieved by the User Agent with the above-mentioned streaming updates request, the User Agent should post this confirmation. This action will produce a confirmed Movement Authority, otherwise known as a reservation. List all confirmed ------------------ Retrieves the list of all the confirmed and not revoked user's reservation with trip yet to be started or closed within a time range defined by the :ref:`configuration variable` ``MAX_MA_HISTORY_USER_DAYS``) .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/movement-authorities/list Response example:: [ { "Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid "TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid "OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String "OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid "LastUpdated": "2020-09-01T09:21:32Z", // DateTime "IsConfirmed": false, // Boolean "IsReadyToStart": false, // Boolean "DeletionDate": null, // DateTime (nullable) "StartTime": "2020-09-01T09:31:29Z", // DateTime "EndTime": "2020-09-01T09:51:29Z", // DateTime "MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime "MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime "MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime "EquipmentReference": null, // String (nullable) "ServiceReference": null, // String (nullable) "StartLocationName": "Milan", // String "StartLocationAddress": "Piazza Duomo, 1", // String "StartLocationLatitude": 45.46018980653452, // Double (nullable) "StartLocationLongitude": 12.21862968891009, // Double (nullable) "EndLocationName": "Milan", // String "EndLocationAddress": "Piazza Duomo, 1", // String "EndLocationLatitude": 45.46018980653452, // Double (nullable) "EndLocationLongitude": 12.21862968891009, // Double (nullable) "MaxTripCount": 1, // Int "RemainingTripCount": 1, // Int "Details": [ { "Guid": "8668be9e-42c0-4af2-878a-64823081c90b", // Guid "DeletionDate": null, // DateTime (nullable) "OriginatorKey": "ma-vehicle-license-plate", // String "Labels": "", // String "ValueLabels": "", // String "Value": "AA000XX", // String "ValueType": 2 // Int (enum) }, ... ], "EstimatedCost": "10 - 20" // String (nullable) }, ... ] The implementing User Agent is expected to periodically ask the server about confirmed Movement Authorities and update a local list accordingly (i.e. keeping track of deletion and/or other updates). In particular, the platform updates the ``Details`` property with vehicle data as soon as the start time approaches, so the User Agent can present this data to the user (i.e. the license plate, or the sticker number). This list can be presented to the user as a list of vehicle reservations. Care must be taken to present expired reservations with appropriate indication; also, revoked reservations (i.e. those with a non-null ``DeletionDate``) must be appropriately presented. The value of the ``OriginatorKey`` property of the authority's details can be one of the value described in :ref:`details-movementauthority`. List all open reservations -------------------------- Retrieves the list of all the confirmed and not revoked user's reservation with trip yet to be started .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/movement-authorities/open-authorities Response example:: [ { "Guid": "0fe98b13-7864-47f8-bb02-aac86e480e2d", // Guid "TransportRequest": "0f09ab29-3c56-4f0e-807b-20b62dd0e668", // Guid "OriginatorKey": "c8f0ff575299ba1a7cd414f46b882e4a20b13b7eb45babd9b33871523b1eb395", // String "OriginatorModule": "32b297a5-8180-420f-9482-84bfc7f55efe", // Guid "LastUpdated": "2020-09-01T09:21:32Z", // DateTime "IsConfirmed": false, // Boolean "IsReadyToStart": false, // Boolean "DeletionDate": null, // DateTime (nullable) "StartTime": "2020-09-01T09:31:29Z", // DateTime "EndTime": "2020-09-01T09:51:29Z", // DateTime "MinValidStartTime": "2020-09-01T09:21:31Z", // DateTime "MaxValidStartTime": "2020-09-01T09:46:29Z", // DateTime "MaxValidEndTime": "2020-09-01T10:21:29Z", // DateTime "EquipmentReference": null, // String (nullable) "ServiceReference": null, // String (nullable) "StartLocationName": "Milan", // String "StartLocationAddress": "Piazza Duomo, 1", // String "StartLocationLatitude": 45.46018980653452, // Double (nullable) "StartLocationLongitude": 12.21862968891009, // Double (nullable) "EndLocationName": "Milan", // String "EndLocationAddress": "Piazza Duomo, 1", // String "EndLocationLatitude": 45.46018980653452, // Double (nullable) "EndLocationLongitude": 12.21862968891009, // Double (nullable) "MaxTripCount": 1, // Int "RemainingTripCount": 1, // Int "Details": [ { "Guid": "8668be9e-42c0-4af2-878a-64823081c90b", // Guid "DeletionDate": null, // DateTime (nullable) "OriginatorKey": "ma-vehicle-license-plate", // String "Labels": "", // String "ValueLabels": "", // String "Value": "AA000XX", // String "ValueType": 2 // Int (enum) }, ... ], "EstimatedCost": "10 - 20" // String (nullable) }, ... ] The value of the ``OriginatorKey`` property of the authority's details can be one of the value described in :ref:`details-movementauthority`. Revocation ---------- Revokes a confirmed movement authority: .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/movement-authorities/revoke/{ma} The API does not need a request body, and it may respond with a plain error response if the movement authority has not been found for the user, or is not confirmed, or with one of the following error: ``err_CannotRevoke`` The requested was either already revoked, expired or with an opened trip