API dokumentácia

Vyhľadávajte vozidlá podľa EČV, VIN alebo čísla osvedčenia o evidencii cez stabilné read-only rozhranie.

Získať bezplatný API kľúč OpenAPI 3.1 JSON Postman kolekcia
curl https://overenie.digital/api/v1/vehicles/license-plates/SK/BL001AA \
  -H 'Accept: application/json' \
  -H 'X-API-Key: ovd_live_…'

Rýchly štart

1

Vytvorte kľúč

Po prihlásení otvorte sekciu API v mojom účte. Celý kľúč sa zobrazí iba raz.

2

Pošlite hlavičku

Použite X-API-Key alebo Bearer autentifikáciu. Mechanizmy sa vzájomne vylučujú.

3

Spracujte JSON

Úspech má polia data a meta. Chyby používajú Problem Details.

Base URL: https://overenie.digital/api/v1. Produkčné požiadavky používajú HTTPS a API kľúč v hlavičke.

Autentifikácia

Každá požiadavka musí obsahovať API kľúč práve v jednej z týchto hlavičiek:

X-API-Key: ovd_live_…

# alebo
Authorization: Bearer ovd_live_…

Hlavičky sa vzájomne vylučujú. Ich súčasné použitie vráti 400 multiple_api_keys.

Kľúč môže mať platnosť 30, 90 alebo 365 dní, prípadne môže byť bez expirácie. Obnovenie v mojom účte vygeneruje novú hodnotu a pôvodnú okamžite zneplatní; nový celý kľúč sa zobrazí iba raz.

Scope oprávnenia

Scope určuje, ktoré dátové skupiny môže účet čítať. Balík poskytuje predvolené scope a administrátor ich môže konkrétnemu účtu individuálne povoliť alebo zakázať. Pridelenie jedného scope automaticky nesprístupní ostatné.

vehicle.basic

Všetky známe EČV s krajinou databázy a objekt basic: VIN, značka, model, kategória, karoséria, palivo, farba, objem, výkon, hmotnosť, miesta, dvere, prevodovka a roky prvej evidencie.

vehicle.technical

Objekt technical: presné dátumy evidencie, rozmery, hmotnosti, nápravy, rázvor, rozchod kolies, motor, spotreba, hluk a emisie.

vehicle.theft

Samostatné overenie v databázach SK, CZ, SI, RO a HU: stav každej kontroly, čas, použitie cache a verejné údaje nájdených záznamov.

vehicle.odometer

Objekt odometer: stav v kilometroch, inzertný portál a časy publikovania a zachytenia.

vehicle.listings

Objekt listings: inzertný portál, URL, dátumy, cena, mena a dostupnosť archivovanej snímky.

vehicle.photos

Objekt photos: schválené fotografie vozidla, URL, názov, dátum a rozmery.

vehicle.listing_photos

Objekt listing_photos: fotografie z inzerátov, portál, dátum publikovania, rozmery a podpísaná URL platná 24 hodín.

vehicle.vin_occurrences

Stránkované zdrojové záznamy VIN v národných databázach s rozlíšením rovnakého vozidla a možnej zhody.

Rozšírenia technical, odometer, listings, photos a listing_photos sa načítajú iba po uvedení v parametri include. Známe EČV sú súčasťou základnej odpovede. Overenie odcudzenia a výskyty VIN majú samostatné endpointy.
GET/vehicles/license-plates/{country}/{licensePlate}vehicle.basic

Vyhľadanie podľa EČV

Vyhľadá všetky kanonické vozidlá spojené so zadaným evidenčným číslom. EČV sa interne normalizuje na veľké písmená bez medzier a pomlčiek.

