Kniha jázd

Vozidlá a história období používania. Dostupné firmám v uzavretej bete.

API knihy jázd je dostupné iba firmám v uzavretej bete menu.car. Mimo bety vracia 404. Na čítanie vozidiel potrebujete scope trip_log:read a oprávnenie trip_log.view v aktuálnej role tvorcu API kľúča. Globálne overenie platnosti kľúča a prístupu jeho tvorcu zostáva zachované.

Nový kľúč na čítanie a zápis dostane trip_log:read aj trip_log:write predvolene. Existujúce kľúče nový scope nedostanú automaticky; pridajte ho pri úprave kľúča. Zápis vozidla cez upsert potrebuje scope trip_log:write a oprávnenie trip_log.create v aktuálnej role tvorcu API kľúča. Oprava jazdy potrebuje trip_log:write a trip_log.update, zmazanie trip_log:write a trip_log.delete.

Endpointy

GET/api/v1/trip-log/vehicles/{vehicleId}/summarytrip_log:read

Súhrn mesiaca (year 1900-3000, month 1-12). fuel_cost a energy_cost sú v currency (mena firmy), reimbursement a sumy allowance vždy v EUR, bez ďalšieho zaokrúhlenia. Súkromné auto zamestnanca, konateľa aj živnostníka (E1) má rovnaký tvar allowance: base, fuel, total, rates (rate_per_km, source), unit_prices (per_unit, unit, source: own/week/month/provisional, pri živnostníkovi receipt s dňom nákupu v period_start a period_end, len doklady, ktoré ocenili jazdu mesiaca) a missing (chýbajúce podklady). Neznáma časť náhrady živnostníka je null a jej dôvod je v missing. Legacy uzávierka auta živnostníka, ktorej mesiac má služobnú jazdu v deň mimo E2 (fuel_lump_sum_50) podľa dnešných období vozidla, vráti reimbursement null a allowance so sumami null a missing legacy_snapshot, lebo rozlíšenie E1 a paušálu sa neprepočítava; mesiac celý v E2 má allowance null a reimbursement 0. Inak pri inom režime je allowance null a reimbursement 0. Uzavretý mesiac číta snapshot ako aplikácia; legacy je staršia uzávierka bez úplného snapshotu. Ukážka je živnostník s úplnými dokladmi.

Request
curl "https://monivio.sk/api/v1/trip-log/vehicles/{vehicleId}/summary?year=2026&month=9" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": {
    "vehicle_id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
    "year": 2026,
    "month": 9,
    "trip_count": 1,
    "total_km": 100,
    "business_km": 100,
    "private_km": 0,
    "business_share": 1,
    "currency": "EUR",
    "fuel_cost": 75,
    "energy_cost": 0,
    "reimbursement": 40.3,
    "allowance": {
      "base": 31.3,
      "fuel": 9,
      "total": 40.3,
      "rates": [
        {
          "rate_per_km": 0.313,
          "source": "340/2025 Z. z."
        }
      ],
      "unit_prices": [
        {
          "per_unit": 1.5,
          "unit": "l",
          "source": "receipt",
          "period_start": "2026-09-01",
          "period_end": "2026-09-01"
        }
      ],
      "missing": []
    },
    "closed": false,
    "exported": false,
    "snapshot_state": "live"
  }
}
POST/api/v1/trip-log/vehicles/upserttrip_log:write

Nájde vozidlo podľa normalizovanej ŠPZ, potom VIN. Doplní len prázdne popisné polia, režim nemení. Bez zhody vytvorí vozidlo pod limitom plánu (201); zhoda vráti 200. Nejednoznačný VIN je konflikt 409. Pole warnings oznámi usage_mode_mismatch, keď sa zadaný režim líši od dnešného, a vin_conflict, keď sa prázdny VIN nájdeného vozidla nedoplnil, lebo zadaný VIN už má iné vozidlo firmy.

