Core - Transportation Requests
==============================
.. Last update: 04/04/2022

Once all data from the user has been gathered (i.e. pick-up and drop-off places and times,
ad-hoc filters) the User Agent can submit a Transportation Request on behalf of the user.

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 </openapi/srv-core/api-src-WebMobile.json>`.

Submit a new Transportation Request
-----------------------------------

.. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/transportation-requests

The request body should be like this::

  {
    StartLocationQuery: "Milan",                   // String
    StartTime: "2001-01-01T01:01:01Z",             // DateTime
    EndLocationQuery: "51.5073509,-0.1277583",     // String
    EndTime: "2001-01-01T02:01:01Z",               // DateTime
    "Filters":{"vg-category":"[1,4,7,10,18]"}      // String (JSON Dictionary)
  }

The User Agent must pass the location queries as either a searchable zone name (or part of name),
or a pair of Latitude,Longitude coordinates as decimal degree numbers with dot as decimal
separator and comma as pair separator.

The platform will automatically search for a zone that contains the GPS point or that contains
the search query in the name, address or description.

It is up to the User Agent to provide a list of zones, if appropriate, for the user to select
from.

The ``Filters`` element is a dictionary, where the key is the ``Key`` element from the filter,
and the value is a string formatted as per instructions at the paragraph about getting the list
of filters.
  
When the Transportation Request is successfully received by the server, the response is a
positive response with a Guid as ``Data`` to be used for retrieving proposed Movement Authorities.

If the Transportation Request cannot be received, the response message will be one of these:

``err_InvalidUserProfile``
  The current user is not allowed to make a reservation.
  
``err_MaxActiveAuthority``
  The user has already reached the maximum number of active reservation, as defined in the :ref:`configuration variable<configuration-core>` ``MAX_ACTIVE_MA``
  
``err_DrivingLicenseExpired``
  This error message code means that the driving license is expired, or will be expired by the time the reservation can start.

``err_InvalidStartDate``
  The pick-up date is invalid or in the past.

``err_InvalidEndDate``
  The drop-off date is invalid or earlier than the pick-up date.

``err_MissingRequiredFilter``
  Uploaded data is missing some required filters.

``err_NoResourceGroup``
  The user is not allowed to access any vehicle groups. This issue must be resolved by
  a platform operator or administrator.