ParameterUmiestnenieTypPopis
country povinnýpathstringDvojpísmenový kód krajiny, napr. SK.
licensePlate povinnýpathstringEČV bez medzier, napr. BL001AA.
pagequeryintegerČíslo strany od 1; predvolená hodnota je 1.
per_pagequeryintegerPočet výsledkov od 1 do 100; predvolená hodnota je 20.
includequerystringVoliteľný zoznam oddelený čiarkou: technical, odometer, listings, photos, listing_photos.
Príklad požiadavky
curl 'https://overenie.digital/api/v1/vehicles/license-plates/SK/BL001AA?page=1&per_page=20' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: ovd_live_…'
200 Príklad odpovede
{
  "data": [
    {
      "id": "b407e1b2ba57ac8929d653c4",
      "country": "SK",
      "registrations": [
        {"database_country": "CZ", "license_plate": "5Z63350"},
        {"database_country": "SK", "license_plate": "BL001AA"},
        {"database_country": "SK", "license_plate": "NR606FL"}
      ],
      "basic": {
        "vin": "WBAUG31050PU29216",
        "brand": "BMW",
        "model": "118 d",
        "year_of_production": null,
        "vehicle_category": "M1",
        "vehicle_type": null,
        "body_type": "AB hatchback 5dv.",
        "fuel": "diesel",
        "fuel_code": 2,
        "color": "Strieborná metalíza svetlá",
        "volume_ccm": 1995,
        "power_kw": 89,
        "weight_max": null,
        "seats": 5,
        "doors": 5,
        "gearbox": null,
        "first_registration_year": 2005,
        "first_registration_local_year": 2010
      }
    }
  ],
  "meta": {
    "request_id": "4a36e06c26c04a4d…",
    "api_version": "1.0",
    "generated_at": "2026-09-27T20:30:00+02:00",
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1,
      "pages": 1,
      "returned": 1,
      "has_previous": false,
      "has_next": false
    }
  }
}
Pole data je vždy zoznam. Jedna EČV môže byť v historických dátach spojená s viacerými vozidlami.
GET/vehicles/vins/{vin}vehicle.basic

Vyhľadanie podľa VIN

Vyhľadá vozidlo podľa normalizovaného VIN. Štandardné 17-znakové VIN je globálna identita vozidla a nie je viazané na krajinu. Pri historickom alebo neštandardnom slabom VIN je krajina povinná, pretože hodnota nemusí byť jednoznačná.

ParameterUmiestnenieTypPopis
vin povinnýpathstringVIN, napr. WBAUG31050PU29216.
countryquerystringPovinná iba pri slabom VIN. Pri silnom VIN sa pre identitu vozidla nepoužíva.
pagequeryintegerČíslo strany od 1; predvolená hodnota je 1.
per_pagequeryintegerPočet výsledkov od 1 do 100; predvolená hodnota je 20.
includequerystringVoliteľný zoznam rozšírených projekcií oddelený čiarkou.
Príklad požiadavky
curl 'https://overenie.digital/api/v1/vehicles/vins/WBAUG31050PU29216' \
  -H 'X-API-Key: ovd_live_…'

Formát úspešnej odpovede je totožný s vyhľadaním podľa EČV. Pole registrations obsahuje všetky známe EČV vozidla aj krajinu databázy. Poradie nevyjadruje chronológiu ani aktuálne používanú EČV, pretože tú z dostupných dát nemožno spoľahlivo určiť. Ak sa rovnaké VIN nachádza pri viacerých kanonických záznamoch, API ich vráti v poli data.

GET/vehicles/registration-documents/{country}/{number}vehicle.basic

Vyhľadanie podľa čísla OEV (TP)

Vyhľadá vozidlá podľa čísla osvedčenia o evidencii vozidla. Hodnota sa normalizuje na veľké písmená bez medzier a pomlčiek.

ParameterUmiestnenieTypPopis
country povinnýpathstringDvojpísmenový kód krajiny, napr. SK.
number povinnýpathstringČíslo dokladu, napr. EIC72630.
pagequeryintegerČíslo strany od 1; predvolená hodnota je 1.
per_pagequeryintegerPočet výsledkov od 1 do 100; predvolená hodnota je 20.
includequerystringVoliteľný zoznam rozšírených projekcií oddelený čiarkou.
Príklad požiadavky
curl 'https://overenie.digital/api/v1/vehicles/registration-documents/SK/EIC72630' \
  -H 'X-API-Key: ovd_live_…'

Číslo dokladu slúži iba na vyhľadanie. V základnej verejnej odpovedi sa z bezpečnostných dôvodov nevracia.

Stránkovanie výsledkov

Vyhľadávacie endpointy a kolekcie používajú rovnaké stránkovanie. Parameter page začína hodnotou 1 a per_page môže mať hodnotu od 1 do 100. Predvolená veľkosť strany je 20 výsledkov.

Pole v meta.paginationVýznam
pageAktuálna strana.
per_pagePožadovaná veľkosť strany.
totalCelkový počet kanonických vozidiel pre identifikátor.
pagesCelkový počet strán.
returnedPočet položiek v aktuálnom poli data.
has_previous, has_nextInformácia o dostupnosti susednej strany.

Strana za poslednou dostupnou stranou vráti HTTP 200, prázdne pole data a zachované stránkovacie metadáta. Neplatné hodnoty vrátia 422 invalid_pagination.

GET/usage

Aktuálna spotreba a oprávnenia

