API registru vozidel: data o vozidle podle VIN jedním dotazem
API registru vozidel od Proklepni vrací podle VIN to, co bezplatné API Ministerstva dopravy nevrací: všechny prohlídky STK se zapsanými nájezdy a jejich vyhodnocení, pátrání po vozidlech v Česku, na Slovensku a v Maďarsku a ocenění z cenového modelu. Technické údaje o voze vrací zdarma i Datová kostka Ministerstva dopravy, ty jsou jen začátek. Rozhraní REST s odpověďmi v JSON doplňuje váš portál nebo software: nenahrazuje inzerci ani účetnictví, jen dodává data a události.
Ukázka běží na smyšlených datech. Ceník pro váš obor
- Kdo v aplikaci pracuje
- Vývojář, vedoucí i majitel: každý má svůj přehled a moderátoři pracují s frontou inzerátů k ověření. Produkční klíč navrhne vývojář a schválí vedoucí, účetní vidí spotřebu podle projektů jen ke čtení a partner spravuje podklíče svých klientů.
- Co se děje samo
- Inzerát vozu, u kterého prověření nebo změna v registru ukáže záznam v pátrání, se skryje a vznikne úkol se zdůvodněním pro inzerenta. Vývoz a zánik přijdou s měsíčním výpisem z registru, dávka z nahraného souboru doběhne do několika hodin a při 80 a 100 % volání v ceně přijde upozornění; v pondělí souhrn pro vedení.
- Napojení
- Klíč posíláte v hlavičce Authorization, ke každému volání je hotový kód v cURL, JavaScriptu a Pythonu. Změny u vozů chodí na váš webhook, hromadné zpracování jako dávky s výsledkem v CSV nebo JSON Lines. Sandbox odpovídá stejně jako produkce a nic neúčtuje. První napojení nastavíme v pilotu s vámi.
Co API vrací: datový slovník
Základem je jedno volání, GET /v1/vehicles/{vin}. Odpověď má pevnou strukturu a je rozdělená do bloků podle zdroje. U každého bloku je pole as_of s dnem, ke kterému údaje platí, a pole source, odkud pocházejí: data se netváří čerstvěji, než jsou. Bloky odpovědi jsou tyto:
- decoded: značka, model, varianta, motor a modelový rok z dekodéru VIN;
- registry: stav v registru, palivo, výkon a objem motoru, barva, počet míst, emisní třída, první registrace v Česku a v zahraničí, původ se zemí a datem dovozu, počet změn vlastníka, údaj, zda je vlastníkem leasingová společnost nebo banka, vyřazení z provozu s důvodem, registrovaný účel použití (taxi, půjčovna) a zapsaná výbava;
- stk: stav a platnost STK, poslední prohlídka a její výsledek podle českých pojmů Způsobilé, Způsobilé na 30 dnů a Nezpůsobilé; všechny prohlídky se závadami vrací GET /v1/vehicles/{vin}/inspections, u každé závady s kódem, oblastí a závažností A, B nebo C;
- odometer: zapsané nájezdy z prohlídek STK, jejich vyhodnocení (bez podezření, zapsaný nájezd klesl, nebo málo dat), průměrný roční nájezd a spodní mez skutečného nájezdu;
- theft: pátrání po vozidlech v Česku, na Slovensku a v Maďarsku a záznam o odcizení v registru vozidel, u každého registru s časem poslední kontroly;
- badges: odznaky s hotovým českým textem, například „Nájezd bez podezření na stočení“ nebo „Neevidováno jako odcizené“, a s úrovní (ok, attention, alert, neutral nebo info), podle které portál zvolí barvu;
- ocenění je zvláštní volání, POST /v1/valuations: odhad ceny, tržní rozpětí a souhrn srovnatelných vozů.
| Endpoint | Co vrací | Počítá se do tarifu |
|---|---|---|
| GET /v1/vehicles/{vin} | Identita vozu: dekódování VIN, registr, STK, nájezd, pátrání a hotové odznaky s českým textem. | Ano |
| GET /v1/vehicles/{vin}/inspections | Všechny prohlídky STK s výsledkem, závadami a zapsaným nájezdem. | Ano |
| GET /v1/vehicles/{vin}/odometer | Zapsané nájezdy, posouzení a volitelně kontrola nájezdu uvedeného v inzerátu. | Ano |
| GET /v1/vehicles/{vin}/theft | Záznamy o odcizení v pátrání ČR, Slovenska a Maďarska a v registru vozidel. | Ano |
| POST /v1/valuations | Odhad ceny, tržní rozpětí a souhrn srovnatelných vozů podle VIN, nebo bez VIN podle značky, modelu, motoru, roku, výbavy a nájezdu. | Ano |
| GET /v1/market/segments | Souhrny inzerce podle segmentů: počet inzerátů, medián inzerované ceny, nájezd a doba v inzerci. Jen souhrny, žádné jednotlivé inzeráty. | Ano |
| POST /v1/watchlists | Založí hlídaný seznam VIN. Změny chodí jako události na váš webhook. Nezapočítává se, účtují se hlídané VIN. | Ne |
| POST /v1/batches | Zpracuje seznam VIN najednou. Výsledek je ke stažení sedm dní. | Po zpracování, jen nalezené VIN |
| GET /v1/batches/{id} | Stav dávky a odkaz na výsledek. Nezapočítává se. | Ne |
| PATCH /v1/watchlists/{id} | Přidá nebo odebere VIN v hlídaném seznamu, třeba při zveřejnění a ukončení inzerátu. Nezapočítává se, účtují se hlídané VIN. | Ne |
| GET /v1/events | Události za zvolené období, i ty, které váš webhook nepřijal. Nezapočítává se. | Ne |
| GET /v1/vehicles/{vin}/report.pdf | Prověření vozu jako PDF: registr, prohlídky STK a nájezd, pátrání a ocenění, s logem vašeho portálu vedle našeho. Cenu můžete vypnout. | Ano |
| POST /v1/applications/check | Prověření vozu a ocenění k žádosti o financování: registr, STK, nájezd, pátrání, tržní rozpětí a LTV požadovaného úvěru. | Ano |
| PUT /v1/portfolio/contracts/{contract_id} | Založí nebo upraví hlídanou smlouvu: zůstatek, délku a zbytkovou hodnotu. Události k vozu chodí s číslem smlouvy. Nezapočítává se. | Ne |
Slovník je psaný opatrně. Nájezd, který mezi dvěma prohlídkami klesl, API nehlásí jako stočený tachometr, ale jako „Zapsaný nájezd klesl, k ověření“, protože za poklesem může být doložená výměna přístrojové desky nebo překlep. Vůz mladší čtyř let, který ještě neměl STK, dostane stav „Nájezd zatím nelze posoudit“, ne zelený odznak. Co z toho vidí kupující, ukazuje bezplatná kontrola VIN na našem webu, postavená na stejných zdrojích.
Každý zdroj má vlastní rytmus a odpověď ho nezakrývá. Výpis z registru vychází jednou měsíčně, prohlídky STK se v otevřených datech objeví zhruba o tři týdny později a pátrání ověřujeme při každém volání a u hlídaných vozů při změně v registru. Změna, která se stala včera, se v registru proto neukáže hned.
Příklad dotazu a odpovědi
Každé volání nese tajný klíč v hlavičce Authorization: Bearer. Produkční tajné klíče začínají sk_live_, testovací sk_test_ a patří jen na váš server. Interní službě vytvoříte omezený klíč rk_live_ jen s oprávněními, která potřebuje.
Níže je dotaz na jeden ukázkový vůz, Škodu Octavii Combi 2.0 TDI, a odpověď, kterou API vrátí. Je to tatáž odpověď jako v konzoli ukázkové aplikace, jen zkrácená na hlavní bloky.
Dotaz, cURL (adresu API_BASE dostanete s přístupem)
curl -X GET "$API_BASE/v1/vehicles/TMBJG7NE4K0214561" \
-H "Authorization: Bearer $PROKLEPNI_API_KEY" \
-H "Accept: application/json"Hlavičky odpovědi: 200 OK · započteno 1 volání
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: req_16b35631ce50
Proklepni-Units: 1Tělo odpovědi, application/json
{
"request_id": "req_16b35631ce50",
"livemode": true,
"generated_at": "2026-10-01T10:24:08Z",
"vin": "TMBJG7NE4K0214561",
"decoded": {
"as_of": "2026-10-01",
"source": "vin_decoder",
"make_display": "Škoda",
"model_display": "Octavia",
"variant": "COMBI",
"engine": "2.0 TDI",
"model_year": 2019
},
"registry": {
"as_of": "2026-09-30",
"source": "registry",
"status": "in_operation",
"fuel": "diesel",
"engine_kw": 110,
"engine_cc": 1968,
"first_registration": "2019-03-20",
"origin": "domestic",
"owner_is_financier": false,
"owner_changes": 1
},
"stk": {
"as_of": "2026-09-10",
"source": "stk_inspections",
"state": "valid",
"last_inspection": "2025-04-02",
"last_regular_inspection": "2025-03-11",
"result": 1,
"result_label": "Způsobilé",
"valid_until": "2027-03-11"
},
"odometer": {
"as_of": "2026-09-10",
"source": "stk_inspections",
"assessment": "no_suspicion",
"readings_count": 3,
"lower_bound_km": 143900
},
"theft": {
"as_of": "2026-10-01",
"source": "theft_registers",
"status": "not_listed",
"status_label": "Neevidováno jako odcizené",
"registers_checked": [
"CZ",
"SK",
"HU",
"vehicle_register"
]
},
"badges": [
{
"kind": "odometer",
"code": "odometer_no_suspicion",
"level": "ok",
"label": "Nájezd bez podezření na stočení",
"detail": "Zapsané nájezdy na sebe navazují (3 zápisy, poslední 4/2025)."
},
{
"kind": "theft",
"code": "theft_not_listed",
"level": "ok",
"label": "Neevidováno jako odcizené",
"detail": "Ověřeno k 1. 10. 2026 v pátrání ČR, Slovenska a Maďarska a v záznamu registru vozidel."
}
]
}Zkráceno. Plná odpověď má v bloku registry další údaje, v bloku theft výpis registrů a všech šest odznaků.
Každá odpověď nese request_id, stejný jako v hlavičce X-Request-Id: uvedete ho při dotazu na podporu. Limit volání platí podle tarifu; po jeho překročení vrací API chybu 429 s hlavičkou Retry-After.
Chyba má vždy stejný tvar: error.code, error.message a error.field. VIN, který registr nezná, vrací 404 vehicle_not_found a portál má v takovém případě zobrazit inzerát bez odznaků a nic neblokovat. VIN o jeden znak kratší vrací 422 invalid_vin. Požadavky POST a PATCH posílejte s hlavičkou Idempotency-Key: stejný klíč se stejným tělem vrátí do 24 hodin původní odpověď a nic se znovu neúčtuje, s jiným tělem vrátí chybu 409.
Sandbox s pěti ukázkovými vozidly vám zřídíme v pilotu: odpovídá stejně jako produkce, nic neúčtuje a každá odpověď nese livemode: false. Vozidla pokrývají typické scénáře od běžného vozu po vůz evidovaný jako odcizený. Endpointy, pole a chyby si projdete v dokumentaci ukázkové aplikace.
Obohacení inzerátu pro portály
Typické nasazení je inzertní portál. Prodávající zadá VIN a formulář se za několik sekund vyplní: značka, model, motor, výkon, palivo, objem motoru, rok výroby, první registrace, barva a počet míst. To umí i bezplatná Datová kostka. Rozdíl je v tom, co portál z odpovědi dostane navíc a může ukázat kupujícímu:
- vyhodnocení nájezdu ze všech prohlídek STK: když prodávající uvede méně kilometrů, než bylo zapsáno při STK, formulář ho na to upozorní hned při zadání a inzerát se zveřejní s označením „Nájezd k ověření“ nebo ho dostane moderátor;
- platnost STK a výsledek poslední prohlídky podle českých pojmů, včetně závad;
- pátrání ve třech státech: vůz, u kterého prověření nebo změna v registru ukáže záznam v pátrání, API oznámí událostí theft.listed a portál inzerát zadrží, dokud moderátor neověří doklady;
- původ a vlastník: dovoz se zemí, údaj, zda je vlastníkem leasingová společnost nebo banka, a registrovaný účel taxi nebo půjčovna;
- hodnocení ceny: kupující vidí, zda je inzerovaná cena pod trhem, v rozpětí trhu, nebo nad ním; u modelu, který neumíme ocenit, odpověď řekne insufficient_data místo odhadu.
Převodovku z VIN nezjistíme: registr ji nevede ani dekodér, proto ji vyplní prodávající spolu s nájezdem, cenou a fotografiemi. Zástavy registr neobsahuje, a proto API neříká, že vůz není zastavený, jen že vlastníkem není leasing ani banka.
Ocenění funguje i bez VIN: POST /v1/valuations přijme značku, model, motor, rok, výbavu, nájezd a stav vozu. Ceny jsou statistika z inzerovaných cen, ne ceny skutečných prodejů, a z inzerce API vrací jen souhrny, například počet, medián a dobu v inzerci. Jednotlivé inzeráty, údaje o prodávajících ani zdrojové portály nevrací.
Dávky a webhooky
Hromadné zpracování neposílejte smyčkou jednotlivých volání. POST /v1/batches přijme seznam VIN, vrátí 202 s číslem dávky a výsledek je u tisíců VIN hotový do několika hodin; ke stažení je sedm dní jako CSV pro Excel nebo JSON Lines. Každý řádek nese VIN, výsledek hledání a u neplatného VIN chybu. Stav dávky zjistíte voláním GET /v1/batches/{id}, nebo počkáte na událost batch.completed. Dávka má v sandboxu nejvýš 100 VIN, v produkci až 50 000 VIN podle smlouvy.
Portál by se neměl každý den ptát na tytéž vozy. Založíte proto seznam hlídaných vozů a API změny pošle samo: při zveřejnění inzerátu přidáte VIN voláním PATCH /v1/watchlists/{id}, po ukončení inzerátu ho odeberete. Událostí je osm:
- inspection.created: k hlídanému vozu přibyla prohlídka STK; otevřená data prohlídek přicházejí po týdenních dávkách se zpožděním zhruba tří týdnů;
- odometer.drop_registered: nově zapsaný nájezd je nižší než dřívější zápis, což je podnět k ověření, ne verdikt;
- theft.listed a theft.cleared: vůz se objevil v pátrání, respektive záznam o odcizení zmizel; pátrání ověřujeme při každém prověření a při změně v registru, na vyžádání kdykoli;
- registration.status_changed a ownership.changed: vyřazení, vývoz nebo zánik a změna vlastníka nebo provozovatele; přicházejí s měsíčním výpisem z registru, tedy až o měsíc později, a u změn vlastníka dostanete jen počet a datum, nikdy osobu;
- valuation.band_moved: tržní rozpětí vozu se při přepočtu cen posunulo o víc než 5 %;
- batch.completed: dávka doběhla a výsledek je ke stažení.
Doručení je navržené tak, aby se na něj dalo spolehnout. Každou událost posíláme metodou POST jako JSON a čekáme 10 sekund na odpověď 2xx. Při chybě opakujeme po 1 minutě, 5 minutách, 30 minutách, 2 hodinách, 8 hodinách a 24 hodinách. Když selže i šesté opakování, událost odložíme a vyzvednete ji voláním GET /v1/events. Doručujeme nejméně jednou a bez záruky pořadí, duplicity poznáte podle hlavičky Proklepni-Event-Id.
Každé doručení je podepsané klíčem odběru, který začíná whsec_. Podpis je HMAC SHA-256 z časové známky a těla zprávy a doporučujeme odmítnout zprávy starší pěti minut. Klíč odběru vyměníte v detailu odběru, starý platí ještě 24 hodin.
Limity a ceník
Tarify mají čtyři stupně, Start, Plus, Business a Enterprise, a liší se objemem volání v ceně, počtem hlídaných VIN a produkčních klíčů a funkcemi: webhooky od Plus, dávky od Business, smluvní objemy v Enterprise. Ceny jednotlivých tarifů najdete v ceníku pro portály a vývojáře. Limity platí pro celý účet, klíče se do nich sčítají. Pravidla jsou tato:
- rychlost: limit podle tarifu, Enterprise podle smlouvy; po překročení vrací API chybu 429 s hlavičkou Retry-After;
- počítání volání: tarif zahrnuje měsíční objem volání, volání nad něj se neblokují a účtují se jednotlivě; neúčtují se chyby požadavku (4xx), dočasný výpadek na naší straně (503), sandbox ani dotaz na stav dávky a stažení událostí; u dávky se účtují jen nalezené VIN;
- verze: číslo verze je v URL, /v1. V rámci verze pole jen přidáváme a nic neodebíráme, zásadní změnu ohlásíme nejméně 12 měsíců předem a stará verze běží po tu dobu vedle nové;
- dostupnost: dostupnost produkčního API sjednáme ve smlouvě podle měření, které vám předem ukážeme; plánovanou údržbu oznamujeme nejméně pět dní předem a děláme ji v noci mimo pracovní dobu, na hlášení chyby v produkci odpovídáme v pracovní dny; sandbox je bez záruky dostupnosti.
Pilot trvá 30 dní a nic nestojí a rozsah volání, rychlost a velikost dávek v něm nastavíme podle vašeho provozu.
Rozdíl oproti Datové kostce
Datová kostka je oficiální a bezplatné API Ministerstva dopravy. Klíč dostanete po registraci a smíte volat 27 dotazů za minutu na klíč. Podle VIN vrací technické údaje, účel použití, datum příští pravidelné prohlídky, stav vozidla a počet vlastníků a provozovatelů. Na jednotlivé dotazy na technické údaje stačí a my ji nenahrazujeme. Nevrací ale historii prohlídek STK, zapsané nájezdy, pátrání ani cenu, nemá události ani dávky a nedává záruku dostupnosti.
Platíte za to, co vzniká až propojením zdrojů, jejich průběžnou údržbou a vyhodnocením:
- všechny prohlídky STK od roku 2008 se závadami, kódem a závažností, ne jen datum příští prohlídky;
- vyhodnocení zapsaných nájezdů: pokles, průměrný roční nájezd a spodní mez skutečného nájezdu;
- pátrání v Česku, na Slovensku a v Maďarsku a záznam o odcizení v registru, ověřené při každém volání;
- u vlastníků počet a data změn a údaj, zda je vlastníkem leasingová společnost nebo banka, u dovozu navíc země a datum;
- ocenění a hodnocení ceny z cenového modelu nad inzerovanými cenami;
- události, hlídané seznamy a dávky do 50 000 VIN pod jedním klíčem a jednou smlouvou, s dohodnutou dostupností.
Co API nevrací, říkáme předem. Nevrací jednotlivé inzeráty, protože inzerce slouží jen jako vstup ocenění, ani údaje o prodávajících a zdrojové portály. Soukromé vlastníky nijak neidentifikuje: u změny vlastníka je v odpovědi jen počet a datum a VIN se s fyzickou osobou nespojuje. Nemáme historii před příchodem vozu do Česka, nájezdy před 1. 7. 2008, zástavy, nehody ani servisní záznamy. A nevrací registrační značku: otevřený registr ji neobsahuje a z registrační značky se VIN určit nedá.
Časté otázky
Čím se vaše API liší od Datové kostky Ministerstva dopravy?
Datová kostka vrací zdarma technické údaje o voze, datum příští prohlídky a počty vlastníků, s limitem 27 dotazů za minutu a bez záruky dostupnosti. Naše API tytéž technické údaje vrací také a přidává všechny prohlídky STK se závadami a zapsanými nájezdy a jejich vyhodnocení, pátrání v Česku, na Slovensku a v Maďarsku, ocenění z cenového modelu, události místo dotazování, dávky a dohodnutou dostupnost. Na jednotlivý dotaz na technické údaje stačí Datová kostka.
Jaká data API vrací a z jakých zdrojů?
Z dekodéru VIN značku, model, variantu a motor, z registru vozidel technické údaje, původ, vlastníky počtem a stav (výpis vychází jednou měsíčně), z prohlídek STK historii prohlídek, závady a zapsané nájezdy (zpoždění zhruba tři týdny), z pátrání po vozidlech Česko, Slovensko a Maďarsko (ověřené při každém volání) a z cenového modelu ocenění z inzerovaných cen (přepočet po každé aktualizaci cen). Každý blok odpovědi nese den, ke kterému platí, a zdroj. Osobní údaje, jednotlivé inzeráty ani registrační značku API nevrací.
Funguje ocenění i bez VIN?
Ano. POST /v1/valuations přijme místo VIN značku, model, motor, rok výroby, výbavu, nájezd a stav vozu (horší, běžný, lepší) a vrátí odhad s tržním rozpětím. Když výbavu neuvedete, je rozpětí širší. Ocenění umíme pro vybrané modely a motory, u jiných odpověď řekne, že model neoceňujeme (404 model_not_priced). Je to statistika z inzerovaných cen, ne cena skutečného prodeje.
Platí se za dotaz, nebo měsíčně?
Obojí: tarif zahrnuje měsíční objem volání a volání nad něj se neblokují, účtují se jednotlivě. Neúčtují se chyby požadavku, dočasný výpadek ani sandbox a u dávky se účtují jen nalezené VIN. Volání nad rámec tarifu stojí na všech tarifech stejně; ceny najdete v ceníku pro portály a vývojáře. Pilot trvá 30 dní a nic nestojí.
Vyzkoušejte Proklepni API na vlastních datech
Pilot trvá 30 dní a nic nestojí. Řekněte nám, kde chcete data používat, a připravíme sandbox a první napojení podle vašeho provozu.
Ukázka běží na smyšlených datech. Ceník pro váš obor