Własny system (API)
Gdy Twoje ciężarówki raportują do telematyki, której Quanty nie czyta samo (albo do Waszego własnego systemu), ten system może zamiast tego wysyłać pozycje do Quanty. W Telematyce łączysz Własny system (API), tworzysz klucz API, który może wysyłać pozycje, a Twój system wysyła je na jeden adres. Od tej chwili działają jak pozycje od każdego dostawcy: na mapie floty, na tablicy pojazdów w Śledzeniu, w kilometrach zleceń i w przebiegu.
Zanim zaczniesz
- Telematyka jest częścią dodatku TMS, a telematykę łączą i klucze API tworzą tylko administratorzy organizacji.
- Pojazdy muszą już być we flocie TMS (Pojazdy i zestawy): Quanty dopasowuje każdą pozycję do jednego z Twoich pojazdów TMS i nigdy nie tworzy pojazdu z pozycji.
- Programista systemu wysyłającego potrzebuje adresu, klucza i opisanego niżej wywołania. Pełne wywołanie i odpowiedź są też w Dokumentacji API.
1. Połącz Własny system (API)
- Otwórz Telematykę (z Integracji) i kliknij Połącz na kafelku Własny system (API): „Dla telematyki, której Quanty nie czyta samo: Twój system wysyła pozycje do Quanty.”
- W kroku Dostęp nie ma nic do wypełnienia: „Nic tu nie trzeba wpisywać. Twój system wysyła pozycje pojazdów na adres poniżej, z kluczem API organizacji.” Krok pokazuje te same instrukcje co Jak wysyłać dane (poniżej).
- Miejsce zapisu: tabela albo Bez tabeli, tylko mapa, jak u każdego dostawcy (zobacz Łączenie telematyki).
- Harmonogram: „Nic nie jest odczytywane według harmonogramu: pozycje przychodzą, gdy wyśle je Twój system.” Jeśli chcesz, nadaj nazwę, i zapisz. Nie ma testu: niczego nie trzeba pytać u dostawcy.
Wiersz połączenia pokazuje potem Odbiór danych: Przez API i Ostatnie dane (kiedy przyszła ostatnia pozycja) oraz ma przycisk Jak wysyłać dane. Wystarczy jedno takie połączenie; gdy już je masz, kafelek nie pokazuje przycisku Połącz.
2. Utwórz klucz API, który może wysyłać pozycje
- Otwórz Ustawienia TMS, API i webhooki i kliknij Utwórz klucz.
- Wpisz Nazwę, na przykład „Nadajnik telematyki”.
- Zaznacz Telematyka: wysyłanie. Ten dostęp nigdy nie jest zaznaczony domyślnie, a wcześniej utworzone klucze go nie mają. Cztery rodzaje danych do odczytu (Zlecenia, Kontrahenci, Pojazdy, Faktury) są domyślnie zaznaczone: odznacz je, jeśli klucz ma tylko wysyłać pozycje.
- Kliknij Utwórz klucz i skopiuj klucz: „Ten klucz pokazujemy tylko raz. Na liście zostaje tylko jego początek; jeśli zginie, unieważnij go i utwórz nowy.”
Klucz, który ma tylko Telematyka: wysyłanie, może wysyłać pozycje i niczego nie czyta. Organizacja może mieć do 20 aktywnych kluczy. Unieważnij od razu wyłącza klucz.
3. Wysyłanie pozycji
Jak wysyłać dane pokazuje adres z przyciskiem Kopiuj:
POST https://<your Quanty API address>/api/v1/ext/tms/telematics/positions
Authorization: Bearer <API key>
Content-Type: application/jsonoraz przykładowe wywołanie z wpisanym bieżącym czasem:
{"items":[{"vehicle":{"plate":"PO 1AB23"},"at":"2026-11-02T10:00:00Z","lat":52.4064,"lng":16.9252,"speed_kmh":82}]}Pola pozycji
| Pole | Co oznacza | Przykład |
|---|---|---|
vehicle | Który pojazd: jego id w Quanty, vin albo plate. Wymagane. | {"plate":"PO 1AB23"} |
at | Kiedy pozycja została zarejestrowana: ISO 8601 (bez przesunięcia strefy to UTC) albo sekundy Unix. Wymagane. | "2026-11-02T10:00:00Z" |
lat, lng | Pozycja w stopniach (WGS 84). Wymagane; 0,0 jest odrzucane. | 52.4064, 16.9252 |
speed_kmh | Prędkość, od 0 do 400. Wysyłaj ją: bez prędkości pojazd jest na mapie pokazywany jako Brak sygnału. | 82 |
heading | Kierunek w stopniach. | 90 |
odometer_km | Przebieg, powyżej 0 i najwyżej 5 000 000. | 423434.5 |
fuel_pct, fuel_l | Poziom paliwa w % (od 0 do 100) i w litrach. | 64 |
driver | Kierowca: id i name. | {"name":"Marek Zieliński"} |
trailer | Naczepa: plate albo vin. | {"plate":"PO 4TR11"} |
Opcjonalna wartość, która nie ma sensu (prędkość -1, przebieg 0, paliwo „n/a”), jest pomijana i wymieniana w ignored; sama pozycja zostaje zapisana. Pole, którego nie wyślesz, zachowuje ostatnią wartość (na przykład kierowca); null je czyści.
Jak dopasowywany jest pojazd
- Po
id, jeśli jest podane (nieznane id jest odrzucane, bez dalszych prób). - W przeciwnym razie po
vin; VIN, który do niczego nie pasuje, przechodzi do numeru rejestracyjnego. - W przeciwnym razie po
plate, porównywanym bez spacji i myślników, wielkimi literami („po-1ab23” pasuje do „PO 1AB23”).
Pojazd TMS, który nie ma jeszcze telematyki, zostaje połączony z tym połączeniem przy pierwszej pozycji, co widać w jego historii. Pojazd, który zasila już inne połączenie telematyki, jest odrzucany, tak samo jak numer rejestracyjny albo VIN wspólny dla dwóch Twoich pojazdów.
Limity
| Limit | Wartość |
|---|---|
| Pozycje w jednym wywołaniu | najwyżej 500 i najwyżej 1 MB |
| Wywołania na klucz | 60 na minutę i 2 000 na godzinę |
| Czas z przyszłości | najwyżej 15 minut przed zegarem Quanty („sprawdź zegar nadawcy”) |
| Stare pozycje | nie starsze niż historia pozycji (90 dni) |
| Jednocześnie | jedno wywołanie na organizację; drugie dostaje odpowiedź „busy” z podpowiedzią, by spróbować ponownie za 2 sekundy |
Wysyłaj partie po kilkaset pozycji, dla każdego pojazdu w kolejności czasu. Pojazd jest W trasie od 3 km/h, poniżej tej prędkości ma stan Postój, a Brak sygnału, gdy jego ostatni raport jest starszy niż 6 godzin. Przebieg pojazdu TMS tylko rośnie, więc wysyłaj prawdziwe odczyty.
Odpowiedź
Quanty odpowiada 200, gdy zapisano co najmniej jedną pozycję, z polami:
| Pole | Znaczenie |
|---|---|
accepted | Przyjęte pozycje. |
positions_added | Pozycje dodane do historii. |
older_than_stored | Pozycje starsze niż to, co pojazd już ma (przyjęte, ale niedodane do śladu). |
vehicles_linked | Numery rejestracyjne połączone z tym połączeniem przez to wywołanie. |
rejected | Każda odrzucona pozycja z jej index, powodem i polem. |
ignored | Pominięte wartości opcjonalne, z ich index i polem. |
Gdy nic nie zostało zapisane, odpowiedź ma ten sam kształt i status odrzuceń (404, 409 albo 422).
| Problem | Odpowiedź |
|---|---|
| Brak klucza, nieznany albo unieważniony klucz | 401 |
| Organizacja nie ma dodatku TMS albo jej plan jest nieopłacony | 402 |
| Klucz nie ma dostępu Telematyka: wysyłanie | 403 |
| Własny system (API) nie jest połączony albo jest wstrzymany | 409 |
| Wywołanie jest za duże | 413 |
To nie JSON, brak items albo więcej niż 500 | 422 |
| Za dużo wywołań albo trwa jeszcze inne wywołanie | 429 (odczekaj i wyślij ponownie) |
Pojedyncza pozycja może zostać odrzucona z powodu: nieznanego id pojazdu (404), pojazdu, który nie jest jednoznaczny albo jest zasilany przez inną telematykę (409), czasu z przyszłości albo starszego niż historia, albo brakującego lub błędnego pola (422).
Trzymaj klucz w tajemnicy
Klucz pozwala każdemu, kto go ma, wysyłać pozycje Twoich pojazdów. Trzymaj go tylko w systemie wysyłającym, a jeśli mógł wyciec, unieważnij go w ustawieniach TMS.
Warto wiedzieć
- Wstrzymanie połączenia odrzuca nowe pozycje, dopóki go nie wznowisz; wiersz pokazuje wtedy Odbiór danych: Wstrzymano.
- Usunięcie połączenia kasuje jego historię pozycji i odłącza pojazdy TMS; pozycje wysłane później są odrzucane.
- Pozycje z Twojego systemu pojawiają się na mapie floty w ciągu 30 sekund i liczą się do kilometrów zleceń i kart drogowych jak pozycje od każdego dostawcy.
Powiązane strony
- Łączenie telematyki: dostawcy, których Quanty czyta samo.
- Pozycje i mapa floty: gdzie pokazują się pozycje.
- Ustawienia TMS: klucze API i webhooki.
- Dokumentacja API: pełne wywołanie i odpowiedź.