SaveTrack API

Začínáme

SaveTrack API zpřístupňuje data vaší flotily dalším systémům: účetnictví, ERP, mzdám nebo vlastnímu reportingu. Je to REST API nad HTTPS, odpovědi jsou v JSON a celé API je popsané ve standardu OpenAPI 3.1. Verze v1 je jen pro čtení, data v SaveTracku nemění.

1. Přihlaste se do SaveTracku hlavním účtem a otevřete Nastavení → API.
2. Klíč pojmenujte (např. „Pohoda“), vyberte oprávnění a potvrďte ho heslem k účtu a kryptoheslem.
3. Klíč se zobrazí pouze jednou. Uložte ho do svého systému jako tajemství, ne do zdrojového kódu.
4. Pošlete první požadavek, například seznam vozidel (příklady níže).

Autentizace

Každý požadavek musí obsahovat klíč v hlavičce Authorization:

Authorization: Bearer st_live_…

Klíč v adrese (např. ?api_key=) API odmítne, protože adresy se ukládají do logů a historie prohlížeče. Klíč patří k účtu, který ho vytvořil. Vidí jen data tohoto účtu.

Výměna klíče: vytvořte nový klíč, nastavte ho ve svém systému a starý potom zrušte. Zrušení platí okamžitě.

Oprávnění

U nového klíče jsou zapnutá všechna kromě adresy:read. Klíči dejte jen ta, která váš systém potřebuje. Endpoint /ucet nepotřebuje žádné oprávnění.

Šifrované údaje a adresy

SaveTrack ukládá SPZ, jména řidičů a polohy šifrované klíčem, který se odemyká vaším kryptoheslem. Kryptoheslo při vytvoření klíče odemkne kopii šifrovacího klíče, která je vázaná na tento API klíč. API proto vrací tyto údaje čitelné. Kryptoheslo se nikde neukládá a po zrušení API klíče se jeho kopie šifrovacího klíče smaže.

U soukromých jízd API adresy ani souřadnice nikdy nevrací, pole mají hodnotu null. Tak to vyžaduje i ochrana osobních údajů řidiče.

Stránkování a synchronizace

Seznamy vracejí nejvýše limit záznamů (1–200, výchozí 100) seřazených podle ID a pole next_od_id. Další stránku získáte tak, že jeho hodnotu pošlete jako od_id. Když je next_od_id rovno null, jste na konci.

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

Pro průběžnou synchronizaci použijte zmenene_od. Vrátí jen záznamy změněné od daného času, např. /jazdy?zmenene_od=2026-11-01T00:00:00+01:00. Uložte si čas začátku synchronizace a při další ho pošlete. Jízdy lze dále filtrovat přes od, do (datum začátku jízdy), vozidlo_id a vodic_id.

/kniha-jazd nestránkuje. Vrátí celé období jednoho vozidla (nejvýše 1 rok) s pořadovými čísly jízd, stavem tachometru na začátku a konci období a souhrnem km podle typu jízdy.

Chyby

Při chybě API vrátí HTTP stav a vždy stejný tvar těla:

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

Každá odpověď má hlavičku X-Request-Id. Když nás kontaktujete kvůli konkrétnímu požadavku, pošlete nám ji.

Limity

Odpovědi obsahují hlavičky X-RateLimit-Limit a X-RateLimit-Remaining. API je součástí služby SaveTrack bez příplatku.

Příklady

Klíč mějte v proměnné prostředí SAVETRACK_API_KEY.

První požadavek: seznam vozidel

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

<?php
$response = file_get_contents('https://admin.savetrack.cz/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.cz/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 měsíc

curl -s "https://admin.savetrack.cz/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.cz/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.cz/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"])

Průběžná synchronizace se stránkováním a limity

import os, time, requests

BASE = "https://admin.savetrack.cz/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 poslední úspěšné synchronizace
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.cz/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čnost

• Komunikace jde jen přes HTTPS. Klíč v databázi SaveTracku není, ukládáme pouze jeho otisk (SHA-256).
• Klíč vidí jen data svého účtu. Záznam jiného účtu vrátí 404, stejně jako neexistující.
• Vytvoření klíče potvrzuje heslo a kryptoheslo a majitel účtu o něm dostane e-mail.
• Každý požadavek zaznamenáváme (čas, cesta, stav, IP) 90 dní. Tělo odpovědi ani klíč se neukládají.
• Pokud máte podezření, že klíč unikl, okamžitě ho zrušte v Nastavení → API a vytvořte nový.

Změny

V rámci v1 přidáváme jen zpětně kompatibilní změny (nová pole, nové endpointy). Nekompatibilní změna dostane novou verzi v2 a v1 bude ještě nějakou dobu fungovat. Nová pole v odpovědích proto má váš systém ignorovat, ne odmítat.

Podpora

S napojením vám rádi pomůžeme. Napište na info@savetrack.sk nebo volejte +421 908 918 880. Uveďte, jaký systém připojujete, a při chybě i X-Request-Id. Strojově čitelná specifikace je na https://admin.savetrack.cz/api/openapi.json. Lze z ní vygenerovat klienta pro většinu jazyků nebo ji importovat do Postmanu či Insomnie.