Dokumentacja API

Z dodatkiem TMS inny Twój system (narzędzie BI, program księgowy, platforma do śledzenia przesyłek) może czytać przez API TMS zlecenia, kontrahentów, pojazdy i faktury Twojej organizacji, a Twój własny system telematyki może wysyłać pozycje pojazdów. Słowami aplikacji: „Klucz pozwala innemu systemowi czytać dane TMS, na przykład zlecenia do raportów, albo wysyłać pozycje pojazdów z jego telematyki. Poza tymi pozycjami nic nie zmienia.”

Z całej reszty Quanty korzystasz przez aplikację pod adresem app.quanty.ai. Wewnętrzne API aplikacji nie jest udostępniane do integracji: wymaga zalogowanej sesji i zmienia się bez zapowiedzi.

Zanim zaczniesz

• Organizacja ma dodatek TMS i opłacony plan. Bez dodatku każde zapytanie jest odrzucane kodem addon_required, a gdy plan nie jest opłacony, kodem payment_required.
• Klucze API tworzy i unieważnia tylko administrator organizacji, w Ustawieniach TMS, API i webhooki.
• System, który woła API, potrzebuje klucza, adresu Twojego API Quanty (jest w przykładzie w oknie klucza) i tej strony.

Klucze API

1. Otwórz Ustawienia TMS, API i webhooki i kliknij Utwórz klucz w części Klucze API.
2. Wypełnij okno i kliknij Utwórz klucz.
3. Klucz widać tylko raz, z Kopiuj i Przykład: pierwsze 50 zleceń (Kopiuj przykład): „Ten klucz pokazujemy tylko raz. Na liście zostaje tylko jego początek; jeśli zginie, unieważnij go i utwórz nowy.”
4. Wklej klucz w systemie, który będzie go używał, i kliknij Gotowe.

Lista kluczy pokazuje Nazwa, Dostęp, Utworzony, Ostatnio użyty („jeszcze nie” do pierwszego zapytania) i Stan: Aktywny albo Unieważniony (z tym, kto go unieważnił). Unieważnij w menu klucza zatrzymuje go od razu: „Systemy, które go używają, od razu stracą dostęp. Tego nie da się cofnąć.”

Odczyt danych

Użyj adresu z przykładu w oknie klucza i wyślij klucz jako token typu Bearer:

GET /api/v1/ext/tms/orders?limit=50
Authorization: Bearer qk_…

Parametry zapytania

Strony i odpytywanie

Odpowiedź to jedna strona, od najstarszej zmiany:

{
  "items": [ { "id": "…", "number": "…", "updated_at": "…" } ],
  "next_cursor": "…"
}

1. Przeczytaj pierwszą stronę, z updated_since, jeśli chcesz tylko ostatnich zmian.
2. Dopóki next_cursor nie jest null, czytaj dalej z cursor ustawionym na tę wartość (z tym samym updated_since).
3. Żeby później sprawdzić zmiany, zacznij następny odczyt z updated_since kilka minut przed czasem ostatniego odczytu.

Wiersze zmienione w ostatnich 10 sekundach nie są jeszcze podawane; przyjdą przy następnym odczycie i dlatego odpytywanie cofa się o kilka minut. Wiersze z tym samym updated_at nigdy nie są pomijane ani powtarzane między stronami. Usuniętych wierszy nie ma; anulowane zachowują swój status. Odpowiedzi nigdy nie są zapisywane w pamięci podręcznej.

Pola

Każdy wiersz ma id, created_at i updated_at oraz pola odpowiedniej tabeli w TMS dane (zobacz Tabele w Quanty). Kwoty i inne liczby dziesiętne przychodzą jako tekst ("1234.50"), liczby całkowite jako liczby, daty jako YYYY-MM-DD (dzień w czasie polskim), momenty w UTC, a wybory jako kody. Wartość nieustawiona to null.

orders (zlecenia)

contractors (kontrahenci)

vehicles (pojazdy)

invoices (faktury)

API nie podaje uwag wewnętrznych, plików, identyfikatorów osób ani współrzędnych. Rekordy z Marcos TMS są w odpowiedzi jak wszystkie inne.

