API dokumentácia

Kniha jázd, náklady a prílohy pre účtovný softvér.

Verzia 1.0.0, formát OpenAPI 3.1. Referencia nižšie sa generuje priamo z tohto dokumentu, takže nemôže zaostať za správaním servera.

REST · JSONOpenAPI 3.119 koncových bodovBearer alebo HTTP Basic

OpenAPI dokument Vytvoriť API token Podpora

Základná adresa: https://ecesty.sk
Formát: JSON · OpenAPI 3.1
Autentizácia: Bearer alebo HTTP Basic
Koncové body: 19 koncových bodov

Obsah dokumentácie

Začíname

Integrácia potrebuje tri veci: token, jedno overovacie volanie a správne stránkovanie. Zvyšok je čítanie a zápis vo vašom vozovom parku.

1
Vytvorte si token
Prihláste sa ako majiteľ účtu a otvorte „Integrácie a automatizácia“ → API tokeny. Zvoľte rozsah (iba čítanie alebo čítanie a zápis) a token si hneď skopírujte — zobrazí sa iba raz. Platí 365 dní, naraz môžete mať najviac 10 aktívnych tokenov.
2
Overte prihlasovacie údaje
Najlacnejšie volanie: /me vráti účet, na ktorý token ukazuje, a rozsah tokenu. Ak dostanete 401, token je nesprávny, zrušený alebo vypršal.
```
curl "https://ecesty.sk/api/v1/me" \
  -H "Authorization: Bearer ec_live_…"
```
3
Načítajte prvé dáta
Zoznamy sú stránkované. Keď je meta.has_next pravdivé, pošlite ďalšiu požiadavku s meta.next_cursor.
```
curl "https://ecesty.sk/api/v1/vehicles?limit=50" \
  -H "Authorization: Bearer ec_live_…"
```
4
Importujte OpenAPI
Strojový popis je dostupný bez prihlásenia a je vhodný na import do Postmana, Insomnie alebo generátora klienta.
```
curl "https://ecesty.sk/api/v1/openapi" -o ecesty-openapi.json
```

Autentizácia

Prihlasovacie údaje sú API token v tvare ec_live_ + 64 hexadecimálnych znakov. Podporované sú dve hlavičky nad tým istým tokenom:

Authorization: Bearer ec_live_… — odporúčané.
Authorization: Basic base64("<e-mail účtu>:<token>") — pre systémy, ktoré vedia iba Basic; base64("<token>:") je tiež prijaté. Heslo k účtu sa na API nikdy nepoužíva.
Pri Basic sa e-mail overuje voči účtu tokenu. Nesúlad vráti 401 invalid_token.
Chýbajúci alebo neplatný token vráti 401 s WWW-Authenticate: Bearer realm="ecesty.sk".

Bearer (odporúčané)

Authorization: Bearer ec_live_…

HTTP Basic (kompatibilita)

Authorization: Basic base64("meno@firma.sk:ec_live_…")

Životný cyklus tokenu

Kde ho vytvoríte: Dashboard → Integrácie a automatizácia → API tokeny.
Kto ho môže vytvoriť: Iba rola owner. Vodič ani administrátor si token nevytvorí.
Platnosť: 365 dní od vytvorenia.
Maximálne aktívnych tokenov: 10
Rozsahy: read · write
Zrušenie: Zrušenie je okamžité a nevratné; ďalšie volanie vráti 401 token_revoked.
Zobrazenie hodnoty: Token sa zobrazí iba raz pri vytvorení; databáza drží iba SHA-256 digest.

Rozsahy tokenu

Token má jeden rozsah. read dovolí všetky volania GET; write dovolí aj POST, PATCH a DELETE. Zápis s tokenom read nie je ticho ignorovaný — vráti 403 forbidden_scope, aby integrácia ani jej používateľ nenadobudli dojem, že zmena prešla.

Iba server–server

Každá požiadavka okrem dokumentu OpenAPI, ktorá prinesie hlavičku Origin, je odmietnutá s 403 browser_clients_not_supported ešte pred overením tokenu. API zámerne nemá CORS politiku — token by sa v prehliadači dostal do dosahu skriptov stránky. Výnimkou je samotný dokument OpenAPI: je verejný, cachuje sa 5 minút a posiela Access-Control-Allow-Origin: *.

Konvencie a limity

Obal odpovedí

Úspech je vždy { "data": … }, zoznamy navyše nesú meta. Chyba je vždy { "error": { "code", "message", "details"? } }. message je slovenský text pre človeka, code je stabilný strojový identifikátor — riadte sa ním, nie textom.

HTTP stav nesie význam — úspech aj chyba majú vlastný kód, nie vždy 200.
Všetky odpovede majú Cache-Control: no-store okrem dokumentu OpenAPI, ktorý sa cachuje 5 minút.
Neznáme polia vo vstupe sa odmietnu (422) — posielajte iba polia uvedené v schéme; chýbajúce povinné pole vráti 422 s details.

Stránkovanie

Kurzorové stránkovanie bez počítania riadkov: server načíta limit + 1 záznamov a zvyšný riadok dokazuje, že existuje ďalšia strana. Poradie je vždy od najnovšieho (created_at a id zostupne).

limit 1–200, predvolene 50; mimo rozsahu vráti 422 validation_error.
cursor preberajte výhradne z meta.next_cursor; poškodený kurzor vráti 400 invalid_cursor.
Pri súbežnom zápise nové záznamy pribúdajú na začiatok a stránky sa posúvajú iba vpred — preto kurzor zostáva stabilný.

Dátumy, časy a časové pásma

trip_date je kalendárny dátum. start_time/end_time pri vytváraní cesty zadávate ako HH:MM; server z nich spolu s trip_date a poľom timezone (IANA, predvolene Europe/Bratislava) vytvorí časovú pečiatku, ktorú potom vracia v odpovedi. expense_date prijíma YYYY-MM-DD alebo plný ISO-8601 čas; samotný dátum znamená polnoc UTC. Budúci dátum cesty je odmietnutý (422).

Dôsledky zápisu

Cesty sa neodstraňujú natrvalo, iba mäkko: DELETE vyžaduje delete_reason, záznam zostane v archíve a vo výkazoch sa ďalej zobrazí ako vymazaný, takže daňová evidencia zostáva zachovaná. Náklady sa odstraňujú natrvalo vrátane príloh. Každý zápis vytvára záznam v auditnom logu (system_events) s identifikátorom volajúceho účtu, takže spätne je dohľadateľné, ktorá integrácia zmenu vykonala.

