Vehicle - Damage Reports
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 damage report
Gets data about a specific damage report:
- GET /v1/damage-reports/{id}
Gets data about a specific damage report
- Parameters
id (integer) – The id of the report
- Status Codes
200 OK – Success
Returns a Json positive response and the data of the specified damage report:
{
"ID": 1, // Int
"Guid": "186e94b5-c383-47ff-8dc9-5b124df62d28", // Guid
"CreatedDate": "2020-09-10T08:33:30Z", // DateTime
"ReportingUser": "21b3da2c-159c-4d76-ad25-e4a8452513ab", // Guid
"ReportingUserName": "abel@gmail.com", // String
"Severity": 1, // Int
"Solved": null, // DateTime (nullable)
"IsBlocking": null, // Boolean (nullable)
"SolvingUser": null, // Guid (nullable)
"SolvingUserName": null, // String (nullable)
"Notes": "Internal mirror damage", // String (nullable)
"Attachments": // Guid Array
[
"f13abe76-91e1-4d18-be36-6edf68c840dc" // Guid
],
"Vehicle":
{
"ID": 26, // Int
"LicensePlate": "AA000AA", // String
"VIN": "01234567890", // String
"Sticker": null, // String
"LastSetOperativeBy": null, // String (nullable)
"IsOperative": true, // Boolean (nullable)
"AdminOperativeStatus": true, // Boolean
"SystemOperativeStatus": true, // Boolean
"SystemOperativeReason": "", // String (nullable)
"OverriddenSystemOperativeStatus": true, // Boolean
"ForcedOperativeBy": "Administrator.name", // String (nullable)
"Notes": null, // String (nullable)
"CategoryLabels": "{\"en\":\"Jolly Smart\"}", // String
"CategoryID": 2, // Int
"CategoryTree": // Category Array (nullable)
{
"ID": 1, // Int
"Labels": "{\"en\":\"City Car\"}", // String
"Children":
[
{
"ID": 2, // Int
"Labels": "{\"en\":\"Jolly Smart\"}", // String
"Children": null // Category Array (nullable)
},
...
]
},
"Devices": // Device Array (nullable)
[
{
"ID": 13, // Int
"SerialNumber": "EDOXVERZKOSYXUJ", // String
"LastDeviceSync": "2001-01-01T00:00:00Z" // DateTime (nullable)
},
...
],
"NominalGarage": null, // String (nullable)
"NominalGarageID": 4, // Int
"RecoveringGarage": null, // String (nullable)
"RecoveringGarageID": null, // Int (nullable)
"Latitude": 46.0838284476514, // Double (nullable)
"Longitude": 13.217754364013674, // Double (nullable)
"LastPositionUpdate": "2020-09-10T08:31:16Z", // DateTime (nullable)
"Groups": [ ], // Guid Array (nullable)
"CurrentTripGuid": null, // Guid (nullable)
"DeviceID": 13, // 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": null, // Double (nullable)
"LastOdometerReading": null, // DateTime (nullable)
"IsDamaged": true, // Boolean (nullable)
"Status": // Object (VehicleStatus)
{
"CurrentReservationEnd": null, // DateTime (nullable)
"CurrentReservationMaxStart": null, // DateTime (nullable)
"CurrentReservationMinStart": null, // DateTime (nullable)
"LastDeviceSync": null, // DateTime (nullable)
"LastMaintenanceEnd": null, // DateTime (nullable)
"LastMaintenanceStart": null, // DateTime (nullable)
"LastMotion": null, // DateTime (nullable)
"LastPositionUpdate": "2020-09-10T08:31:16Z", // DateTime (nullable)
"LastTripEnd": "2020-09-10T08:34:33Z", // DateTime (nullable)
"LastTripStart": "2020-09-10T08:31:16Z", // DateTime (nullable)
"FuelLevelPct": null, // Double (nullable)
"ServiceBattery": null, // Double (nullable)
"LastNetworkSignalStrengthPct": null, // Int (nullable)
"AdminOperativeStatus": true, // Boolean
"SystemOperativeStatus": true, // Boolean
"IsLowFuel": true, // Boolean
"IsLowEVB": true, // Boolean
"IsLostContact": true, // Boolean
"IsPositionLost": false, // Boolean
"IsReserved": true, // Boolean
"IsOnTrip": false, // Boolean
"IsOnTripAndMoving": false, // Boolean
"IsWithoutTripsForLong": false, // Boolean
"IsInMaintenance": false, // Boolean
"IsInternetWeak": true // Boolean
},
"InternalCleaningStatus": null, // Int (nullable)
"ExternalCleaningStatus": null, // Int (nullable)
"IgnitionVoltageLevel": null // Int (nullable)
}
The field CategoryLabels
in Vehicle and Labels
in CategoryTree contain a stringified Json containing pairs “language code”:”localized value”
Values of the property Severity
can be one of the DamageSeverity enumeration.
Values of the properties InternalCleaningStatus
and ExternalCleaningStatus
can be one of the VehicleCleaningStatus enumeration.
Values of EngineType
can be one of the VehicleEngineTypes enumeration.
The fields NominalGarage
, RecoveringGarage
and Groups
are always either null or empty string/array.
Get damage report list
Gets the list of damage reports (it’s a Paged List APIs, as explained in the introduction):
Returns a list of all damage reports:
[
{
"ID": 1, // Int
"CreatedDate": "2020-09-10T08:33:30Z", // DateTime
"ReportingUser": "21b3da2c-159c-4d76-ad25-e4a8452513ab", // Guid
"ReportingUserName": "abel@gmail.com", // String
"Severity": 1, // Int
"Solved": null, // DateTime (nullable)
"IsBlocking": null, // Boolean (nullable)
"SolvingUser": null, // Guid (nullable)
"SolvingUserName": null, // String (nullable)
"Notes": "Internal mirror damage", // String (nullable)
"Attachments": // Guid Array
[
"f13abe76-91e1-4d18-be36-6edf68c840dc" // Guid
],
"VehicleID": 26, // Int
"LicensePlate": "AA000AA", // String
"OperationID": null, // Int (nullable)
"OperatingBaseID": null, // int (nullable)
"OperatingBase": null, // String (nullable)
"LastOperationUpdate": null, // DateTime (nullable)
"OperationEnteredBy": null, // String (nullable)
"OperationSignedOffBy": null, // String (nullable)
"OperationPerformedBy": null, // String (nullable)
"OperationCompleted": false, // Boolean
"OperationSuccessful": false // Boolean
},
...
]
Value of the property Severity
can be one of the DamageSeverity enumeration.
The data related to the specific maintenance operation (OperationID
through OperationSuccessful
) here are always set as either
null or false.
Update Damage Report
Persists the edit about an existing damage report:
- POST /v1/damage-reports
Persists edits about an existing damage report
- Status Codes
200 OK – Success
with a request body like:
{
ID: 43, // Int
IsBlocking: true, // Boolean (nullable)
Notes: "Additional notes or description of the damage", // String (nullable)
SolvingUser: "Solving operator user name" // String (nullable)
}
This API will update the fields Notes
and IsBlocking
if the damage report is yet to be solved and the field SolvingUserName
if the damage
report is already solved.
The field IsBlocking
is a nullable boolean, and means that the damage report is severe, and thus the vehicle has to be set as inoperative.
As soon as a damage report set as not blocking - or still not set as blocking or not blocking - is updated with IsBlocking
to true, the platform
will set the assigned vehicle as inoperative; conversely, if the damage report has IsBlocking
set to true and it is updated to false, if there
are no other blocking unresolved damage reports on the vehicle it will be set as operative.
Possible errors are:
err_InvalidElement
No value has been passed in the field ID
, no damage report has been found for the provided ID or the damage is marked as solved and no solving user has been provided
Mark Damage Report as Solved
Sets the damage report as solved:
- POST /v1/damage-reports/{id}/mark-solved
Set damage report as solved
- Parameters
id (integer) –
- Status Codes
200 OK – Success
where id
is the ID of the damage report to be set as solved.
This API requires a request body like this:
{
Notes: "Additional notes or description of the damage", // String (nullable)
SolvingUser: "Solving operator user name" // String
}
and will automatically set the Solved
field at the current date and time. If the damage report was set as blocking and there ar no other blocking
unresolved damage reports on the vehicle, it will also set the vehicle as operative.
The SolvingUser
field is required.
Possible errors are:
err_NotFound
No damage reports has been found for the provided id
err_AlreadySolved
The damage report related to the provided id has already been marked as solved
err_InvalidElement
No solving user has been provided in the Json body