Błędy

Odmowa ma kod i zdanie (error_code, message), nigdy nic z klucza.

Limity

Cudze złe klucze nigdy nie spowalniają poprawnego klucza.

Wysyłanie pozycji pojazdów

Dla telematyki, której Quanty nie czyta samo, Twój własny system może wysyłać pozycje. Cała instrukcja, z każdym polem, dopasowaniem pojazdów i wszystkimi odpowiedziami, jest na stronie Własny system (API). W skrócie:

1. Administrator łączy Własny system (API) w Telematyce: „Nic tu nie trzeba wpisywać.” Połączenie pokazuje Odbiór danych: Przez API, Ostatnie dane oraz Jak wysyłać dane z adresem, potrzebnym kluczem i przykładowym wywołaniem.
2. Utwórz klucz API z Telematyka: wysyłanie.
3. Twój system wysyła pozycje:

POST /api/v1/ext/tms/telematics/positions
Authorization: Bearer qk_…
Content-Type: application/json

{
  "items": [
    {
      "vehicle": { "plate": "PO 1AB12" },
      "at": "2026-11-01T10:00:00Z",
      "lat": 52.40,
      "lng": 16.92,
      "speed_kmh": 82,
      "heading": 270,
      "odometer_km": 423434.5,
      "fuel_pct": 61,
      "fuel_l": 410,
      "driver": { "id": "D-17", "name": "Jan Kowalski" },
      "trailer": { "plate": "PO 9TR" }
    }
  ]
}

• vehicle wskazuje pojazd jego id w Quanty, numerem vin albo numerem rejestracyjnym plate. Pojazd bez telematyki zostaje połączony przy pierwszej pozycji; pojazd, który bierze pozycje z innego połączenia telematyki, jest dla tej pozycji odrzucany.
• at to moment ISO (bez strefy czytany jako UTC) albo sekundy Unix; czas o więcej niż 15 minut przed zegarem Quanty jest odrzucany, więc sprawdź zegar nadawcy. lat i lng są wymagane, reszta jest opcjonalna. Imię i nazwisko kierowcy to dane osobowe, jak przy każdej telematyce.
• Pole, którego pozycja nie ma, zostawia ostatnią wartość pojazdu (paliwo, kierowca), a null je czyści. Przebieg w pojeździe tylko rośnie, więc wysyłaj prawdziwy odczyt. Opcjonalna wartość, która nie jest odczytem (prędkość -1, przebieg 0, paliwo "n/a"), jest pomijana i wymieniona w ignored; pozycja i tak się liczy.

Odpowiedź to 200, gdy zapisano co najmniej jedną pozycję:

{
  "accepted": 1,
  "positions_added": 1,
  "older_than_stored": 0,
  "vehicles_linked": 0,
  "rejected": [ { "index": 3, "status": 404, "error_code": "…", "message": "…" } ],
  "ignored": [ { "index": 0, "field": "speed_kmh" } ]
}

Każda pozycja ma własną odpowiedź: odrzucona trafia do rejected ze swoim numerem, a pozostałe są zapisywane. To samo wywołanie wysłane dwa razy zapisuje się raz, a odczyt starszy niż najnowszy odczyt pojazdu trafia do jego śladu, nie cofając pojazdu.

Całe wywołanie jest odrzucane:

Inne sposoby przenoszenia danych

• Arkusze Google: importuj wiersze z arkusza Google według harmonogramu, z kolumną klucza przeciw duplikatom, albo eksportuj tabelę w drugą stronę.
• Eksport: każdą tabelę wyeksportujesz do CSV, Excela albo PDF z Więcej działań w arkuszu (zobacz Projekty, tabele i widoki), a listy i raporty TMS mają własny eksport.
• Automatyzacje (beta): zamieniaj e-maile, wiadomości WhatsApp i faktury z KSeF w rekordy tabeli i reaguj na nowe i zmienione rekordy.
• Linki do udostępniania: pulpity i prezentacje można udostępniać tylko do odczytu za pomocą linku (zobacz Pulpity i Prezentacje).

Pytania o API: support@quanty.ai.