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.