Request
curl -X POST "https://monivio.sk/api/v1/trip-log/vehicles/upsert" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Testovacie vozidlo",
  "license_plate": "TEST-3951",
  "legal_owner_type": "company",
  "possession_type": "owned",
  "fuel_type": "diesel",
  "usage_period": {
    "valid_from": "2026-01-01",
    "evidence_mode": "ordinary_trip_log",
    "vat_mode": "not_applicable"
  }
}'
Response 200json
{
  "data": {
    "id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
    "name": "Testovacie vozidlo",
    "license_plate": "TEST3951",
    "vin": null,
    "fuel_type": "diesel",
    "legal_owner_type": "company",
    "possession_type": "owned",
    "active": true,
    "current_usage_mode": "not_applicable",
    "usage_periods": [
      {
        "id": "vup_2hf8pq3rxn4mlkzyt9abwvve",
        "valid_from": "2026-01-01",
        "valid_to": null,
        "evidence_mode": "ordinary_trip_log",
        "vat_mode": "not_applicable"
      }
    ],
    "created": false,
    "match_key": "license_plate",
    "filled_fields": [],
    "warnings": []
  }
}
GET/api/v1/trip-log/vehiclestrip_log:read

Zoznam aktívnych vozidiel. S include_inactive=true obsahuje aj archivované vozidlá.

Request
curl "https://monivio.sk/api/v1/trip-log/vehicles?include_inactive=true" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": [
    {
      "id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
      "name": "Testovacie vozidlo",
      "license_plate": "TEST3951",
      "vin": null,
      "fuel_type": "diesel",
      "legal_owner_type": "company",
      "possession_type": "owned",
      "active": true,
      "current_usage_mode": "not_applicable"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1,
    "total": 1,
    "total_pages": 1
  }
}
GET/api/v1/trip-log/vehicles/{vehicleId}trip_log:read

Detail vlastného vozidla vrátane histórie období používania. Cudzie vozidlo vráti 404.

Request
curl "https://monivio.sk/api/v1/trip-log/vehicles/{vehicleId}" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": {
    "id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
    "name": "Testovacie vozidlo",
    "license_plate": "TEST3951",
    "vin": null,
    "fuel_type": "diesel",
    "legal_owner_type": "company",
    "possession_type": "owned",
    "active": true,
    "current_usage_mode": "not_applicable",
    "usage_periods": [
      {
        "id": "vup_2hf8pq3rxn4mlkzyt9abwvve",
        "valid_from": "2026-01-01",
        "valid_to": null,
        "evidence_mode": "ordinary_trip_log",
        "vat_mode": "not_applicable"
      }
    ]
  }
}
POST/api/v1/trip-log/vehicles/{vehicleId}/trips/bulktrip_log:write

Náhľad hromadného zápisu bez zápisu dát. Existujúce external_id vráti existing; chyba novej jazdy zamietne celú dávku.

Request
curl -X POST "https://monivio.sk/api/v1/trip-log/vehicles/{vehicleId}/trips/bulk" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true,
  "trips": [
    {
      "external_id": "reckon-bulk-1",
      "trip_date": "2026-06-10",
      "origin": "Bratislava",
      "destination": "Trnava",
      "kilometers": 50
    }
  ]
}'
Response 200json
{
  "data": {
    "results": [
      {
        "index": 0,
        "external_id": "reckon-bulk-1",
        "status": "would_create",
        "id": null,
        "errors": []
      }
    ],
    "summary": {
      "created": 0,
      "existing": 0,
      "duplicate_in_batch": 0,
      "error": 0,
      "would_create": 1
    }
  }
}
GET/api/v1/trip-log/vehicles/{vehicleId}/tripstrip_log:read

Jazdy mesiaca. Rok a mesiac sú povinné, celé mesiace sa vracajú bez stránkovania vstupu.