Vráti balík priradený účtu, mesačnú spotrebu, krátkodobý limit a efektívne scope oprávnenia kľúča.

curl 'https://overenie.digital/api/v1/usage' \
  -H 'Authorization: Bearer ovd_live_…'
200 Príklad odpovede
{
  "data": {
    "key": {"name": "Produkčný backend"},
    "plan": {"code": "free", "name": "Free"},
    "quota": {"period": "2026-09", "limit": 30, "used": 7, "remaining": 23},
    "rate_limit": {"requests_per_minute": 5},
    "scopes": ["vehicle.basic"]
  },
  "meta": {
    "request_id": "58c5b8e1be8c4f89…",
    "api_version": "1.0",
    "generated_at": "2026-09-27T20:30:00+02:00"
  }
}
Volanie /usage neodčerpáva mesačný kredit, započítava sa však do limitu požiadaviek za minútu.

Dátový model vozidla

Všetky zdokumentované polia príslušného scope sú v odpovedi vždy. Ak údaj nie je zistený, jeho hodnota je null. Klient sa preto môže spoľahnúť na stabilnú štruktúru objektu.

PoleTypVýznam / jednotka
idstringStabilný verejný identifikátor; nejde o databázové ID.
countrystring|nullKrajina kontextu vyhľadania; pri globálnom vyhľadaní podľa silného VIN je null.
registrationsarrayVšetky známe dvojice database_country + license_plate; žiadna sa neoznačuje za aktuálnu.
basic.vinstringVIN, ak je dostupné.
basic.brand, modelstringZnačka a model.
basic.fuelstringStabilný identifikátor, napr. diesel.
basic.volume_ccmnumberZdvihový objem v cm³.
basic.power_kwintegerVýkon zaokrúhlený na celé kW.
basic.weight_maxnumberNajväčšia prípustná hmotnosť v kg.
basic.first_registration_yearintegerRok prvej evidencie.
Zobraziť všetky základné polia
  • vin
  • brand
  • model
  • year_of_production
  • vehicle_category
  • vehicle_type
  • body_type
  • fuel
  • fuel_code
  • color
  • volume_ccm
  • power_kw
  • weight_max
  • seats
  • doors
  • gearbox
  • first_registration_year
  • first_registration_local_year
Rozšírený blok sa vráti, ak ho požiadavka uvedie v include a kľúč má zodpovedajúci scope. Blok bez nájdených záznamov obsahuje prázdne records. Všetky zdokumentované kľúče záznamu sú vždy prítomné a nezistené hodnoty sú null.

Príklady dátových scope

Inline rozšírenia sa pridávajú cez include. Overenie odcudzenia a kolekcie identity sa volajú samostatne. Každé volanie vyžaduje zodpovedajúci scope.

vehicle.technical objekt technical

Rozmery sú v mm, hmotnosti v kg, objem nádrže v litroch, spotreba v l/100 km a dátumy vo formáte YYYY-MM-DD.

"technical": {
  "factory_mark": "BMW 118 d",
  "condition": null,
  "weight_operational": 1420,
  "weight_permissible_kg": 1840,
  "axle_type": null,
  "axle_number": 2,
  "places_total": 5,
  "places_standing": 0,
  "places_sleep": 0,
  "gearbox_gears": 6,
  "engine_manufacturer": "BMW",
  "engine_min_rpm": 4000,
  "wheel_track_1": 1484,
  "wheel_track_2": 1497,
  "wheel_track_3": null,
  "wheel_track_4": null,
  "wheelbase": 2660,
  "max_roof_load": 75,
  "tank_volume": 51,
  "length": 4227,
  "width": 1751,
  "height": 1430,
  "loading_area_length": null,
  "loading_area_width": null,
  "power_weight_ratio": 0.063,
  "consumption": null,
  "consumption_city": 6.7,
  "consumption_city_out": 4.2,
  "consumption_combined": 5.1,
  "noise_standing": 78,
  "noise_revolutions": 3000,
  "noise_driving": 70,
  "emissions_co2": 136,
  "emissions_co2_city": null,
  "emissions_co2_city_out": null,
  "first_registration_date": "2005-09-01",
  "first_registration_local_date": "2010-05-19"
}
vehicle.theft overenie SK, CZ, SI, RO a HU

Endpoint /vehicles/{vehicleId}/theft vracia samostatný stav každej databázy. Stav unavailable nikdy neznamená, že vozidlo nie je hľadané.

