SaveTrack API

Začíname

SaveTrack API sprístupňuje dáta vašej flotily ďalším systémom: účtovníctvu, ERP, mzdám alebo vlastnému reportingu. Je to REST API nad HTTPS, odpovede sú v JSON a celé API je opísané v štandarde OpenAPI 3.1. Verzia v1 je len na čítanie, dáta v SaveTracku nemení.

1. Prihláste sa do SaveTracku hlavným účtom a otvorte Nastavenia → API.
2. Kľúč pomenujte (napr. „Pohoda“), vyberte oprávnenia a potvrďte ho heslom do účtu a kryptoheslom.
3. Kľúč sa zobrazí iba raz. Uložte ho do svojho systému ako tajomstvo, nie do zdrojového kódu.
4. Pošlite prvý požiadavok, napríklad zoznam vozidiel (príklady nižšie).

Autentifikácia

Každý požiadavok musí obsahovať kľúč v hlavičke Authorization:

Authorization: Bearer st_live_…

Kľúč v adrese (napr. ?api_key=) API odmietne, lebo adresy sa ukladajú do logov a histórie prehliadača. Kľúč patrí k účtu, ktorý ho vytvoril. Vidí len dáta tohto účtu.

Výmena kľúča: vytvorte nový kľúč, nastavte ho vo svojom systéme a starý potom zrušte. Zrušenie platí okamžite.

Oprávnenia

Pri novom kľúči sú zapnuté všetky okrem adresy:read. Kľúču dajte len tie, ktoré váš systém potrebuje. Endpoint /ucet nepotrebuje žiadne oprávnenie.

Šifrované údaje a adresy

SaveTrack ukladá ŠPZ, mená vodičov a polohy šifrované kľúčom, ktorý sa odomyká vaším kryptoheslom. Kryptoheslo pri vytvorení kľúča odomkne kópiu šifrovacieho kľúča, ktorá je viazaná na tento API kľúč. API preto vracia tieto údaje čitateľné. Kryptoheslo sa nikde neukladá a po zrušení API kľúča sa jeho kópia šifrovacieho kľúča zmaže.

Pri súkromných jazdách API adresy ani súradnice nikdy nevracia, polia majú hodnotu null. Takto to vyžaduje aj ochrana osobných údajov vodiča.

Stránkovanie a synchronizácia

Zoznamy vracajú najviac limit záznamov (1–200, predvolene 100) zoradených podľa ID a pole next_od_id. Ďalšiu stránku získate tak, že jeho hodnotu pošlete ako od_id. Keď je next_od_id rovné null, ste na konci.

{
  "data": [ … ],
  "next_od_id": "9QzL0bW1xY"
}

Na priebežnú synchronizáciu použite zmenene_od. Vráti len záznamy zmenené od daného času, napr. /jazdy?zmenene_od=2026-11-01T00:00:00+01:00. Uložte si čas začiatku synchronizácie a pri ďalšej ho pošlite. Jazdy sa dajú ďalej filtrovať cez od, do (dátum začiatku jazdy), vozidlo_id a vodic_id.

/kniha-jazd nestránkuje. Vráti celé obdobie jedného vozidla (najviac 1 rok) s poradovými číslami jázd, stavom tachometra na začiatku a konci obdobia a súhrnom km podľa typu jazdy.

Chyby

Pri chybe API vráti HTTP stav a vždy rovnaký tvar tela:

{
  "error": "The given data was invalid.",
  "code": "validation_failed",
  "fields": { "od": ["The od field is required."] }
}

Každá odpoveď má hlavičku X-Request-Id. Keď nás kontaktujete kvôli konkrétnemu požiadavku, pošlite nám ju.

Limity

Odpovede obsahujú hlavičky X-RateLimit-Limit a X-RateLimit-Remaining. API je súčasťou služby SaveTrack bez príplatku.

Príklady

Kľúč majte v premennej prostredia SAVETRACK_API_KEY.

Prvý požiadavok: zoznam vozidiel

curl -s "https://admin.savetrack.sk/api/v1/vozidla" \
  -H "Authorization: Bearer $SAVETRACK_API_KEY"

<?php
$response = file_get_contents('https://admin.savetrack.sk/api/v1/vozidla', false, stream_context_create([
    'http' => ['header' => 'Authorization: Bearer ' . getenv('SAVETRACK_API_KEY'), 'ignore_errors' => true],
]));
$vehicles = json_decode($response, true)['data'];

import os, requests