Úprava cesty vyžaduje edit_reason a zapisuje novú verziu do trip_versions s dôvodom aj aktérom.
Vymazaná cesta sa v zoznamoch ani v detaile nevracia (GET, PATCH aj DELETE vracajú 404); jej história zostáva v databáze a vo výkazoch.
Vozidlo cesty je po vytvorení nemenné; dátum, časy, vodiča a ostatné polia meníte cez PATCH s dôvodom.

Limity požiadaviek

Limity platia pre každú IP adresu a pre každý token samostatne; odpoveď 429 vždy nesie hlavičku Retry-After.

Rozsah	Limit	Platí	Poznámka
IP adresa	3600 požiadaviek / 60 s	Pred overením tokenu, na každú požiadavku.	Chráni server pred neautentizovaným zahltením. Pri prekročení: 429 len pre túto IP.
API token	120 požiadaviek / 60 s	Po overení tokenu, na každý token samostatne.	Odpoveď nesie hlavičku `Retry-After` v sekundách. Pre dávkový import používajte `limit=200` a stránkujte, netlačte požiadavky opakovane.
Telo požiadavky	20 MB (produkcia) / 6 MB (dev)	`client_max_body_size` proxy stojaceho pred aplikáciou.	Prílohy: najviac 3 súbory a 5 MB celkovo na náklad. Nové súbory sa počítajú podľa veľkosti, v akej prišli (teda pred kompresiou); už uložené prílohy sa počítajú po kompresii.

Katalóg chýb

Riaďte sa poľom error.code, nie textom správy — správa je pre človeka a môže sa prekladať alebo spresňovať. Kódy sú stabilné.

Stav	Kód	Správa	Kedy
400	invalid_cursor	Neplatný kurzor.	Parameter `cursor` nie je platný base64url JSON alebo neobsahuje dátum a UUID.
401	unauthorized	Chýba autorizačná hlavička.	Požiadavka neposlala `Authorization`.
401	invalid_token	Neplatný API token.	Token nemá tvar `ec_live_` + 64 hex znakov, neexistuje, alebo sa e-mail v Basic autentizácii nezhoduje s účtom tokenu.
401	token_revoked	Tento API token bol odvolaný.	Token bol zrušený v dashboarde.
401	token_expired	Platnosť tohto API tokenu vypršala.	Od vytvorenia tokenu uplynulo viac ako 365 dní.
403	forbidden_scope	Tento token má prístup iba na čítanie.	Token s rozsahom `read` zavolal zápisovú operáciu (POST, PATCH, DELETE).
403	forbidden	Vozidlo alebo vodič nepatrí do vášho vozového parku.	`vehicle_id` alebo `driver_id` nie je z vozového parku tokenu, alebo vodič nie je priradený k vozidlu. Token bez roly `owner` (napríklad po zmene roly účtu) vráti rovnaký kód so správou „API tokeny môžu vytvárať a používať iba majitelia účtov.“
403	account_inactive	Účet je deaktivovaný.	Majiteľ účtu bol deaktivovaný; token prestal fungovať okamžite.
403	browser_clients_not_supported	Požiadavky z prehliadača nie sú podporované.	Požiadavka obsahovala hlavičku `Origin`. Odmieta sa pred overením tokenu.
404	not_found	Záznam neexistuje.	Záznam neexistuje, bol odstránený, alebo patrí inému majiteľovi.
422	validation_error	Neplatné údaje.	Chýba povinné pole, typ je nesprávny, hodnota je mimo rozsahu, alebo kombinácia porušuje pravidlo (napr. koniec pred začiatkom). Dôvody sú v `error.details`.
429	rate_limit_exceeded	Prekročený limit požiadaviek.	Prekročený limit na IP adresu (3600/min) alebo na token (120/min).
500	internal_error	Interná chyba servera.	Neočakávaná chyba; požiadavka nemusela prejsť. Bezpečné opakovať s odstupom.

Tvar chyby

{
  "error": {
    "code": "validation_error",
    "message": "Neplatné údaje.",
    "details": [
      { "field": "body", "message": "Parameter limit musí byť 1–200." }
    ]
  }
}

Referencia koncových bodov

Každý koncový bod môže vrátiť aj 401 a 429. Tie v kartách neuvádzame, aby neprekryli chyby špecifické pre daný koncový bod.

Účet

Overenie prihlasovacích údajov a informácie o účte.

1 koncový bod

GET/api/v1/me

Informácie o účte a tokene

Vráti účet, na ktorý token ukazuje, použitý rozsah a verziu API. Vhodné ako health-check integrácie pri štarte aj po výmene tokenu.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/me" \
  -H "Authorization: Bearer ec_live_…"

Odpoveď 200

Účet, rozsah tokenu a verzia API.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
account	objekt	povinné	Odpoveď `GET /me`. Najlacnejšie volanie na overenie prihlasovacích údajov: vráti účet, rozsah tokenu a verziu API
account.account	objekt	povinné	Majiteľ, ktorému token patrí. Všetky údaje sú z jeho profilu
account.token	objekt	povinné	Objekt zložený z polí nižšie
account.api_version	`v1`	povinné	Jedna z uvedených hodnôt
token	objekt	povinné	Objekt zložený z polí nižšie
token.scope	`read` \| `write`	povinné	Jedna z uvedených hodnôt
api_version	`v1`	povinné	Jedna z uvedených hodnôt

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Vozidlá

Vozový park majiteľa vrátane vyradených vozidiel.

2 koncové body

GET/api/v1/vehicles

Zoznam vozidiel

Vypíše všetky vozidlá majiteľa vrátane vyradených (disabled_at nie je null). Vyradené vozidlá sa zámerne nevynechávajú — pri dohľadávaní minulého obdobia potrebujete vozidlo, ktoré vtedy jazdilo.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/vehicles" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
limit	celé číslo	dotaz	voliteľné	Počet položiek na stranu. Predvolene 50, maximum 200; iná hodnota vráti 422
cursor	string	dotaz	voliteľné	Nepriehľadný kurzor z `meta.next_cursor` predchádzajúcej strany. Neupravujte ho — je to base64url dvojice `(created_at, id)`, ktorá určuje, odkiaľ pokračovať

Odpoveď 200