{
  "status": "found",
  "checks": [
    {
      "database_country": "SK",
      "status": "found",
      "checked_at": "2026-09-28T16:20:00+02:00",
      "cached": true,
      "records": [{
        "license_plate": "ZA749JM",
        "vin": "TMAJ3811ALJ892285",
        "registration_country": "Slovenská republika",
        "manufacturer": "HYUNDAI",
        "model": "TUCSON",
        "vehicle_type": "OSOBNÉ VOZIDLO",
        "color": "Šedá metalíza tmavá",
        "stolen_at": "2026-09-24"
      }]
    },
    {"database_country": "CZ", "status": "not_found", "checked_at": "2026-09-28T16:20:01+02:00", "cached": false, "records": []},
    {"database_country": "SI", "status": "not_found", "checked_at": "2026-09-28T15:00:00+02:00", "cached": false, "records": []},
    {"database_country": "RO", "status": "not_found", "checked_at": "2026-09-28T15:00:02+02:00", "cached": true, "records": []},
    {"database_country": "HU", "status": "not_found", "checked_at": "2026-09-28T15:00:03+02:00", "cached": true, "records": []}
  ]
}
vehicle.odometer objekt odometer

Záznamy sú zoradené od najnovšieho. count udáva počet vrátených meraní.

"odometer": {
  "count": 2,
  "records": [
    {
      "odometer_km": 182450,
      "portal": "Inzertný portál",
      "published_at": "2025-04-03T12:00:00+02:00",
      "captured_at": "2025-04-04T11:12:13+02:00"
    },
    {
      "odometer_km": 164820,
      "portal": "Inzertný portál",
      "published_at": "2023-08-18T09:30:00+02:00",
      "captured_at": "2023-08-18T10:02:41+02:00"
    }
  ]
}
vehicle.listings objekt listings

Objekt obsahuje verejné údaje inzerátu. Kontaktné ani iné súkromné údaje predávajúceho sa nevracajú.

"listings": {
  "count": 1,
  "records": [
    {
      "id": "1284ae6c39d170c13eb2d732",
      "portal": "Inzertný portál",
      "url": "https://example.com/listing/1284ae6c",
      "published_at": "2025-04-03T12:00:00+02:00",
      "captured_at": "2025-04-04T11:12:13+02:00",
      "price": 10999.9,
      "currency": "EUR",
      "screenshot_available": false
    }
  ]
}
vehicle.photos objekt photos

Vracajú sa aktívne moderované fotografie priradené priamo k vozidlu.

"photos": {
  "count": 1,
  "records": [
    {
      "id": "07a22e48b2b00a5fa975391c",
      "title": "Predný pohľad",
      "created_at": "2024-01-02T03:04:05+01:00",
      "width": 1600,
      "height": 1200,
      "url": "https://overenie.digital/images/vozidlo/fotografia/91"
    }
  ]
}
vehicle.listing_photos objekt listing_photos

count je počet záznamov v náhľade. Pole records obsahuje najviac 24 najnovších fotografií; presný počet a ďalšie strany poskytuje kolekčný endpoint.

"listing_photos": {
  "count": 1,
  "records": [
    {
      "id": "b882ec29d1272fca983a2725",
      "portal": "Inzertný portál",
      "published_at": "2025-04-03T12:00:00+02:00",
      "width": 1280,
      "height": 720,
      "url": "https://overenie.digital/images/vozidlo/inzerat/fotografia/92?expires=1790620200&signature=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "expires_at": "2026-09-28T20:30:00+02:00"
    }
  ]
}
vehicle.vin_occurrences kolekcia vin_occurrences

Kolekcia vracia všetky známe národné zdrojové záznamy. same_vehicle znamená rovnakú identitu podľa silného VIN; possible_match je iba možná zhoda slabého VIN. Ak národný dataset obsahuje VIN, ale neposkytuje EČV, pole license_plate má hodnotu null. Polia brand a model sú pôvodné hodnoty konkrétnej národnej databázy a môžu preto obsahovať všeobecnú hodnotu ako JINÉ; najlepší zlúčený profil je v základnom objekte basic.

{
  "database_country": "CZ",
  "vehicle_id": "b407e1b2ba57ac8929d653c4",
  "license_plate": "5Z63350",
  "vin": "WBAUG31050PU29216",
  "vin_kind": "strong",
  "identity_relation": "same_vehicle",
  "brand": "BMW",
  "model": "118 d"
}
GET/vehicles/{vehicleId}/theftvehicle.theft

Overenie v evidenciách odcudzených vozidiel

Preverí vozidlo nezávisle v databázach Slovenska, Česka, Slovinska, Rumunska a Maďarska. SK, CZ a HU používajú živý zdroj s perzistentnou cache; SI a RO používajú pravidelne importované databázy. HU má zároveň postupne synchronizovanú lokálnu kópiu.

