FLOTIS REST API

Dokumentacja

wersja: 2020-06-29

Wstęp

Poniższa dokumentacja dotyczy portalu flotis.pl i usługi Flotis API. Wszelkie prawa zastrzeżone.

REST API

Flotis REST API udostępnia interfejs programistyczny zbudowany w oparciu o architekturę REST. Umożliwia on integrację z portalem flotis.pl .

Protokuł 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 (uproszczona) odpowiedź serwera dla żądania:

/flotis-api/secured/external/companies

{
    "companies": [
        {
            "id": "1234",
            "name": "CompanyInternational"
        },
    {
            "id": "4321",
            "name": "EuropeImport"
        }
    ]
}

Dostęp do API

Uwierzytelnianie i autoryzacja

Żądania do API wymagają autoryzacji. Konkretne żądania zostaną oznaczone w dalszej części dokumentu.

API Key

Użytkownik uprawniony do korzystania z API otrzyma dane dostępowe: identyfikator-klienta i sekret-klienta. Każde żądanie HTTP do API będzie musiało zostać opatrzone nagłówkiem: Authorization: Basic klucz-klienta. Klucz-klienta to zakodowany w Base64 ciąg znaków identyfikator-klienta:sekret-klienta.

Przykład:

Identyfikator-klienta: 12345
Sekret-klienta: sekret12345
Authorization: Basic "MTIzNDU6c2VrcmV0MTIzNDU="

Wersja

Żądania do API należy opatrzyć nagłówkiem umożliwiającym określenie wersji systemu. Klucz nagłówka: Accept, Wartość nagłówka application/vnd.flotis.pl-ext1+json

Dostępne komunikaty

W usłudze dostępne są komunikaty, które pozwalają przeglądać dane przypisanych firm, dane pojazdów oraz ich pozycje. Główną funkcjonalnością systemu Flotis jest mechanizm monitorowania GPS pojazdów firmy.

Firmy

System Flotis umożliwia pobranie podstawowych danych firm. W kolejnych podpunktach zostaną omówione wszystkie dostępne dla użytkownika komunikaty oraz struktura danych wejściowych / wyjściowych.

Dane przypisanych firm

Zapytanie:

GET /flotis-api/secured/external/companies

Nagłówki http:

• Accept - application/vnd.flotis.pl-ext1+json
• Authorization - Basic klucz-klienta

Struktura danych (odpowiedzi):

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

Dane pojazdów

System Flotis umożliwia pobranie podstawowych danych pojazdów. W kolejnych podpunktach zostaną omówione wszystkie dostępne dla użytkownika komunikaty oraz struktura danych wejściowych/wyjściowych.

Zapytanie:

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

Nagłówki http:

• Accept - application/vnd.flotis.pl-ext1+json
• Authorization - Basic klucz-klienta

Parametry:

• {companyId} - ID firmy

Struktura danych (odpowiedzi):

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

Pozycje pojazdów

Zapytanie:

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

Nagłówki http:

• Accept - application/vnd.flotis.pl-ext1+json
• Authorization - Basic klucz-klienta

Parametry:

Wymagane:

• {companyId} - ID firmy

Opcjonalne:

• vehicleId - ID pojazdu

Struktura danych (odpowiedzi):

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

Wartości wyliczeniowe w systemie

W przedstawionych zapytaniach i odpowiedziach brak specjalnych wartości wyliczeniowych.

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.