Strana vozidiel od najnovšieho; poradie podľa created_at, id.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
registration_number	string	povinné	Evidenčné číslo vozidla
vin	string · null	voliteľné	VIN
make	string · null	voliteľné	Značka
model	string · null	voliteľné	Model
year	celé číslo · null	voliteľné	Rok výroby
fuel_type	string · null	voliteľné	Palivo vedené v dashboarde (napr. `petrol`, `diesel`, `electric`)
emission_standard	string · null	voliteľné	Emisná norma
co2_grams_per_km_wltp	číslo · null	voliteľné	CO₂ WLTP v g/km
initial_odometer	číslo · null	voliteľné	Počiatočný stav kilometrov
current_odometer	číslo · null	voliteľné	Aktuálny stav kilometrov
date_added	dátum (YYYY-MM-DD) · null	voliteľné	Dátum zaradenia
disabled_at	čas (ISO-8601, UTC) · null	voliteľné	Kedy bolo vozidlo vyradené; `null` pre aktívne vozidlo
disabled_reason	string · null	voliteľné	Dôvod vyradenia
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
meta.limit	celé číslo	voliteľné	Veľkosť strany, ktorá bola naozaj použitá
meta.has_next	boolean	voliteľné	Existuje ďalšia strana
meta.next_cursor	string · null	voliteľné	Kurzor ďalšej strany, alebo `null` na poslednej strane

Chybové stavy

400Neplatný kurzor (invalid_cursor).
403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
422Parameter limit mimo rozsahu 1–200 (validation_error).

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

GET/api/v1/vehicles/{id}

Detail vozidla

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/vehicles/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Odpoveď 200

Vozidlo.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
registration_number	string	povinné	Evidenčné číslo vozidla
vin	string · null	voliteľné	VIN
make	string · null	voliteľné	Značka
model	string · null	voliteľné	Model
year	celé číslo · null	voliteľné	Rok výroby
fuel_type	string · null	voliteľné	Palivo vedené v dashboarde (napr. `petrol`, `diesel`, `electric`)
emission_standard	string · null	voliteľné	Emisná norma
co2_grams_per_km_wltp	číslo · null	voliteľné	CO₂ WLTP v g/km
initial_odometer	číslo · null	voliteľné	Počiatočný stav kilometrov
current_odometer	číslo · null	voliteľné	Aktuálny stav kilometrov
date_added	dátum (YYYY-MM-DD) · null	voliteľné	Dátum zaradenia
disabled_at	čas (ISO-8601, UTC) · null	voliteľné	Kedy bolo vozidlo vyradené; `null` pre aktívne vozidlo
disabled_reason	string · null	voliteľné	Dôvod vyradenia
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Vodiči

Aktívni vodiči priradení k vozidlám.

1 koncový bod

GET/api/v1/drivers

Zoznam vodičov

Aktívni vodiči priradení aspoň k jednému vozidlu majiteľa, zoradení podľa mena. Zoznam nie je stránkovaný — vráti sa celý. Deaktivovaný vodič sa nevráti a API ho neprijme pri zápise cesty ani nákladu.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/drivers" \
  -H "Authorization: Bearer ec_live_…"

Odpoveď 200

Všetci aktívni vodiči vozového parku.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
full_name	string	povinné	Meno a priezvisko
email	e-mail	povinné	E-mailová adresa
phone_number	string · null	voliteľné	Telefónne číslo z profilu

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Cesty

Kniha jázd — čítanie, zápis a úprava s históriou verzií.

5 koncových bodov

GET/api/v1/trips

Zoznam ciest

Odstránené cesty sa nevracajú. Filtre sa kombinujú logickým AND a from/to filtrujú trip_date. Poradie je od najnovšieho podľa created_at, nie podľa trip_date.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/trips?from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
vehicle_id	uuid	dotaz	voliteľné	Obmedzí výsledok na jedno vozidlo z vášho vozového parku
driver_id	uuid	dotaz	voliteľné	Obmedzí výsledok na jedného vodiča
from	dátum (YYYY-MM-DD)	dotaz	voliteľné	Dátum od (vrátane), formát `YYYY-MM-DD`
to	dátum (YYYY-MM-DD)	dotaz	voliteľné	Dátum do (vrátane), formát `YYYY-MM-DD`
limit	celé číslo	dotaz	voliteľné	Počet položiek na stranu. Predvolene 50, maximum 200; iná hodnota vráti 422
cursor	string	dotaz	voliteľné	Nepriehľadný kurzor z `meta.next_cursor` predchádzajúcej strany. Neupravujte ho — je to base64url dvojice `(created_at, id)`, ktorá určuje, odkiaľ pokračovať

Odpoveď 200

Strana ciest.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Vozidlo cesty
driver_id	uuid	voliteľné	Vodič, ktorému je cesta pripísaná
trip_date	dátum (YYYY-MM-DD)	povinné	Dátum cesty (`YYYY-MM-DD`)
start_location	string	voliteľné	Miesto začiatku
end_location	string	voliteľné	Miesto konca
distance_km	číslo	voliteľné	Vzdialenosť v kilometroch
start_time	čas (ISO-8601, UTC)	voliteľné	Čas začiatku (s dátumom)
end_time	čas (ISO-8601, UTC)	voliteľné	Čas konca (s dátumom)
start_timezone	string	voliteľné	IANA pásmo, v ktorom bol čas začiatku zadaný
end_timezone	string	voliteľné	IANA pásmo času konca
purpose	string	voliteľné	Účel cesty
odometer_start	číslo	voliteľné	Stav kilometrov na začiatku
odometer_end	číslo	voliteľné	Stav kilometrov na konci
notes	string · null	voliteľné	Poznámka
created_at	čas (ISO-8601, UTC)	voliteľné	Čas vzniku záznamu (UTC)
updated_at	čas (ISO-8601, UTC)	voliteľné	Čas poslednej zmeny (UTC)
meta.limit	celé číslo	voliteľné	Veľkosť strany, ktorá bola naozaj použitá
meta.has_next	boolean	voliteľné	Existuje ďalšia strana
meta.next_cursor	string · null	voliteľné	Kurzor ďalšej strany, alebo `null` na poslednej strane

Chybové stavy

400Neplatný kurzor (invalid_cursor).
403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
422Parameter limit mimo rozsahu 1–200 (validation_error).

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

POST/api/v1/tripsrozsah write

Vytvorenie cesty

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Ďalšie pravidlá: distance_km musí byť väčšia ako 0, odometer_end nesmie byť nižší ako odometer_start, end_time nesmie byť skorší ako start_time a trip_date nesmie byť v budúcnosti (v časovom pásme timezone). driver_id predvolene ukazuje na majiteľa účtu; iný vodič musí byť aktívne priradený k uvedenému vozidlu, inak operácia vráti 403 forbidden.

Ukážka požiadavky

