FLOTIS REST API

Dokumentacja Flotis REST API
wersja: 1.2 (2022-02-01)

Wstęp

Główną funkcjonalnością systemu Flotis jest mechanizm monitorowania pozycji pojazdów na podstawie danych przesyłany z urządzeń GPS zainstalowanych w pojazdach. Poniższa dokumentacja dotyczy usługi Flotis REST API. W usłudze tej dostępne są komunikaty, które pozwalają pobierać dane przypisanych firm, dane pojazdów oraz ich pozycje. Wszelkie prawa zastrzeżone.

REST API

Flotis REST API udostępnia interfejs programistyczny zbudowany w oparciu o architekturę REST. Umożliwia on integrację z usługą monitoringu pojazdów Flotis.

Protokół komunikacyjny

Komunikację realizuje się z wykorzystaniem protokołu HTTPS wraz z jego metodą: GET.

Metody

API zostało zbudowane w oparciu o następujące metody HTTP:

  • GET - Wykorzystywana do pobierania danych

Reprezentacja danych

Komunikacja w obrębie API odbywa się za pomocą danych w formacie JSON. W odpowiedziach serwera pola o wartości NULL nie są ukrywane. Przykładowa odpowiedź serwera dla żądania:

/flotis-api/secured/external/companies

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

Nagłówki HTTP

Uwierzytelnianie i autoryzacja

Żądania do API wymagają autoryzacji. Użytkownik uprawniony do korzystania z API otrzyma od administatora systemu dane dostępowe: identyfikator-klienta i sekret-klienta.
Do każdego żądania należy dołączyć nagłówek: Authorization o wartości: Basic klucz-klienta.
Klucz-klienta to zakodowany w Base64 ciąg znaków identyfikator-klienta:sekret-klienta.

Przykład:
identyfikator klienta: client_id
sekret klienta: client_secret
klucz klienta (Base64(client_id:client_secret)): Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
nagłówek HTTP: Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Wersja

Do każdego żądania należy również dołączyć nagłówek: Accept określający wersję komunikatu. Wersja komunikatu oznaczana jest przy opisie każdego żądania.
 
 

Dostępne komunikaty

W kolejnych punktach zostaną omówione wszystkie dostępne dla użytkownika komunikaty oraz struktura danych wejściowych/wyjściowych.

1. Firmy

Flotis REST API umożliwia pobranie listy firm, dla których użytkownik API może pobierać dane o pojazdach.

1.1. Dane przypisanych firm

Żądanie:
GET /flotis-api/secured/external/companies

Wersja komunikatu:
application/vnd.flotis.pl-ext1+json

Struktura danych (odpowiedzi):

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

2. Pojazdy

Flotis REST API umożliwia pobranie podstawowych danych o pojazdach.

2.1. Dane pojazdów (id firmy)

Dane pojazdów pobierane na podstawie id firmy.

UWAGA!
Z dniem 01.06.2022r żądanie to przestanie być dostępne.
Zamiast tego komunikatu należy używać żądania: 2.2 Dane pojazdów (klucz api))

Żądanie:
GET /flotis-api/secured/external/vehicles/companyId/{companyId}

Wersja komunikatu:
application/vnd.flotis.pl-ext1+json

Parametry:
{companyId} - id firmy (dostępny w odpowiedzi żądania: 1 Firmy)

Struktura danych (odpowiedzi):

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

2.2. Dane pojazdów (klucz api)

Dane pojazdów pobierane na podstawie przekazanego klucza api.

Żądanie:
GET /flotis-api/secured/external/vehicles/api-key/{api-key}

Wersja komunikatu:
application/vnd.flotis.pl-ext1+json

Parametry:
{api-key} - Klucz api przekazany użytkownikowi API przez użytkownika systemu.

Struktura danych (odpowiedzi):

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

3. Pozycje

Flotis REST API umożliwia pobranie ostatniej pozycji pojazdu. Aktualna pozycja pojazdu jest odświeżana nie częściej niż co 1 minutę.

3.1. Pozycje (id firmy)

Ostatnie pozycje pojazdów pobierane na podstawie id firmy.

UWAGA!
Z dniem 01.06.2022r żądanie to przestanie być dostępne.
Zamiast tego komunikatu należy używać żądania: 3.2 Pozycje (klucz api))

Żądanie:
GET /flotis-api/secured/external/positions/companyId/{companyId}

Wersja komunikatu:
application/vnd.flotis.pl-ext1+json

Parametry:
{companyId} - id firmy (dostępny w odpowiedzi żądania: 1 Firmy)

Struktura danych (odpowiedzi):

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

3.2. Pozycje (klucz api)

Ostatnie pozycje pojazdów pobierane na podstawie przekazanego klucza api.

Żądanie:
GET /flotis-api/secured/external/positions/api-key/{api-key}

Wersja komunikatu:
application/vnd.flotis.pl-ext1+json

Parametry:
{api-key} - Klucz api przekazany użytkownikowi API przez użytkownika systemu.

Struktura danych (odpowiedzi):

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

Statusy HTTP

Każde żądanie do API zwraca status HTTP informujący o wyniku operacji. Poniżej przedstawiono wszystkie komunikaty występujące w systemie:

  • 200 - (Ok) - Żądanie wykonano z sukcesem.
  • 400 - (Bad Request) - Niepoprawne żądanie HTTP.
  • 401 - (Unauthorized) - Brak poprawnej autoryzacji.
  • 403 - (Forbidden) - Akcja niedozwolona dla danego użytkownika.
  • 404 - (Not Found) - Zasób nie został odnaleziony.
  • 500 - (Internal Server Error) - Błąd wewnętrzny serwera.