Vehicle - Damages
=================
.. Last update: 21/10/2021

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 :download:`here </openapi/srv-vehicle/api-src-WebMobile.json>`.

Add damage
----------
Receives a vehicle damage notification paired with a trip:

.. openapi:: /openapi/srv-vehicle/api-src-WebMobile.json
   :paths:
     /v1/damages/new

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 :ref:`enum-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

.. openapi:: /openapi/srv-vehicle/api-src-WebMobile.json
   :paths:
     /v1/damages/sync

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 :ref:`enum-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:

.. openapi:: /openapi/srv-vehicle/api-src-WebMobile.json
   :paths:
     /v1/trips/{guid}/damage-report

| 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 :ref:`enum-damageseverity` enumeration.

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