curl -X POST "https://ecesty.sk/api/v1/trips" \
  -H "Authorization: Bearer ec_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "vehicle_id": "9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c",
  "trip_date": "2026-01-15",
  "start_time": "08:00",
  "end_time": "09:30",
  "start_location": "Bratislava",
  "end_location": "Nitra",
  "distance_km": 92.4,
  "odometer_start": 45120,
  "odometer_end": 45212,
  "purpose": "Obchodné rokovanie",
  "notes": "Cesta k dodávateľovi"
}'

Telo požiadavky · application/json

Pole	Typ	Povinné	Popis a obmedzenia
vehicle_id	uuid	povinné	Vozidlo z vášho vozového parku
driver_id	uuid	voliteľné	Vodič priradený k vozidlu. Predvolene majiteľ účtu
trip_date	dátum (YYYY-MM-DD)	povinné	Dátum cesty; nesmie byť v budúcnosti
start_location	string	povinné	Miesto začiatku · dĺžka 1–200
end_location	string	povinné	Miesto konca · dĺžka 1–200
distance_km	číslo	povinné	Vzdialenosť; musí byť väčšia ako 0 · nad 0 do 9999
start_time	string	povinné	Čas začiatku `HH:MM` v časovom pásme `timezone`
end_time	string	povinné	Čas konca `HH:MM`; nesmie byť skorší ako `start_time`
purpose	string	povinné	Účel cesty · dĺžka 1–500
odometer_start	číslo	povinné	Stav kilometrov na začiatku · 0 – 9999999
odometer_end	číslo	povinné	Stav kilometrov na konci; nie nižší ako `odometer_start` · 0 – 9999999
notes	string	voliteľné	Voliteľná poznámka · max. dĺžka 1000
timezone	string	voliteľné	IANA časové pásmo pre oba časy, napr. `Europe/Bratislava` · max. dĺžka 50 · predvolene `Europe/Bratislava`

Príklad tela

{
  "vehicle_id": "9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c",
  "trip_date": "2026-01-15",
  "start_time": "08:00",
  "end_time": "09:30",
  "start_location": "Bratislava",
  "end_location": "Nitra",
  "distance_km": 92.4,
  "odometer_start": 45120,
  "odometer_end": 45212,
  "purpose": "Obchodné rokovanie",
  "notes": "Cesta k dodávateľovi"
}

Odpoveď 201

Cesta vytvorená. Hlavička Location ukazuje na jej detail.

Hlavičky: Location

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Vozidlo cesty
driver_id	uuid	voliteľné	Vodič, ktorému je cesta pripísaná
trip_date	dátum (YYYY-MM-DD)	povinné	Dátum cesty (`YYYY-MM-DD`)
start_location	string	voliteľné	Miesto začiatku
end_location	string	voliteľné	Miesto konca
distance_km	číslo	voliteľné	Vzdialenosť v kilometroch
start_time	čas (ISO-8601, UTC)	voliteľné	Čas začiatku (s dátumom)
end_time	čas (ISO-8601, UTC)	voliteľné	Čas konca (s dátumom)
start_timezone	string	voliteľné	IANA pásmo, v ktorom bol čas začiatku zadaný
end_timezone	string	voliteľné	IANA pásmo času konca
purpose	string	voliteľné	Účel cesty
odometer_start	číslo	voliteľné	Stav kilometrov na začiatku
odometer_end	číslo	voliteľné	Stav kilometrov na konci
notes	string · null	voliteľné	Poznámka
created_at	čas (ISO-8601, UTC)	voliteľné	Čas vzniku záznamu (UTC)
updated_at	čas (ISO-8601, UTC)	voliteľné	Čas poslednej zmeny (UTC)

Chybové stavy

403Token nemá rozsah write (forbidden_scope), účet je neaktívny, alebo vozidlo či vodič nepatrí do vozového parku (forbidden).
422Neplatné údaje alebo kombinácia zakázaná pravidlami. Dôvody sú v error.details.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

GET/api/v1/trips/{id}

Detail cesty

Odstránená cesta vráti 404 — história zostáva v databáze, ale nie v API.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/trips/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Odpoveď 200

Cesta.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Vozidlo cesty
driver_id	uuid	voliteľné	Vodič, ktorému je cesta pripísaná
trip_date	dátum (YYYY-MM-DD)	povinné	Dátum cesty (`YYYY-MM-DD`)
start_location	string	voliteľné	Miesto začiatku
end_location	string	voliteľné	Miesto konca
distance_km	číslo	voliteľné	Vzdialenosť v kilometroch
start_time	čas (ISO-8601, UTC)	voliteľné	Čas začiatku (s dátumom)
end_time	čas (ISO-8601, UTC)	voliteľné	Čas konca (s dátumom)
start_timezone	string	voliteľné	IANA pásmo, v ktorom bol čas začiatku zadaný
end_timezone	string	voliteľné	IANA pásmo času konca
purpose	string	voliteľné	Účel cesty
odometer_start	číslo	voliteľné	Stav kilometrov na začiatku
odometer_end	číslo	voliteľné	Stav kilometrov na konci
notes	string · null	voliteľné	Poznámka
created_at	čas (ISO-8601, UTC)	voliteľné	Čas vzniku záznamu (UTC)
updated_at	čas (ISO-8601, UTC)	voliteľné	Čas poslednej zmeny (UTC)

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

PATCH/api/v1/trips/{id}rozsah write

Úprava cesty

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Meniť sa dá to isté, čo vo formulári v dashboarde: dátum, časy a časové pásma, vodič, miesta, vzdialenosť, účel, kilometre a poznámky. Vozidlo ostáva po vytvorení nemenné — iné vozidlo znamená novú cestu. Časy posielate ako HH:MM a kombinujú sa s trip_date; ak zmeníte iba dátum, časy sa posunú na nový dátum a ponechajú si hodinu. edit_reason je povinný: bez neho sa úprava nevykoná (422), rovnako ako v dashboarde. Každá úprava zapíše novú verziu do trip_versions s dôvodom aj účtom, ktorý zmenu vykonal. Kontroly vzdialenosti a kilometrov sa vyhodnocujú nad zlúčeným záznamom (existujúce hodnoty + zmena), takže čiastočná úprava nevytvorí stav, ktorý by odmietlo vytvorenie cesty. Odstránená cesta vráti 404, rovnako ako pri čítaní.

Ukážka požiadavky

curl -X PATCH "https://ecesty.sk/api/v1/trips/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "trip_date": "2026-08-01",
  "start_time": "08:15",
  "purpose": "Obchodné rokovanie v Nitre",
  "edit_reason": "Spresnenie účelu"
}'

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Telo požiadavky · application/json

