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.