curl 'https://overenie.digital/api/v1/vehicles/b407e1b2ba57ac8929d653c4/theft' \
  -H 'X-API-Key: ovd_live_…'

status môže byť found, not_found alebo unavailable. Celkový stav je found, ak našla záznam aspoň jedna databáza; inak je unavailable, ak aspoň jedna kontrola zlyhala. Pole cached hovorí, či bol použitý ešte čerstvý výsledok.

GET/vehicles/{vehicleId}/{collection}

Stránkované kolekcie vozidla

Pre objemnejšie dátové skupiny použite verejné id z výsledku vyhľadania. Každá kolekcia má samostatné stránkovanie a vyžaduje zodpovedajúci scope. Známe EČV sú vždy priamo v poli registrations základného výsledku.

KolekciaPožadovaný scopeObsah
vin_occurrencesvehicle.vin_occurrencesNárodné zdrojové záznamy VIN a ich vzťah ku kanonickému vozidlu.
odometervehicle.odometerHistorické stavy odometra.
listingsvehicle.listingsHistorické inzeráty.
photosvehicle.photosSchválené fotografie vozidla.
listing_photosvehicle.listing_photosFotografie z historických inzerátov.
Príklad
curl 'https://overenie.digital/api/v1/vehicles/b407e1b2ba57ac8929d653c4/listings?page=2&per_page=50' \
  -H 'X-API-Key: ovd_live_…'

Odpoveď obsahuje pole záznamov v data a rovnaký objekt meta.pagination ako hlavné vyhľadávanie. Úspešná strana spotrebuje jeden kredit.

Návratové hlavičky a kvóta

HlavičkaVýznam
X-Request-IDJedinečný identifikátor požiadavky pre podporu.
X-Quota-LimitMesačný limit úspešných vyhľadaní.
X-Quota-RemainingPočet zostávajúcich vyhľadaní po tejto odpovedi.
X-Quota-ResetObnovenie kvóty vo formáte ISO 8601.
Retry-AfterPri HTTP 429 počet sekúnd do ďalšieho pokusu.

Do mesačnej kvóty sa započíta iba úspešné vyhľadanie s HTTP 200. Všetky autentifikované požiadavky podliehajú minútovému rate limitu.

Chybové odpovede

Chyby používajú application/problem+json. Pole code je stabilné a určené na programové spracovanie.

{
  "type": "https://overenie.digital/api#vehicle_not_found",
  "title": "Vehicle not found",
  "status": 404,
  "detail": "No vehicle was found for the supplied identifier.",
  "instance": "/api/v1/vehicles/license-plates/SK/XX000XX",
  "code": "vehicle_not_found",
  "request_id": "b38bc53a3fd74f9d…"
}
HTTPKódKedy vznikne
400multiple_api_keysKľúč bol poslaný v oboch autentifikačných hlavičkách.
401missing_api_key, invalid_api_keyKľúč chýba alebo nie je platný.
403api_key_disabled, api_key_expiredKľúč je zrušený alebo expirovaný.
403api_access_disabled, api_access_inactivePrístup účtu je vypnutý alebo mimo platnosti.
403insufficient_scopeBalík nemá požadované oprávnenie.
404vehicle_not_foundVozidlo sa nenašlo.
422invalid_identifier, invalid_vehicle_idVyhľadávací alebo verejný identifikátor má nepodporovaný formát.
422invalid_country, country_requiredKrajina nie je podporovaná alebo chýba pri slabom VIN.
422invalid_includeinclude obsahuje nepodporovanú projekciu.
422invalid_paginationpage alebo per_page sú mimo povoleného rozsahu.
429rate_limit_exceeded, ip_rate_limit_exceededPrekročený limit kľúča alebo sieťovej adresy.
429monthly_quota_exceededVyčerpaná mesačná kvóta.
500internal_errorNeočakávaná chyba; podpore pošlite request_id.
503api_unavailable, api_misconfiguredVerejné API je dočasne nedostupné.

Verzovanie a kompatibilita

Hlavná verzia je v URL: /api/v1. Aktuálne ide o neverejnú testovaciu verziu a jej kontrakt sa môže pred verejným spustením zmeniť. Po zverejnení budú nekompatibilné zmeny patriť do novej hlavnej verzie.

Odporúčanie: ignorujte budúce neznáme JSON polia a nespoliehajte sa na ich poradie. Zdokumentované kľúče objektov sú vždy prítomné; nezistená hodnota je null.