Core - License Documents
========================
.. Last update: 04/04/2022

Users should upload a valid driving license document before being able to make reservations
and perform trips with the shared vehicles.

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

  /api/mobile/

A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded :download:`here </openapi/srv-core/api-src-WebMobile.json>`.

Get the current document
------------------------

.. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/license-document/last

The resulting object is like this::

  {
    "ID": 40,                                              // Int
    "UserID": 5,                                           // Int
    "UserName": "user@test.com",                           // String
    "Type": 0,                                             // Int
    "LicenseNumber": "aaabbb123",                          // String
    "IssuingAuthorityID": 20,                              // Int
    "IssuingAuthority": "MTCT",                            // String
    "Category": "b",                                       // String
    "EquivalentCategory": "b",                             // String
    "CreatedDate": "2019-12-18T13:12:00Z",                 // DateTime
    "IssueDate": "2019-12-01T13:11:09Z",                   // DateTime
    "ExpiryDate": "2020-05-01T12:11:11Z",                  // DateTime (nullable)
    "IsExpired": true,                                     // Boolean
    "LastValidationDate": null,                            // DateTime (nullable)
    "IsValid": true,                                       // Boolean (nullable)
    "IsDeletable": false,                                  // Boolean
    "Attachments": [
      {
        "Guid": "dad015d7-3eb1-4068-88ee-2f9898b86add",    // Guid
        "FileName": "file name"                            // String
      },
      { ... }
    ],
    "Notes": "",                                           // String (nullable)
    "Guid": "dad015d7-3eb1-4068-88ee-2f9898b86add"         // Guid
  }

where the ``Type`` field can be one of the value defined in the :ref:`enum-licensedocumenttypes` enumeration.

Upload a new document
---------------------

.. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/license-document/new

Request body example::

  {
    LicenseNumber: "AB678345",                                     // String
    Category: "C",                                                 // String
    IssuingAuthority: 1,                                           // Int
    IssueDate: "2001-01-01T01:01:01Z",                             // DateTime
    ExpiryDate: "2001-01-01T01:01:01Z",                            // DateTime (nullable)
    Attachments: [
    	{
    	  Guid: '91cd7750-44dc-41ca-b6cd-b801a6cca9ec',            // Guid
          Data: "base64-encoded content of the file",              // String
          Name: "Attachment name",                                 // String
          MimeType: "application/pdf"                              // String
        },
        { ... }
    ]
  }

Implementing User Agents should pass data as entered by the user. In the ``Attachments`` array,
photos of the license document should be stored as base64-encoded JPEG files, resized to have
the longest side around 1000 pixels long. At least two photos are recommended.

The result can be a plain positive response, a positive response with details on attachment errors::

  {
    [
      {
        Attachment: "91cd7750-44dc-41ca-b6cd-b801a6cca9ec",    // Guid of the attachment
        Code: "10101",                                         // Numeric code of the error
        Message: "..."                                         // Localized description of the error
      },
      { ... }
    ]
  }
  
where the error reason may be:
  * 00100: some error arose while trying to save the attachment in the storage
  
or a negative response with one of these messages:

``err_NoLicenseNumberOrCategory``
  No LicenseNumber or Category has been provided.

``err_InvalidDates``
  Issue or expiry date is missing
  
``err_InvalidStartDate``
  Provided issue date is in the future
  
``err_InvalidEndDate``
  Provided expiry date is in the past

``err_MissingAuthority``
  No IssuingAuthority ID has been provided or no authority has been found for the provided ID.