Pole	Typ	Povinné	Popis a obmedzenia
trip_date	dátum (YYYY-MM-DD)	voliteľné	Nový dátum cesty; existujúce časy sa posunú na tento deň
driver_id	uuid	voliteľné	Iný vodič priradený k vozidlu cesty
start_location	string	voliteľné	Miesto začiatku cesty · dĺžka 1–200
end_location	string	voliteľné	Miesto konca cesty · dĺžka 1–200
distance_km	číslo	voliteľné	Najazdená vzdialenosť v kilometroch · nad 0 do 9999
start_time	string	voliteľné	Čas začiatku v tvare `HH:MM`, kombinuje sa s `trip_date`
start_timezone	string	voliteľné	Časové pásmo začiatku (IANA) · max. dĺžka 50
end_time	string	voliteľné	Čas konca v tvare `HH:MM`, kombinuje sa s `trip_date`
end_timezone	string	voliteľné	Časové pásmo konca (IANA) · max. dĺžka 50
purpose	string	voliteľné	Účel cesty · dĺžka 1–500
odometer_start	číslo	voliteľné	Stav počítadla kilometrov na začiatku · 0 – 9999999
odometer_end	číslo	voliteľné	Stav počítadla kilometrov na konci · 0 – 9999999
notes	string	voliteľné	Poznámky; prázdny reťazec pole vyprázdni · max. dĺžka 1000
edit_reason	string	povinné	Povinný dôvod úpravy, zapisuje sa do histórie verzií (`trip_versions`) · dĺžka 1–500

Príklad tela

{
  "trip_date": "2026-08-01",
  "start_time": "08:15",
  "purpose": "Obchodné rokovanie v Nitre",
  "edit_reason": "Spresnenie účelu"
}

Odpoveď 200

Upravená cesta.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Vozidlo cesty
driver_id	uuid	voliteľné	Vodič, ktorému je cesta pripísaná
trip_date	dátum (YYYY-MM-DD)	povinné	Dátum cesty (`YYYY-MM-DD`)
start_location	string	voliteľné	Miesto začiatku
end_location	string	voliteľné	Miesto konca
distance_km	číslo	voliteľné	Vzdialenosť v kilometroch
start_time	čas (ISO-8601, UTC)	voliteľné	Čas začiatku (s dátumom)
end_time	čas (ISO-8601, UTC)	voliteľné	Čas konca (s dátumom)
start_timezone	string	voliteľné	IANA pásmo, v ktorom bol čas začiatku zadaný
end_timezone	string	voliteľné	IANA pásmo času konca
purpose	string	voliteľné	Účel cesty
odometer_start	číslo	voliteľné	Stav kilometrov na začiatku
odometer_end	číslo	voliteľné	Stav kilometrov na konci
notes	string · null	voliteľné	Poznámka
created_at	čas (ISO-8601, UTC)	voliteľné	Čas vzniku záznamu (UTC)
updated_at	čas (ISO-8601, UTC)	voliteľné	Čas poslednej zmeny (UTC)

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.
422Neplatné údaje alebo kombinácia zakázaná pravidlami. Dôvody sú v error.details.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

DELETE/api/v1/trips/{id}rozsah write

Vymazanie cesty

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Vymazanie je mäkké: záznam zostáva v databáze, aby bola zachovaná auditačná stopa. Vymazanie vyžaduje dôvod v poli delete_reason; bez neho sa nič nezmení (422). Vymazať môže iba majiteľ vozidla, na ktorom je cesta zapísaná. Cesty iného účtu API nenájde, preto požiadavka vráti 404. Po vymazaní zostáva cesta v knihe jázd ako archívny záznam (is_deleted, deleted_at, deleted_by, deleted_reason). V reportoch vozidla sa zobrazí označená ako vymazaná a jej kilometre sa do celkovej vzdialenosti už nepočítajú. Trigger zapíše novú verziu do trip_versions s typom deleted, dôvodom a účtom, ktorý vymazanie vykonal. Vymazanú cestu už nie je možné upraviť, obnoviť ani inak meniť — GET, PATCH aj DELETE vracajú 404.

Dôvod sa posiela v tele požiadavky (application/json); požiadavka bez tela vráti 422.

Ukážka požiadavky

curl -X DELETE "https://ecesty.sk/api/v1/trips/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "delete_reason": "Duplicitný záznam zo starého importu"
}'

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Telo požiadavky · application/json

Pole	Typ	Povinné	Popis a obmedzenia
delete_reason	string	povinné	Povinný dôvod vymazania; ukladá sa do záznamu cesty aj do histórie verzií (`trip_versions`) · dĺžka 1–500

Príklad tela

{
  "delete_reason": "Duplicitný záznam zo starého importu"
}

Odpoveď 200

Cesta vymazaná (záznam ostáva archivovaný).

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
deleted	boolean	povinné	Príznak true alebo false
deleted_reason	string	povinné	Textová hodnota

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.
422Neplatné údaje alebo kombinácia zakázaná pravidlami. Dôvody sú v error.details.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Náklady

Výdavky, párovanie s účtovníctvom a prílohy.

9 koncových bodov

GET/api/v1/expenses

Zoznam nákladov

Filtre sa kombinujú logickým AND. from a to filtrujú expense_date, pričom to zahŕňa celý deň. Zoznam nevracia reconciliation_notes; ten nájdete v detaile nákladu.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/expenses?expense_type=fuel&from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
vehicle_id	uuid	dotaz	voliteľné	Obmedzí výsledok na jedno vozidlo z vášho vozového parku
driver_id	uuid	dotaz	voliteľné	Obmedzí výsledok na jedného vodiča
expense_type	`fuel` \| `other`	dotaz	voliteľné	Druh nákladu; iná hodnota vráti 422
from	dátum (YYYY-MM-DD)	dotaz	voliteľné	Dátum od (vrátane), formát `YYYY-MM-DD`
to	dátum (YYYY-MM-DD)	dotaz	voliteľné	Dátum do (vrátane), formát `YYYY-MM-DD`
limit	celé číslo	dotaz	voliteľné	Počet položiek na stranu. Predvolene 50, maximum 200; iná hodnota vráti 422
cursor	string	dotaz	voliteľné	Nepriehľadný kurzor z `meta.next_cursor` predchádzajúcej strany. Neupravujte ho — je to base64url dvojice `(created_at, id)`, ktorá určuje, odkiaľ pokračovať

