Vehicle - Damages

In some cases the users can submit damages reports to the platform from their smartphone.

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

/api/vehicle-mobile

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

Add damage

Receives a vehicle damage notification paired with a trip:

POST /v1/damages/new

Receives a vehicle damage notification paired with a trip API is deprecated, use damages/sync instead

Status Codes

The body of the request is the following:

{
  Trip: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid
  Notes: "Additional notes",                      // String
  Severity: 1                                     // Int
}

Value types of Severity can be one of the DamageSeverity enumeration.

If the request is successful, it will return a Json positive response with the ID of the new record:

{
  Damage: 123
}

The response will return a plain Json negative response if there is no trip corresponding to the guid provided, if there is no vehicle assigned to the trip, if the trip has been closed for longer than a configurable amount of time or if there was a problem saving the data.

This API is deprecated, use sync damage reports instead

Sync Damage Reports

Receives and syncronize data about multiple damage reports

POST /v1/damages/sync

Synchronizes the list of damage reports from the client to the server

Status Codes

The body of the request is the following:

{
DamageReports: [
  {
    Trip: 'ce8bb2da-8047-44e3-9f0d-80e792f4f90e',    // Guid of the trip related to the damage report
    Guid: '91cd7750-44dc-41ca-b6cd-b801a6cca9ec',    // Guid
    Timestamp: '2020-01-01 00:00:00',                // Date
    Severity: 1,                                     // Int
    Notes: 'some notes'                              // String (nullable)
  },
  { ... }
  ]
}

where value types of Severity can be one of the DamageSeverity enumeration.

In case of problems while registering one or more damage reports, the API will return an OK response with the details of the damage reports with errors:

{
  [
    {
      DamageReport: "91cd7750-44dc-41ca-b6cd-b801a6cca9ec",    // Guid of damage report
      Code: "10101",                                           // Numeric code of the error
      Message: "..."                                           // Localized description of the error
    },
    { ... }
  ]
}
The error reason may be:

  • 30000: some of the provided data is invalid (i.e. the severity is not in the accepted values)

  • 30001: no trip has been found for the provided guid

  • 30002: no vehicle has been found on the provided trip

  • 30003: the provided trip is not related to the current user

  • 30004: the provided trip has been closed for too long to accept a new damage report

Get trip vehicle unresolved damage report

Used to retrieve the list of unresolved damage on the trip assigned vehicle:

GET /v1/trips/{guid}/damage-report

Returns the damage report linked to the trip’s vehicle

Parameters

  • guid (string) – The guid of the trip

Status Codes
guid: The guid of the trip (Guid)

The request will return a Json positive response and any unresolved damage report (if there are any) of the trip corresponding to the guid provided:

{
  "CreatedDate": "2019-12-10T15:33:07Z",                          // DateTime
  "ReportingUser": "ddb8b869-e9c3-4346-b075-c19967ea5a57",        // Guid
  "ReportingUserName": "...",                                     // String
  "Severity": 1,                                                  // Int
  "IsBlocking": null,                                             // Boolean (nullable)
  "Notes": "Test danno medio segnalato da iOS",                   // String (nullable)
  "Attachments": ["53155c4a-b2a0-412f-ab41-552d9ccdf784",...],    // Guid Array (nullable)
  "ID": 46,                                                        // Int
  "Guid": "186e94b5-c383-47ff-8dc9-5b124df62d28"                  // Guid
}

Value types of Severity can be one of the DamageSeverity enumeration.

If there is no corresponding trip, the request will return a plain Json negative response.