Core - Transportation Request

Module dedicated to transportation requests.

The base url for the APIs in this page is at:

/api/admin

A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.

Get trasportation request

Gets details about a specific transportation request:

GET /v1/transportation-requests/{id}

Gets details about a specific transportation request

Parameters

id (integer) – The id of the transportation request

Status Codes

200 OK – Success

id: The id of the transportation request (int)

Returns a Json positive response and the the details of the trasportation request:

{
  ID: 123,                                        // Int
  UserID: 345,                                    // Int
  Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid
  UserName: "UserName",                           // String
  FullName: "John Doe",                           // String
  Email: "user@email.com",                        // String
  MobilePhoneNumber: "3349822333",                // String
  StartLocationQuery: "London Gatwick",           // String
  EndLocationQuery: "London Heathrow",            // String
  StartTime: "2001-01-01T01:01:01Z",              // DateTime
  EndTime: "2001-01-01T01:01:01Z",                // DateTime
  ExternalResourceGroups: [ Guid array ]          // Guid Array
}

Returns a plain Json negative response if the ID provided in the request does not correspond to any existing transportation request.

Add transportation request

Posts a new Transportation Request on the system:

POST /v1/transportation-requests

Posts a new Transportation Request on the system

Status Codes

200 OK – Success

With a request body like this:

{
  UserID: 123,                                            // Int
  StartLocationQuery: "London Gatwick",                   // String
  EndLocationQuery: "London Heathrow",                    // String
  StartTime: "2020/01/01 10:00:00",                       // DateTime
  EndTime: "2020/01/01 11:00:00",                         // DateTime
  Filters: [ key: "vg-category", value: [1,4,7,10,18] ]   // JSON Dictionary
}

All fields are required, but the Filters field. Filters is required only if the system have some required ExtResourceFilter.

If the transportation request is added successfully, it will return a Json positive response and the Guid of the new record:

{
  "53155c4a-b2a0-412f-ab41-552d9ccdf784"
}

Possible error messages are:

err_InvalidUser: The user corresponding to the provided ID is either not an end user, has not been confirmed or has been disabled
err_MaxMACountReached: The user has already reached the maximum number of active reservation, as defined in the configuration variable MAX_ACTIVE_MA
err_InvalidStartDate: The start date is either not valid or is in the past
err_InvalidEndDate: The end date is either not valid or is earlier than the start date
err_MissingRequestFilter: Missing required filters
err_NotAdministrable: The logged operator has no rights to manage the selected user
err_NoUserSpecified: No UserID has been provided in the request
err_MissingGroups: There are no resources available to the user
err_InvalidElement: There were unhandled error while adding the new trasportation request

Get filters

Gets the list of current filters for compiling a transportation request:

GET /v1/transportation-requests/filters

Gets the list of current filters for compiling a transportation request

Status Codes

200 OK – Success

Returns a Json positive response and the list of filters:

[
  {
    ID: 1234,                                                                                   // Int
    CreatedDate: "2001-01-01T01:01:01Z",                                                        // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",                                                        // DateTime
    ValueType: 4,                                                                               // Int
    Key: "vg-category",                                                                         // String
    Labels: "{\"en\":\"Category\"}",                                                            // String
    ValidValues: "["9060503a-5ba6-42b4-a01e-cbce1cb98c7e", ...]",                               // String
    ValidValuesLabels: "{\"9060503a-5ba6-42b4-a01e-cbce1cb98c7e\":{\"en\":\"City Car\"}, ...}", // String
    IsRequired: true                                                                            // Boolean
  },
  ...
]

The value of the Key property can be one of the value described in Movement Authority Filters.

The ValidValues field is a stringified array whose value, when present depending on the value of the ValueType field (see below), may vary depending on the context of the specific filter (i.e. it may be a number array, Guid array, string array…).

The field Labels contains a stringified Json containing pairs “language code”:”localized value”

The field ValidValuesLabels also contains a stringified Json, and is valorized only for types Enumeration and Multiple Enumeration

ValueType can be one of the AdditionalValueTypes enumeration, with the following implications:

Value	Implications
Number	In the `ValidValues` there can be a JSON array of two items, the first being the lower bound and the second being the upper bound of the allowed range. A value of null or undefined lets the end unbounded. No `ValidValuesLabels` are to be expected.
Boolean	No `ValidValues` are to be expected, but there can be `ValidValuesLabels`.
String	No `ValidValues` are to be expected, nor `ValidValuesLabels`.
Enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected, as in the example data above. The User Agent must specify exactly one of the valid values in the JSON array contained in `ValidValues` as the filter value when compiling a Transportation Request.
Multi-enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected, as in the example data above. The User Agent must specify at least one, and possibly more, of the valid values in the JSON array contained in `ValidValues` as the filter value when compiling a Transportation Request. The filter value must be a string containing a JSON array of the selected values.