FLOTIS REST API

Documentation Flotis REST API
version: 1.2 (2022-02-01)

Preface

The main functionality of the Flotis system is the vehicle position monitoring mechanism based on data sent from GPS devices installed in the vehicles. The following documentation applies to the Flotis REST API service. This service offers messages that allow you to receive data of assigned companies, vehicles and their positions.
All rights reserved.

REST API

The Flotis REST API provides a programming interface based on the REST architecture. It enables integration with the Flotis service.

Communication protocols

Communication is carried out using the HTTPS protocol together with it method: GET.

Methods

The API was built based on the following HTTP methods:

• GET - Used to retrieve data

Data representation

Communication within the API is realised using data in JSON format. NULL fields are not hidden in server responses. Sample (simplified) server response for a request:

/flotis-api/secured/external/companies

[
    {
        "id": 34,
        "name": "CompanyInternational"
    },
    {
        "id": 123,
        "name": "EuropeImport"
    }
]

HTTP headers

Authentication and authorization

API requests require authorization. The user authorized to use the API will receive access data from the system administrator: client-id and client-secret.
Each HTTP request will have to contain the header: Authorization with value: Basic client-key.
The client-key is the string encoded in Base64 client-id:client-secret.

Example:
client-id: client_id
client-secret: client_secret
client-key: (Base64(client_id:client_secret)): Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
HTTP header: Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Version

Each request should also be accompanied by the header: Accept, which defines the version of the message. The message version is marked with the description of each request.
 

Available messages

All messages available to the user and the structure of the input/output data will be discussed in the following sections.

1. Companies

Flotis REST API allows you to receive a list of companies for which the API user can get vehicle data.

1.1. Assigned companies data

Request:
GET /flotis-api/secured/external/companies

Message version:
application/vnd.flotis.pl-ext1+json

Data structure (Response):

[
    {
        "id": 0,
        "name": "string"
    }
]

 

2. Vehicles

Flotis REST API allows you to receive basic vehicle data.

2.1. Vehicle data (company id)

Vehicle data received based on company id.

WARNING!
As of June 1, 2022 this request will no longer be available.
Use request instead: 2.2. Vehicle data (api key)

Request:
GET /flotis-api/secured/external/vehicles/companyId/{companyId}

Message version:
application/vnd.flotis.pl-ext1+json

Parameters:
{companyId} - company id (available in response to the request: 1. Companies)

Data structure (Response):

[
    {
        "id": 0,
        "deviceNumber": "string",
        "description": "string",
        "registration": "string"
    }
]

2.2. Vehicle data (api key)

Vehicle data received based on provided api key.

Request:
GET /flotis-api/secured/external/vehicles/api-key/{api-key}

Message version:
application/vnd.flotis.pl-ext1+json

Parameters:
{api-key} - The api key passed to the API user by the system user.

Data structure (Response):

[
    {
        "id": 0,
        "deviceNumber": "string",
        "description": "string",
        "registration": "string"
    }
]

 

3. Positions

Flotis REST API allows you to retrieve the last vehicle position. The current vehicle position is refreshed no more frequently than every 1 minute.

3.1. Positions (company id)

Last vehicle positions received based on company id.

WARNING!
As of June 1, 2022 this request will no longer be available.
Use request instead: 3.2. Positions (api key)

Request:
GET /flotis-api/secured/external/positions/companyId/{companyId}

Message version:
application/vnd.flotis.pl-ext1+json

Parameters:
{companyId} - company id (available in response to the request: 1. Companies)

Data structure (Response):

[
    {
        "vehicleId": 0,
        "gpsTime": 0,
        "latitude": 0.0,
        "longitude": 0.0,
        "speed": 0
    }
]

3.2. Positions (api key)

Last vehicle positions received based on provided api key.

Request:
GET /flotis-api/secured/external/positions/api-key/{api-key}

Message version:
application/vnd.flotis.pl-ext1+json

Parameters:
{api-key} - The api key passed to the API user by the system user.

Data structure (Response):

[
    {
        "vehicleId": 0,
        "gpsTime": 0,
        "latitude": 0.0,
        "longitude": 0.0,
        "speed": 0
    }
]

 

HTTP statuses

Each request to the API returns an HTTP status informing about the result of the operation. The following are all system messages:

• 200 - (Ok) - The request was carried out successfully.
• 400 - (Bad Request) - Invalid HTTP request.
• 401 - (Unauthorized) - No valid authorization.
• 403 - (Forbidden) - Action not allowed for this user.
• 404 - (Not Found) - The resource was not found.
• 500 - (Internal Server Error) - Internal server error.