r = requests.get("https://admin.savetrack.sk/api/v1/vozidla",
                 headers={"Authorization": f"Bearer {os.environ['SAVETRACK_API_KEY']}"}, timeout=30)
r.raise_for_status()
vehicles = r.json()["data"]

Kniha jázd vozidla za mesiac

curl -s "https://admin.savetrack.sk/api/v1/kniha-jazd?vozidlo_id=4fK2pQ9xZa&od=2026-10-01&do=2026-10-31" \
  -H "Authorization: Bearer $SAVETRACK_API_KEY"

<?php
$query = http_build_query(['vozidlo_id' => '4fK2pQ9xZa', 'od' => '2026-10-01', 'do' => '2026-10-31']);
$book = json_decode(file_get_contents('https://admin.savetrack.sk/api/v1/kniha-jazd?' . $query, false, stream_context_create([
    'http' => ['header' => 'Authorization: Bearer ' . getenv('SAVETRACK_API_KEY')],
])), true)['data'];

printf("Business: %.1f km, private: %.1f km\n", $book['summary']['business_km'], $book['summary']['private_km']);

HEADERS = {"Authorization": f"Bearer {os.environ['SAVETRACK_API_KEY']}"}
book = requests.get("https://admin.savetrack.sk/api/v1/kniha-jazd",
                    params={"vozidlo_id": "4fK2pQ9xZa", "od": "2026-10-01", "do": "2026-10-31"},
                    headers=HEADERS, timeout=60).json()["data"]
print(book["summary"]["business_km"], book["odometer_start_km"], book["odometer_end_km"])

Priebežná synchronizácia so stránkovaním a limitmi

import os, time, requests

BASE = "https://admin.savetrack.sk/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SAVETRACK_API_KEY']}"}

def fetch_all(resource, **params):
    params = {"limit": 200, **params}
    while True:
        r = requests.get(f"{BASE}/{resource}", params=params, headers=HEADERS, timeout=30)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        if not body["next_od_id"]:
            return
        params["od_id"] = body["next_od_id"]

last_sync = load_last_sync()          # čas poslednej úspešnej synchronizácie
for trip in fetch_all("jazdy", zmenene_od=last_sync):
    upsert_trip(trip["id"], trip)

<?php
function fetchAll(string $resource, array $params = []): Generator
{
    $params += ['limit' => 200];
    while (true) {
        $ctx = stream_context_create(['http' => [
            'header' => 'Authorization: Bearer ' . getenv('SAVETRACK_API_KEY'),
            'ignore_errors' => true,
        ]]);
        $body = json_decode(file_get_contents('https://admin.savetrack.sk/api/v1/' . $resource . '?' . http_build_query($params), false, $ctx), true);
        if (($body['code'] ?? null) === 'rate_limited') {
            sleep(60);
            continue;
        }
        yield from $body['data'];
        if (! $body['next_od_id']) {
            return;
        }
        $params['od_id'] = $body['next_od_id'];
    }
}

foreach (fetchAll('tankovania', ['od' => '2026-10-01', 'do' => '2026-10-31']) as $refueling) {
    importRefueling($refueling['id'], $refueling['price_cents'] / 100, $refueling['currency']);
}

Bezpečnosť

• Komunikácia ide len cez HTTPS. Kľúč v databáze SaveTracku nie je, ukladáme iba jeho odtlačok (SHA-256).
• Kľúč vidí len dáta svojho účtu. Záznam iného účtu vráti 404, rovnako ako neexistujúci.
• Vytvorenie kľúča potvrdzuje heslo a kryptoheslo a majiteľ účtu dostane o ňom e-mail.
• Každý požiadavok zaznamenávame (čas, cesta, stav, IP) 90 dní. Telo odpovede ani kľúč sa neukladajú.
• Ak máte podozrenie, že kľúč unikol, okamžite ho zrušte v Nastavenia → API a vytvorte nový.

Zmeny

V rámci v1 pridávame len spätne kompatibilné zmeny (nové polia, nové endpointy). Nekompatibilná zmena dostane novú verziu v2 a v1 bude ešte istý čas fungovať. Nové polia v odpovediach preto váš systém má ignorovať, nie odmietať.

Podpora

S napojením vám radi pomôžeme. Napíšte na info@savetrack.sk alebo volajte +421 908 918 880. Uveďte, aký systém pripájate, a pri chybe aj X-Request-Id. Strojovo čitateľná špecifikácia je na https://admin.savetrack.sk/api/openapi.json. Dá sa z nej vygenerovať klient pre väčšinu jazykov alebo ju importovať do Postmana či Insomnie.