Odpoveď 200

Strana nákladov.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
driver_id	uuid · null	voliteľné	Vodič, ktorému náklad patrí
expense_type	`fuel` \| `other`	povinné	Druh nákladu
amount	číslo	povinné	Suma v mene `currency`
currency	string	povinné	Kód meny (ISO 4217)
payment_method	`cash` \| `credit_card` \| `debit_card` \| `loyalty_card`	voliteľné	Jedna z uvedených hodnôt
expense_date	čas (ISO-8601, UTC)	voliteľné	Dátum a čas nákladu. Pri vstupe je prijateľný aj samotný dátum `YYYY-MM-DD`
gas_station_name	string · null	voliteľné	Čerpacia stanica (pri `fuel`)
gas_station_location	string · null	voliteľné	Miesto čerpacej stanice
fuel_amount	číslo · null	voliteľné	Množstvo paliva (pri `fuel`)
fuel_unit	`L` \| `kWh` \| `kg` · null	voliteľné	Jednotka paliva
description	string · null	voliteľné	Popis nákladu. Pri druhu `fuel` sa neukladá (pole sa ignoruje)
comments	string · null	voliteľné	Interná poznámka
odometer_reading	číslo · null	voliteľné	Stav kilometrov pri nákupe
reconciliation_status	`pending` \| `reconciled` \| `disputed` · null	voliteľné	Stav párovania s účtovníctvom
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
updated_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
meta.limit	celé číslo	voliteľné	Veľkosť strany, ktorá bola naozaj použitá
meta.has_next	boolean	voliteľné	Existuje ďalšia strana
meta.next_cursor	string · null	voliteľné	Kurzor ďalšej strany, alebo `null` na poslednej strane

Chybové stavy

400Neplatný kurzor (invalid_cursor).
403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
422Parameter limit mimo rozsahu 1–200 alebo neplatná hodnota expense_type.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

POST/api/v1/expensesrozsah write

Vytvorenie nákladu

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Podmienky podľa typu: pri fuel sú povinné gas_station_name, fuel_amount a fuel_unit; pri other je povinný description. description sa pri fuel neukladá. currency je povinná (povolené kódy: EUR, USD, GBP, CZK, PLN, HUF, CHF) a ukladá sa veľkými písmenami. expense_date prijíma YYYY-MM-DD alebo plný ISO-8601 čas; samotný dátum znamená polnoc UTC. driver_id predvolene ukazuje na majiteľa účtu. Úspech vráti 201 a hlavičku Location.

Ukážka požiadavky

curl -X POST "https://ecesty.sk/api/v1/expenses" \
  -H "Authorization: Bearer ec_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "vehicle_id": "9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c",
  "expense_type": "fuel",
  "amount": 64.5,
  "currency": "EUR",
  "payment_method": "credit_card",
  "expense_date": "2026-01-15",
  "gas_station_name": "Slovnaft",
  "gas_station_location": "D1, odpočívadlo Zeleneč",
  "fuel_amount": 42.3,
  "fuel_unit": "L",
  "odometer_reading": 45212
}'

Telo požiadavky · application/json

Pole	Typ	Povinné	Popis a obmedzenia
vehicle_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
driver_id	uuid	voliteľné	Predvolene majiteľ účtu
expense_type	`fuel` \| `other`	povinné	`fuel` vyžaduje stanicu a množstvo paliva; `other` vyžaduje popis
amount	číslo	povinné	Suma v mene `currency` · 0.01 – 9999999
currency	`EUR` \| `USD` \| `GBP` \| `CZK` \| `PLN` \| `HUF` \| `CHF`	povinné	Kód meny. Povinný; uloží sa veľkými písmenami
payment_method	`cash` \| `credit_card` \| `debit_card` \| `loyalty_card`	povinné	Jedna z uvedených hodnôt
expense_date	string	povinné	Dátum alebo ISO-8601 čas nákladu · max. dĺžka 40
gas_station_name	string	voliteľné	Povinné pri `fuel` · max. dĺžka 255
gas_station_location	string	voliteľné	Textová hodnota · max. dĺžka 500
fuel_amount	číslo	voliteľné	Povinné pri `fuel` · 0 – 999999
fuel_unit	`L` \| `kWh` \| `kg`	voliteľné	Povinné pri `fuel`
description	string	voliteľné	Povinné pri `other`; pri `fuel` sa ignoruje · max. dĺžka 1000
comments	string	voliteľné	Textová hodnota · max. dĺžka 1000
odometer_reading	číslo	voliteľné	Číslo · 0 – 9999999

Príklad tela

{
  "vehicle_id": "9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c",
  "expense_type": "fuel",
  "amount": 64.5,
  "currency": "EUR",
  "payment_method": "credit_card",
  "expense_date": "2026-01-15",
  "gas_station_name": "Slovnaft",
  "gas_station_location": "D1, odpočívadlo Zeleneč",
  "fuel_amount": 42.3,
  "fuel_unit": "L",
  "odometer_reading": 45212
}

Odpoveď 201

Náklad vytvorený. Hlavička Location ukazuje na jeho detail.

Hlavičky: Location

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
driver_id	uuid · null	voliteľné	Vodič, ktorému náklad patrí
expense_type	`fuel` \| `other`	povinné	Druh nákladu
amount	číslo	povinné	Suma v mene `currency`
currency	string	povinné	Kód meny (ISO 4217)
payment_method	`cash` \| `credit_card` \| `debit_card` \| `loyalty_card`	voliteľné	Jedna z uvedených hodnôt
expense_date	čas (ISO-8601, UTC)	voliteľné	Dátum a čas nákladu. Pri vstupe je prijateľný aj samotný dátum `YYYY-MM-DD`
gas_station_name	string · null	voliteľné	Čerpacia stanica (pri `fuel`)
gas_station_location	string · null	voliteľné	Miesto čerpacej stanice
fuel_amount	číslo · null	voliteľné	Množstvo paliva (pri `fuel`)
fuel_unit	`L` \| `kWh` \| `kg` · null	voliteľné	Jednotka paliva
description	string · null	voliteľné	Popis nákladu. Pri druhu `fuel` sa neukladá (pole sa ignoruje)
comments	string · null	voliteľné	Interná poznámka
odometer_reading	číslo · null	voliteľné	Stav kilometrov pri nákupe
reconciliation_status	`pending` \| `reconciled` \| `disputed` · null	voliteľné	Stav párovania s účtovníctvom
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
updated_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC

Chybové stavy