Request
curl "https://monivio.sk/api/v1/trip-log/vehicles/{vehicleId}/trips?year=2026&month=6" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": [
    {
      "id": "trip_2hf8pq3rxn4mlkzyt9abwvve",
      "vehicle_id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
      "external_id": "reckon-test-1",
      "sequence_number": 1,
      "trip_date": "2026-06-10",
      "arrival_date": "2026-06-10",
      "departure_time": "08:00",
      "arrival_time": "09:00",
      "driver_name": null,
      "origin": "Bratislava",
      "destination": "Trnava",
      "purpose": "Stretnutie so zákazníkom",
      "kilometers": 50,
      "private_kilometers": 0,
      "city_kilometers": 0,
      "highway_kilometers": 0,
      "combined_cycle": false,
      "odometer_before": 1000,
      "odometer_after": 1050,
      "distance_source": "manual",
      "source": "api",
      "status": "draft",
      "reconstructed": false,
      "updated_at": "2026-06-10T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1,
    "total": 1,
    "total_pages": 1
  }
}
PATCH/api/v1/trip-log/trips/{tripId}trip_log:write

Oprava iba poslaných polí. Voliteľný expected_updated_at porovná updated_at z posledného čítania; zastaraný token je 409 tripChanged.

Request
curl -X PATCH "https://monivio.sk/api/v1/trip-log/trips/{tripId}" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "purpose": "Opravený účel stretnutia"
}'
Response 200json
{
  "data": {
    "id": "trip_2hf8pq3rxn4mlkzyt9abwvve",
    "vehicle_id": "veh_2hf8pq3rxn4mlkzyt9abwvve",
    "external_id": "reckon-test-1",
    "sequence_number": 1,
    "trip_date": "2026-06-10",
    "arrival_date": "2026-06-10",
    "departure_time": "08:00",
    "arrival_time": "09:00",
    "driver_name": null,
    "origin": "Bratislava",
    "destination": "Trnava",
    "purpose": "Opravený účel stretnutia",
    "kilometers": 50,
    "private_kilometers": 0,
    "city_kilometers": 0,
    "highway_kilometers": 0,
    "combined_cycle": false,
    "odometer_before": 1000,
    "odometer_after": 1050,
    "distance_source": "manual",
    "source": "api",
    "status": "draft",
    "reconstructed": false,
    "updated_at": "2026-06-10T10:00:00.000Z"
  }
}
DELETE/api/v1/trip-log/trips/{tripId}trip_log:write

Soft delete jazdy s auditom a eventmi. Uzavretý alebo exportovaný mesiac odmietne zápis s 412.

Request
curl -X DELETE "https://monivio.sk/api/v1/trip-log/trips/{tripId}" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Vozidlo

id
string
Stabilný identifikátor vozidla.
name
string
Názov vozidla.
license_plate
string | null
Evidenčné číslo vozidla (ŠPZ).
vin
string | null
VIN, ak je vyplnené.
fuel_type
string
Pohon: petrol, diesel, hybrid, plug_in_hybrid, bev, lpg alebo other.
legal_owner_type
string
Právny vlastník vozidla.
possession_type
string
Spôsob držby vozidla.
active
boolean
Neaktívne vozidlo je archivované; jeho história zostáva zachovaná.
current_usage_mode
string | null
Dnešný režim DPH podľa časového pásma firmy: not_applicable, mixed_50 alebo full_100. Bez platného obdobia null.
usage_periods
array
Iba detail. História období: id, valid_from, valid_to, evidence_mode, vat_mode. Otvorené obdobie má valid_to=null; zrušené zmeny režimu sa nevracajú.

Chyby

Firma mimo bety menu.car dostane 404 bez ohľadu na scope kľúča. Vo firme v bete chýbajúci scope vráti 403 INSUFFICIENT_SCOPE. Neplatný kľúč vráti 401. Ak tvorcu kľúča z firmy odobrali, pozastavili alebo stratil právo spravovať API kľúče, každý zdroj vráti 401 API_KEY_INACTIVE. Ak je tvorca aktívny, ale jeho aktuálna rola nemá oprávnenie knihy jázd na danú operáciu, endpoint knihy jázd vráti 403 FORBIDDEN. Cudzie alebo neexistujúce vozidlo vráti 404. Doménové chyby knihy jázd nesú details.trip_log_code a prípadné details.issues: nenájdený záznam 404, konflikt 409, nesplnená podmienka 412, neplatný vstup 422 VALIDATION_ERROR.

