API dokumentácia

Rýchly štart

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é.

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.

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_…'

{
  "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
    }
  }
}

Vyhľadanie podľa VIN

Vyhľadá vozidlá podľa normalizovaného VIN. Podporuje štandardné 17-znakové VIN aj použiteľné historické alebo neštandardné hodnoty uložené v databáze.

curl 'https://overenie.digital/api/v1/vehicles/vins/WBAUG31050PU29216?country=SK' \
  -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.

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.

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.

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.

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_…'

{
  "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"
  }
}

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.

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.

"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"
}

{
  "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": []}
  ]
}

"odometer": {
  "count": 2,
  "records": [
    {
      "odometer_km": 182450,
      "portal": "Autobazar.eu",
      "published_at": "2025-04-03T12:00:00+02:00",
      "captured_at": "2025-04-04T11:12:13+02:00"
    },
    {
      "odometer_km": 164820,
      "portal": "AAAauto.sk",
      "published_at": "2023-08-18T09:30:00+02:00",
      "captured_at": "2023-08-18T10:02:41+02:00"
    }
  ]
}

"listings": {
  "count": 1,
  "records": [
    {
      "id": "1284ae6c39d170c13eb2d732",
      "portal": "Autobazar.eu",
      "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": true
    }
  ]
}

"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"
    }
  ]
}

"listing_photos": {
  "count": 1,
  "records": [
    {
      "id": "b882ec29d1272fca983a2725",
      "portal": "Autobazar.eu",
      "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"
    }
  ]
}

{
  "database_country": "CZ",
  "vehicle_id": "b407e1b2ba57ac8929d653c4",
  "license_plate": "5Z63350",
  "vin": "WBAUG31050PU29216",
  "vin_kind": "strong",
  "brand": "BMW",
  "model": "118 d"
}

Overenie v evidenciách odcudzených vozidiel

Preverí vozidlo nezávisle v databázach Slovenska, Česka a Slovinska. SK a CZ používajú živý zdroj s perzistentnou cache; SI používa pravidelne importovanú databázu.

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.

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.

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

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…"
}

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.