403Token nemá rozsah write (forbidden_scope), účet je neaktívny, alebo vozidlo či vodič nepatrí do vozového parku (forbidden).
422Neplatné údaje alebo kombinácia zakázaná pravidlami. Dôvody sú v error.details.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

GET/api/v1/expenses/{id}

Detail nákladu

Obsahuje navyše reconciliation_notes, ktoré zoznam nevracia.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Odpoveď 200

Náklad.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
driver_id	uuid · null	voliteľné	Vodič, ktorému náklad patrí
expense_type	`fuel` \| `other`	povinné	Druh nákladu
amount	číslo	povinné	Suma v mene `currency`
currency	string	povinné	Kód meny (ISO 4217)
payment_method	`cash` \| `credit_card` \| `debit_card` \| `loyalty_card`	voliteľné	Jedna z uvedených hodnôt
expense_date	čas (ISO-8601, UTC)	voliteľné	Dátum a čas nákladu. Pri vstupe je prijateľný aj samotný dátum `YYYY-MM-DD`
gas_station_name	string · null	voliteľné	Čerpacia stanica (pri `fuel`)
gas_station_location	string · null	voliteľné	Miesto čerpacej stanice
fuel_amount	číslo · null	voliteľné	Množstvo paliva (pri `fuel`)
fuel_unit	`L` \| `kWh` \| `kg` · null	voliteľné	Jednotka paliva
description	string · null	voliteľné	Popis nákladu. Pri druhu `fuel` sa neukladá (pole sa ignoruje)
comments	string · null	voliteľné	Interná poznámka
odometer_reading	číslo · null	voliteľné	Stav kilometrov pri nákupe
reconciliation_status	`pending` \| `reconciled` \| `disputed` · null	voliteľné	Stav párovania s účtovníctvom
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
updated_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
reconciliation_notes	string · null	voliteľné	Poznámka k párovaniu (napr. číslo dokladu v účtovníctve)

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

PATCH/api/v1/expenses/{id}rozsah write

Úprava nákladu

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Upraviteľné sú suma, popis, poznámky, údaje o čerpacej stanici, stav kilometrov a polia párovania. Druh nákladu, vozidlo, vodič, dátum a spôsob platby meniť nemožno — pre iný druh nákladu založte nový záznam. Nastavenie reconciliation_status na reconciled uloží reconciled_by a reconciled_at; zmena na iný stav ich vyprázdni. Prázdne telo vráti 422.

Ukážka požiadavky

curl -X PATCH "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "reconciliation_status": "reconciled",
  "reconciliation_notes": "Doklad č. 2026/0042"
}'

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Telo požiadavky · application/json

Pole	Typ	Povinné	Popis a obmedzenia
amount	číslo	voliteľné	Číslo · 0.01 – 9999999
description	string	voliteľné	Textová hodnota · max. dĺžka 1000
comments	string	voliteľné	Textová hodnota · max. dĺžka 1000
gas_station_name	string	voliteľné	Textová hodnota · max. dĺžka 255
gas_station_location	string	voliteľné	Textová hodnota · max. dĺžka 500
fuel_amount	číslo	voliteľné	Číslo · 0 – 999999
odometer_reading	číslo	voliteľné	Číslo · 0 – 9999999
reconciliation_status	`pending` \| `reconciled` \| `disputed`	voliteľné	`reconciled` uloží čas a aktéra párovania; iný stav ich vyprázdni
reconciliation_notes	string	voliteľné	Napríklad číslo dokladu v účtovníctve · max. dĺžka 1000

Príklad tela

{
  "reconciliation_status": "reconciled",
  "reconciliation_notes": "Doklad č. 2026/0042"
}

Odpoveď 200

Upravený náklad.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
vehicle_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
driver_id	uuid · null	voliteľné	Vodič, ktorému náklad patrí
expense_type	`fuel` \| `other`	povinné	Druh nákladu
amount	číslo	povinné	Suma v mene `currency`
currency	string	povinné	Kód meny (ISO 4217)
payment_method	`cash` \| `credit_card` \| `debit_card` \| `loyalty_card`	voliteľné	Jedna z uvedených hodnôt
expense_date	čas (ISO-8601, UTC)	voliteľné	Dátum a čas nákladu. Pri vstupe je prijateľný aj samotný dátum `YYYY-MM-DD`
gas_station_name	string · null	voliteľné	Čerpacia stanica (pri `fuel`)
gas_station_location	string · null	voliteľné	Miesto čerpacej stanice
fuel_amount	číslo · null	voliteľné	Množstvo paliva (pri `fuel`)
fuel_unit	`L` \| `kWh` \| `kg` · null	voliteľné	Jednotka paliva
description	string · null	voliteľné	Popis nákladu. Pri druhu `fuel` sa neukladá (pole sa ignoruje)
comments	string · null	voliteľné	Interná poznámka
odometer_reading	číslo · null	voliteľné	Stav kilometrov pri nákupe
reconciliation_status	`pending` \| `reconciled` \| `disputed` · null	voliteľné	Stav párovania s účtovníctvom
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
updated_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC
reconciliation_notes	string · null	voliteľné	Poznámka k párovaniu (napr. číslo dokladu v účtovníctve)

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.
422Neplatné údaje alebo kombinácia zakázaná pravidlami. Dôvody sú v error.details.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

DELETE/api/v1/expenses/{id}rozsah write

Odstránenie nákladu

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

Trvalé odstránenie: náklad aj všetky jeho prílohy sa zmažú. Pre daňovú evidenciu je vhodnejšie náklad upraviť alebo označiť ako disputed — odstránený záznam sa už nedá obnoviť.

Ukážka požiadavky

curl -X DELETE "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Odpoveď 200

Náklad odstránený.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
deleted	boolean	povinné	Príznak true alebo false

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

GET/api/v1/expenses/{id}/attachments

Zoznam príloh nákladu

Metadáta príloh zoradené od najstaršej. Obsah súboru sťahujte samostatným volaním GET …/attachments/{attachmentId}.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c/attachments" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Odpoveď 200

Prílohy nákladu.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
expense_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
file_name	string	povinné	Pôvodný názov súboru
file_type	string	povinné	MIME typ. Obrázky sa na vstupe prekomprimujú a uložia ako `image/jpeg`
file_size	celé číslo	povinné	Veľkosť uloženého súboru v bajtoch (po prípadnej kompresii)
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

POST/api/v1/expenses/{id}/attachmentsrozsah write

Nahranie príloh

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope.