Oprava a zmazanie jazdy

Zoznam jázd vyžaduje year (1900-3000) a month (1-12). Vráti celý mesiac vozidla. Polia zodpovedajú importu: external_id, trip_date, arrival_date, departure_time, arrival_time, driver_name, origin, destination, purpose, kilometers, private_kilometers, odometer_before a odometer_after. Dátumy majú formát YYYY-MM-DD, časy HH:MM, kilometre sú celé nezáporné čísla. Súkromné kilometre nesmú prevýšiť celkové.

Jazda súkromného vozidla zamestnanca alebo konateľa nesie režim jazdy: city_kilometers (z toho služobné km v meste), combined_cycle (kombinovaný cyklus na žiadosť zamestnanca, len pri vozidle so spotrebou v členení na cykly a bez km v meste) a highway_kilometers (služobné km na diaľnici a rýchlostnej ceste, len pri elektromobile). Predvolene je celá jazda mimo mesta (0, 0, false). Km v meste a na diaľnici spolu nesmú prevýšiť služobné km, teda kilometers mínus private_kilometers; vyšší počet API odmietne, nič neoreže.

PATCH prijíma iba menené polia, navyše distance_source, status a reconstructed. Vozidlo, sequence_number ani source sa nemenia. Odpoveď obsahuje updated_at; pošlite ho ako expected_updated_at, ak chcete odmietnuť súbežnú zmenu (409, details.trip_log_code=tripChanged). Obsadené external_id je 409 tripExternalIdTaken aj pri zmazanej jazde. Uzavretý alebo exportovaný mesiac odmietne PATCH aj DELETE s 412; platia rovnaké pravidlá §85n ako v aplikácii. DELETE jazdu iba označí ako zmazanú, zachová audit a eventy a vráti 204 bez tela.

Hromadný zápis a dry run

POST vehicles/:vehicleId/trips/bulk potrebuje trip_log:write a trip_log.create. Prijíma trips s 1-500 jazdami a dry_run (predvolene false). Polia zodpovedajú importu uvedenému vyššie; dátum a kilometre sú povinné. Pri dry_run=true neuloží žiadnu jazdu, importnú dávku, audit ani event. Rovnaké zámky vozidla a mesiacov chránia validáciu aj zápis, vrátane uzavretých mesiacov a pravidiel §85n podľa dňa jazdy.

Odpoveď 200 obsahuje data.results v poradí vstupu: index (od 0), external_id, status, id (alebo null) a errors s kódom a poľom trips.index.pole. Súhrn data.summary počíta každý stav. created znamená novú jazdu, existing už existujúcu živú jazdu bez porovnania obsahu, duplicate_in_batch opakované ID v dávke, would_create platnú novú jazdu pri dry run. error nesie chyby vrátane external_id_taken_deleted, monthClosed alebo monthAlreadyExported. Existujúce jazdy opravujte cez PATCH; bulk ich neprepisuje ani neobnovuje zmazané jazdy.

Platí celá dávka alebo nič: pri chybe novej jazdy sa nič nezapíše a vrátia sa všetky chyby naraz. Inak platné nové jazdy dostanú error s kódom batch_rejected; existing sa vracia vždy. Klient musí vyhodnotiť výsledky aj pri HTTP 200. Neplatná obálka alebo viac než 500 jázd je 422. Súbeh rovnakých external_id skončí ako existing alebo doménový konflikt 409 tripExternalIdTaken, nie 500. Hlavička idempotency key ani hromadná oprava nie sú podporované. Dry run nie je rezervácia.