Vehicle - Categories
The Admin interface handles web service calls from the Admin web gui. The base url for this is at:
/api/vehicle-admin
A JSON file with OpenAPI data about all vehicle-related admin APIs can be downloaded here.
Get categories tree
Get the tree of categories:
Returns a Json positive response and the tree of the vehicle categories:
[
{
"ID": 1, // Int
"ParentID": null, // Int (nullable)
"Labels": "{\"en\":\"City Car\"}", // String
"Children": // VehicleCategory Array (nullable)
[
{
"ID": 2, // Int
"ParentID": 1, // Int
"Labels": "{\"en\":\"Jolly Smart\"}", // String
"Children": [], // VehicleCategory Array (nullable)
"Guid": "00000000-0000-0000-0000-000000000000", // Guid
"ParentGuid": "170884ee-05e3-4c14-a8b4-e661a9a216e1", // Guid
"Originator": "32b297a5-8180-420f-9482-84bfc7f55efe" // Guid
},
...
],
"Guid": "00000000-0000-0000-0000-000000000000", // Guid
"Originator": "32b297a5-8180-420f-9482-84bfc7f55efe" // Guid
},
...
]
The field Labels contains a stringified Json containing pairs “language code”:”localized value”
The fields ParentID and ParentGuid are always valorized inside of children categories.
Get category subtree
Gets the subtree of categories rooted at the specified parent:
- GET /v1/vehicle-categories/{id}/tree
Gets the subtree of categories rooted at the specified parent
- Parameters
id (integer) – The id of the parent category
- Status Codes
200 OK – Success
Returns a Json positive response and the subtree of categories:
[
{
"ID": 1, // Int
"ParentID": null, // Int
"Labels": "{\"en\":\"City Car\"}", // String
"Children": // VehicleCategory Array (nullable)
[
{
"ID": 2, // Int
"ParentID": 1, // Int
"Labels": "{\"en\":\"Jolly Smart\"}", // String
"Children": [], // VehicleCategory Array (nullable)
"Guid": "00000000-0000-0000-0000-000000000000", // Guid
"ParentGuid": null, // Guid
"Originator": "32b297a5-8180-420f-9482-84bfc7f55efe" // Guid
},
...
],
"Guid": "00000000-0000-0000-0000-000000000000", // Guid
"ParentGuid": null, // Guid (nullable)
"Originator": "32b297a5-8180-420f-9482-84bfc7f55efe" // Guid
},
...
]
The field Labels contains a stringified Json containing pairs “language code”:”localized value”
The fields ParentID and ParentGuid are always valorized inside of children categories.
Get vehicle category
Gets a specific vehicle category:
- GET /v1/vehicle-categories/{id}
Gets a specific vehicle category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
- DELETE /v1/vehicle-categories/{id}
Marks a specified category (and its descendants) as deleted
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
The request will return a Json positive response and the data of the category corresponding to the provided ID:
{
ID: 123, // Int
ParentID: 122, // Int (nullable)
DeletionDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
Labels: "{\"en\":\"City Car\"}", // String
Manufacturer: "FIAT", // String (nullable)
Model: "Punto" // String (nullable)
Year: 2018, // Int (nullable)
PassengerSeats: 4, // Int (nullable)
Image: "iVBORw0KGgoAAAANSUhEU...", // ByteArray as String (nullable)
ImageThumbnail: "iVBORw0KGgoAAAANSUhEU...", // ByteArray as String (nullable)
IsRoot: true // Boolean
}
or a plain Json negative response if no corresponding record is found.
The field Labels contains a stringified Json containing pairs “language code”:”localized value”
Get categories list
Gets the list of tree-leaf categories (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/vehicle-categories/list
Gets the list of tree-leaf categories
- Status Codes
200 OK – Success
Returns the list of tree-leaf categories:
[
{
"ID": 2, // Int
"ParentID": null, // Int (nullable)
"Labels": "{\"en\":\"Jolly Smart\"}", // String
"Guid": "00000000-0000-0000-0000-000000000000", // Guid
"ParentGuid": null, // Guid (nullable)
"DeletionDate": null, // DateTime (nullable)
"Originator": "32b297a5-8180-420f-9482-84bfc7f55efe" // Guid
},
...
]
The field Labels contain a stringified Json containing pairs “language code”:”localized value”
Add new or edit existing vehicle category
Persists edits about a new or existing category:
- POST /v1/vehicle-categories
Persists edits about a new or existing category
- Status Codes
200 OK – Success
With a body like this:
{
ID: 123, // Int
ParentID: 12, // Int (nullable)
Labels: "{\"en\":\"Sedan\",...}", // String
Manufacturer: "FIAT", // String (nullable)
Model: "Punto", // String (nullable)
Year: 2018, // Int (nullable)
PassengerSeats: 5 // Int (nullable)
}
If ID (category ID) is not provided or is set to 0, then the request will create a new record.
The field Labels contains a stringified Json containing pairs “language code”:”localized value”
Returns a plain Json positive response if the record was added or edit successfully.
err_InvalidElementNo value has been passed in the labels field, or no category to edit has been found for the provided
ID
Delete category
Marks a specified category (and its descendants) as deleted:
- GET /v1/vehicle-categories/{id}
Gets a specific vehicle category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
- DELETE /v1/vehicle-categories/{id}
Marks a specified category (and its descendants) as deleted
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
Returns a Json positive response if the request is successful.
Returns a plain Json negative response if the category is ReadOnly
Possible error messages are:
err_ElementDoesNotExistThere is no category corresponding to the
IDprovided in the requesterr_ElementAlreadyDeletedThe specified category record has already been marked as deleted
err_CannotDeleteCategoryHasVehiclesThe category has some vehicles assigned to it
Get the images for a vehicle category
Gets the image and image thumbnail for the specified vehicle category.
- GET /v1/vehicle-categories/{id}/images
Retrieves the main image and thumbnail for the specified category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
The request will return a positive response with the image data for the images of the specified category:
{
Image: "iVBORw0KGgoAAAANSUhEU...", // ByteArray as String (nullable)
ImageThumbnail: "iVBORw0KGgoAAAANSUhEU..." // ByteArray as String (nullable)
}
where the two fields are the images converted in base64 string format, or a plain Json negative response if an error occurred.
Add or edit category image
Persists the main image for the specified category:
- POST /v1/vehicle-categories/{id}/image
Persists the main image for the specified category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
With the request body:
{
Base64String: "base64-encoded content of the file" // String
}
Returns a plain Json positive response if the image was successfully saved.
Returns a plain Json negative response if there is no category corresponding to the ID provided in the request, or if there was a problem saving the image.
Add or edit category thumbnail
Persists the thumbnail image for the specified category:
- POST /v1/vehicle-categories/{id}/thumbnail
Persists the thumbnail image for the specified category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
With the request body:
{
Base64String: "base64-encoded content of the file" // String
}
Returns a plain Json positive response if the thumbnail was successfully saved.
Returns a plain Json negative response if there is no category corresponding to the ID provided in the request, or if there was a problem saving the thumbnail.
Get vehicles by category
Gets the list of vehicles belonging to the specified category (it’s a Paged List APIs, as explained in the introduction):
- GET /v1/vehicle-categories/{id}/list-vehicles
Gets the list of vehicles belonging to the specified category
- Parameters
id (integer) – The id of the category
- Status Codes
200 OK – Success
Returns a list of the vehicles:
[
{
"ID": 21, // Int
"LicensePlate": "AA000AA", // String
"VIN": "343434343434343434", // String
"Sticker": null, // String (nullable)
"LastSetOperativeBy": "User Name", // String (nullable)
"IsOperative": false, // Boolean
"AdminOperativeStatus": false, // Boolean
"SystemOperativeStatus": true, // Boolean
"SystemOperativeReason": null, // String (nullable)
"OverriddenSystemOperativeStatus": true, // Boolean
"ForcedOperativeBy": "Administrator.name", // String (nullable)
"Notes": null, // String (nullable)
"CategoryLabels": "{\"en\":\"City Car\"}", // String
"CategoryID": 1, // Int
"CategoryTree": null, // Object (CategoryDescription)
"Devices": // Object Array
[
{
"ID": 17, // Int
"SerialNumber": "DWVBMPHBJXFZFRM", // String
"LastDeviceSync": "2001-01-01T00:00:00Z" // DateTime (nullable)
},
...
],
"Latitude": 41.775761, // Double (nullable)
"Longitude": 12.245980000000003, // Double (nullable)
"LastPositionUpdate": "2019-09-18T04:14:23Z", // DateTime (nullable)
"Groups": [], // Guid Array
"CurrentTripGuid": null, // Guid (nullable)
"DeviceID": 17, // Int (nullable)
"LastDeviceSync": null, // DateTime (nullable)
"LastNetworkSignalStrengthPct": null, // Int (nullable)
"EngineType": 0, // Int
"FuelTankCapacity": null, // Int (nullable)
"FuelLevelPct": null, // Double (nullable)
"EVBLevelPct": null, // Double (nullable)
"OdometerKm": 118, // Int (nullable)
"LastOdometerReading": "2001-01-01T00:00:00Z", // DateTime (nullable)
"IsDamaged": false, // Boolean (nullable)
"Status": // Object (VehicleStatus)
{
CurrentReservationEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
CurrentReservationMaxStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
CurrentReservationMinStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastDeviceSync: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMaintenanceEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMaintenanceStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMotion: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPositionUpdate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastTripEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastTripStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
FuelLevelPct: 10.123, // Double (nullable)
ServiceBattery: 12.456, // Double (nullable)
LastNetworkSignalStrengthPct: 81, // Double (nullable)
AdminOperativeStatus: true, // Boolean
SystemOperativeStatus: false, // Boolean
IsLowFuel: true, // Boolean
IsLowEVB: true, // Boolean
IsLostContact: false, // Boolean
IsPositionLost: false, // Boolean
IsReserved: false, // Boolean
IsOnTrip: false, // Boolean
IsOnTripAndMoving: false, // Boolean
IsWithoutTripsForLong: false, // Boolean
IsInMaintenance: false, // Boolean
IsInternetWeak: false // Boolean
},
"InternalCleaningStatus": null, // Int (nullable)
"ExternalCleaningStatus": null, // Int (nullable)
"IgnitionVoltageLevel": null // Int (nullable)
},
...
]
The field CategoryLabels and Labels in CategoryTree contain a stringified Json containing pairs “language code”:”localized value”
Value of the fields InternalCleaningStatus and ExternalCleaningStatus can be one of the VehicleCleaningStatus enumeration.
Values of EngineType can be one of the VehicleEngineTypes enumeration.
Get descendant category vehicles
Gets the list of vehicles of the descendant categories:
- GET /v1/vehicle-categories/{id}/list-descendants-vehicles
Gets the list of vehicles belonging to the specified category descendants
- Parameters
id (integer) – The id of the parent category
- Status Codes
200 OK – Success
Returns a Json positive response and the list of vehicles:
[
{
"ID": 21, // Int
"LicensePlate": "AA000AA", // String
"VIN": "343434343434343434", // String
"Sticker": null, // String
"LastSetOperativeBy": null, // String
"IsOperative": false, // Boolean
"AdminOperativeStatus": false, // Boolean
"SystemOperativeStatus": true, // Boolean
"SystemOperativeReason": null, // String
"OverriddenSystemOperativeStatus": true, // Boolean
"ForcedOperativeBy": "Administrator.name", // String (nullable)
"Notes": null, // String
"CategoryLabels": "{\"en\":\"City Car\"}", // String
"CategoryID": 1, // Int
"CategoryTree": null, // Object (CategoryDescription)
"Devices": null, // Null
"NominalGarage": "London Maintenance Garage", // String
"NominalGarageID": 12, // Int
"RecoveringGarage": null, // String (nullable)
"RecoveringGarageID": null, // Int (nullable)
"Latitude": 41.775761, // Double (nullable)
"Longitude": 12.245980000000003, // Double (nullable)
"LastPositionUpdate": "2019-09-18T04:14:23Z", // DateTime (nullable)
"Groups": [], // Guid Array
"CurrentTripGuid": null, // Guid (nullable)
"DeviceID": 17, // Int (nullable)
"LastDeviceSync": null, // dateTime (nullable)
"LastNetworkSignalStrengthPct": null, // Int (nullable)
"EngineType": 0, // Int
"FuelTankCapacity": null, // Int (nullable)
"FuelLevelPct": null, // Double (nullable)
"EVBLevelPct": null, // Double (nullable)
"OdometerKm": 118, // Int (nullable)
"LastOdometerReading": "2001-01-01T00:00:00Z", // DateTime (nullable)
"IsDamaged": false, // Boolean (nullable)
"Status": // Object (VehicleStatus)
{
CurrentReservationEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
CurrentReservationMaxStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
CurrentReservationMinStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastDeviceSync: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMaintenanceEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMaintenanceStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastMotion: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPositionUpdate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastTripEnd: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastTripStart: "2001-01-01T01:01:01Z", // DateTime (nullable)
FuelLevelPct: 10.123, // Double (nullable)
ServiceBattery: 12.456, // Double (nullable)
LastNetworkSignalStrengthPct: 81, // Double (nullable)
AdminOperativeStatus: true, // Boolean
SystemOperativeStatus: false, // Boolean
IsLowFuel: true, // Boolean
IsLowEVB: true, // Boolean
IsLostContact: false, // Boolean
IsPositionLost: false, // Boolean
IsReserved: false, // Boolean
IsOnTrip: false, // Boolean
IsOnTripAndMoving: false, // Boolean
IsWithoutTripsForLong: false, // Boolean
IsInMaintenance: false, // Boolean
IsInternetWeak: false // Boolean
},
"InternalCleaningStatus": null, // Int (enum VehicleCleaningStatus) (nullable)
"ExternalCleaningStatus": null, // Int (enum VehicleCleaningStatus) (nullable)
"IgnitionVoltageLevel": null // Int (nullable)
},
...
]
or a plain Json negative response if there was a problem retrieving the data.
The field CategoryLabels and Labels in CategoryTree contain a stringified Json containing pairs “language code”:”localized value”
Value InternalCleaningStatus and ExternalCleaningStatus can be one of the VehicleCleaningStatus enumeration.
Values of EngineType can be one of the VehicleEngineTypes enumeration.