multipart/form-data s poľom files (možno viackrát v jednej požiadavke). Obmedzenia platia na celý náklad, nielen na jednu požiadavku: najviac 3 prílohy a 5 MB celkovo. Povolené typy: image/jpeg, image/jpg, image/png, image/webp, application/pdf. Obrázky sa na vstupe prekomprimujú (max. 1414 px na dlhšiu stranu) a uložia sa v pôvodnom formáte — image/png zostáva PNG, image/webp WebP, image/jpeg JPEG; PDF sa ukladá bez zmeny. Obrázok s deklarovaným rastrom nad 100 megapixelov sa odmietne (422). Telo jednej požiadavky obmedzuje proxy pred aplikáciou (20 MB v produkcii, 6 MB na vývojovom serveri). Úspech vráti 201 so zoznamom uložených prílôh.

Ukážka požiadavky

curl -X POST "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c/attachments" \
  -H "Authorization: Bearer ec_live_…" \
  -F "files=@blok.jpg" \
  -F "files=@ucet.pdf"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)

Telo požiadavky · multipart/form-data

Pole	Typ	Povinné	Popis a obmedzenia
files	pole binárne dáta	povinné	Súbory na nahranie; spolu najviac 3 súbory a 5 MB na náklad

Súbory posielajte v poli files. V jednej požiadavke ich môže byť viac; celkový limit sa počíta na jeden náklad.

Odpoveď 201

Prílohy nahrané.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
expense_id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
file_name	string	povinné	Pôvodný názov súboru
file_type	string	povinné	MIME typ. Obrázky sa na vstupe prekomprimujú a uložia ako `image/jpeg`
file_size	celé číslo	povinné	Veľkosť uloženého súboru v bajtoch (po prípadnej kompresii)
created_at	čas (ISO-8601, UTC)	voliteľné	Časová pečiatka v UTC

Chybové stavy

403Token nemá rozsah write (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.
422Žiadne súbory, prekročený počet alebo veľkosť, alebo nepovolený typ súboru (validation_error).

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

GET/api/v1/expenses/{id}/attachments/{attachmentId}

Stiahnutie prílohy

Vráti surové bajty s Content-Type uloženého súboru, Content-Length a Content-Disposition: attachment; filename="…" (pôvodný názov). Odpoveď nie je JSON a nemá obal data; do súboru ju zapisujte tak, ako prišla. Príloha nahraná cez Telegram bota môže mať iný typ, než dovoľuje HTTP upload.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c/attachments/1c7d3a90-5e2b-4b6f-8a44-7d0f9c2e5a11" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)
attachmentId	uuid	cesta	povinné	Identifikátor prílohy (UUID) z `GET /expenses/{id}/attachments`

Odpoveď 200

Obsah súboru.

Hlavičky: Content-TypeContent-LengthContent-Disposition

Odpoveď nie je JSON — telo tvoria surové bajty súboru.

Chybové stavy

403Účet je deaktivovaný (account_inactive), token patrí inej ako majiteľskej role (forbidden), alebo token skúša zápis s rozsahom iba na čítanie (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

DELETE/api/v1/expenses/{id}/attachments/{attachmentId}rozsah write

Odstránenie prílohy

Vyžaduje token s rozsahom write. Token s rozsahom read dostane 403 forbidden_scope. Odstráni sa iba táto príloha, náklad zostáva.

Ukážka požiadavky

curl -X DELETE "https://ecesty.sk/api/v1/expenses/9b2f4c1e-6a3d-4f8a-9c1b-2d5e7f9a0b3c/attachments/1c7d3a90-5e2b-4b6f-8a44-7d0f9c2e5a11" \
  -H "Authorization: Bearer ec_live_…"

Parametre

Pole	Typ	Kde	Povinné	Popis a obmedzenia
id	uuid	cesta	povinné	Identifikátor záznamu (UUID)
attachmentId	uuid	cesta	povinné	Identifikátor prílohy (UUID) z `GET /expenses/{id}/attachments`

Odpoveď 200

Príloha odstránená.

Polia odpovede

Pole	Typ	Povinné	Popis a obmedzenia
id	uuid	povinné	Jedinečný identifikátor záznamu (UUID)
deleted	boolean	povinné	Príznak true alebo false

Chybové stavy

403Token nemá rozsah write (forbidden_scope).
404Záznam neexistuje, alebo nepatrí do vášho vozového parku. Pre cudzí záznam sa zámerne vracia 404, nie 403 — existencia cudzích dát sa neprezrádza.

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Popis API

Strojový OpenAPI dokument.

1 koncový bod

GET/api/v1/openapi

OpenAPI 3.1 dokument

Tento dokument, ktorý práve čítate, ako JSON. Volanie je verejné, bez tokenu a bez limitu na token — obsahuje iba kontrakt, žiadne dáta účtu. Odpoveď má Cache-Control: public, max-age=300 a Access-Control-Allow-Origin: *, takže ho možno importovať priamo v prehliadači do Postmana či Insomnie.

Ukážka požiadavky

curl "https://ecesty.sk/api/v1/openapi"

Odpoveď 200

OpenAPI dokument.

Chybové stavy

Vždy môže prísť aj 401 a 429 — rovnaký tvar pri každom koncovom bode, popísaný v katalógu chýb.

Potrebujete pole alebo formát navyše?

Napíšte nám, čo váš účtovný systém potrebuje. API rozširujeme podľa reálnych integračných požiadaviek a nové polia dopĺňame bez zmeny verzie, ak sú spätne kompatibilné.

Kontaktovať podporu info@ecesty.sk

Späť nahor

Začíname

Vytvorte si token

Overte prihlasovacie údaje

Načítajte prvé dáta

Importujte OpenAPI

Autentizácia

Životný cyklus tokenu

Rozsahy tokenu

Iba server–server

Konvencie a limity

Obal odpovedí

Stránkovanie

Dátumy, časy a časové pásma

Dôsledky zápisu

Limity požiadaviek

Katalóg chýb

Referencia koncových bodov

Účet

Odpoveď 200

Polia odpovede

Chybové stavy

Vozidlá

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Vodiči

Odpoveď 200

Polia odpovede

Chybové stavy

Cesty

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Telo požiadavky · application/json

Odpoveď 201

Polia odpovede

Chybové stavy

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre

Telo požiadavky · application/json

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre

Telo požiadavky · application/json

Odpoveď 200

Polia odpovede

Chybové stavy

Náklady

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Telo požiadavky · application/json

Odpoveď 201

Polia odpovede

Chybové stavy

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre

Telo požiadavky · application/json

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre

Odpoveď 200

Polia odpovede

Chybové stavy

Parametre