{ "openapi": "3.1.0", "info": { "title": "Kontrola-STK.cz API", "version": "1.0.0", "summary": "Historie vozidel z Registru silničních vozidel ČR pro firemní integrace.", "description": "REST API pro tarif Business: technické údaje, historie STK včetně závad, stav tachometru s detekcí stočení, vlastníci a provozovatelé, převod SPZ na VIN a vozidla podle IČO.\n\nAutentizace API klíčem (vytvoříte v https://kontrola-stk.cz/account/api). Limity: 1000 požadavků denně a 60 požadavků za minutu na účet.\n\nDokumentace: https://kontrola-stk.cz/api/docs", "termsOfService": "https://kontrola-stk.cz/vop", "contact": { "name": "Podpora Kontrola-STK.cz", "email": "michal.kunc@cloudcore.cz", "url": "https://kontrola-stk.cz/api/docs" } }, "servers": [ { "url": "https://kontrola-stk.cz/api/v1", "description": "Produkce" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Vozidla", "description": "Detail vozidla podle VIN a hodnocení rizik." }, { "name": "SPZ", "description": "Převod registrační značky na VIN." }, { "name": "Firmy", "description": "Vozidla vlastněná nebo provozovaná firmou (IČO)." }, { "name": "Účet", "description": "Čerpání limitů a informace o klíči." } ], "paths": { "/vehicles/{vin}": { "get": { "tags": [ "Vozidla" ], "operationId": "getVehicle", "summary": "Detail vozidla podle VIN", "description": "Kompletní data vozidla z registru: technické údaje, registrace, historie STK se závadami, tachometr, vlastníci, dovoz, vyřazení a výbava. Parametrem `include` lze omezit vracené sekce (základní údaje a `summary` jsou vždy).", "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "VIN vozidla (17 znaků, bez I, O, Q). Nerozlišuje velikost písmen.", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$" }, "example": "TMBHG41U942882738" }, { "name": "include", "in": "query", "required": false, "description": "Čárkou oddělený seznam sekcí: technical, registration, inspections, odometer, owners, imports, deregistrations, equipment. Bez parametru se vrací vše.", "schema": { "type": "string" }, "example": "inspections,odometer" } ], "responses": { "200": { "description": "Detail vozidla", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Minute-Limit": { "$ref": "#/components/headers/X-RateLimit-Minute-Limit" }, "X-RateLimit-Minute-Remaining": { "$ref": "#/components/headers/X-RateLimit-Minute-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "vin": "TMBHG41U942882738", "make": "ŠKODA", "model": "OCTAVIA", "variant": "SEALHX01 FM5", "type": "ŠKODA OCTAVIA 1U / 1U", "kind": "OSOBNÍ AUTOMOBIL", "category": "M1", "body": "AC KOMBI", "status": { "code": "registered", "label": "PROVOZOVANÉ" }, "first_registration": "2004-01-22", "first_registration_cz": "2004-01-22", "year": 2004, "color": "ŠEDÁ-METAL", "fuel": "NM", "summary": { "inspections_count": 18, "defects_count": 26, "owners_count": 9, "last_inspection": "2026-03-12", "last_result": "passed", "next_inspection": "2028-03-11", "next_inspection_days": 519, "last_odometer_km": 332511, "odometer_rollback": true }, "engine": { "code": "ALH", "manufacturer": "VOLKSWAGEN, AG, WOLFSBURG, SRN", "displacement_ccm": 1896, "power_kw": 66, "max_speed_kmh": 182, "electric": false, "hybrid": false }, "emissions": { "standard": "EURO 3", "co2": "184 / 116 / 140", "consumption": "6.8 / 4.3 / 5.2" }, "dimensions": { "length": 4613, "width": 1731, "height": 1510, "wheelbase": 2500 }, "weights": { "curb_kg": 1360, "max_kg": 1875, "max_trailer_braked_kg": 1300, "max_trailer_unbraked_kg": 500 }, "seats": 5, "registration": { "plate": null, "plate_type": "STD. SILNIČNÍ", "tp_number": null, "orv_number": "UBO690169", "pcv": "3695492", "purpose": "Běžný provoz", "type_approval": "3460-445-02" }, "inspections": [ { "date": "2026-03-12", "type": "Opakovaná", "result_code": 1, "result": "passed", "result_label": "Způsobilé", "odometer_km": 332511, "next_inspection": "2028-03-11", "station": { "name": "DROUŽKOVICKÁ 476, 43141, ÚDLICE", "code": "3536", "city": "Údlice", "region": "Ústecký kraj" }, "protocol_number": "CZ-3536-26-03-0587", "emission_check": true, "defects": [ { "code": "2.1.3.7.1", "severity": "A", "description": "Prachovky pohyblivých spojů pákového mechanismu řízení jsou poškozené." } ] }, { "date": "2026-03-11", "type": "Pravidelná", "result_code": 2, "result": "passed_with_defects", "result_label": "Způsobilé s vadami", "odometer_km": 332500, "next_inspection": "2026-04-10", "station": { "name": "DROUŽKOVICKÁ 476, 43141, ÚDLICE", "code": "3536", "city": "Údlice", "region": "Ústecký kraj" }, "protocol_number": "CZ-3536-26-03-0492", "emission_check": true, "defects": [ { "code": "8.2.1.2.5", "severity": "B", "description": "U vozidel s OBD sdělovač MI (MIL) se po zapnutí zapalování nerozsvítí nebo po nastartování vozidla indikuje závadu." }, { "code": "4.1.4.3.2", "severity": "B", "description": "Nepovolená úprava světlometu." } ] } ], "odometer": { "last_km": 332511, "records": 18, "km_per_year": 11578, "rollback_detected": true, "rollbacks": [ { "date": "2016-01-25", "previous_date": "2016-01-18", "from_km": 2131035, "to_km": 213366 } ] }, "owners": [ { "relation": "owner", "subject_type": "person", "name": null, "ico": null, "from": "2026-04-29", "to": null, "current": true }, { "relation": "owner", "subject_type": "company", "name": "AutoESA a.s.", "ico": "25627538", "from": "2022-07-08", "to": "2022-07-25", "current": false }, { "relation": "operator", "subject_type": "company", "name": "Grundfos Sales Czechia and Slovakia s.r.o.", "ico": "61975265", "from": "2004-01-22", "to": "2008-03-05", "current": false } ], "imports": [], "deregistrations": [], "equipment": [ { "type": "TAŽNÉ ZAŘÍZENÍ", "from": null, "to": null } ] }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } }, "400": { "description": "Neplatný VIN nebo parametr", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_vin": { "value": { "error": { "code": "invalid_vin", "message": "VIN musí mít 17 znaků (písmena A–Z kromě I, O, Q a číslice)." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/vehicles/{vin}/risk": { "get": { "tags": [ "Vozidla" ], "operationId": "getVehicleRisk", "summary": "Hodnocení rizik vozidla", "description": "Rizikové skóre 0–100 (vyšší = rizikovější), úroveň low / medium / high, seznam zjištění se závažností info / warning / danger a pozitivní zjištění.", "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "VIN vozidla (17 znaků, bez I, O, Q). Nerozlišuje velikost písmen.", "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$" }, "example": "TMBHG41U942882738" } ], "responses": { "200": { "description": "Hodnocení rizik", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Minute-Limit": { "$ref": "#/components/headers/X-RateLimit-Minute-Limit" }, "X-RateLimit-Minute-Remaining": { "$ref": "#/components/headers/X-RateLimit-Minute-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Risk" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "vin": "TMBHG41U942882738", "score": 45, "level": "high", "flags": [ { "code": "serious_defects", "severity": "warning", "title": "Vážné závady v historii", "detail": "4 vážné závady (kategorie B), naposledy 11.03.2026: Nepovolená úprava světlometu; U vozidel s OBD sdělovač MI (MIL) se po zapnutí zapalování…." }, { "code": "frequent_owner_changes", "severity": "warning", "title": "Časté změny vlastníka", "detail": "8 vlastníků v registru, z toho 5 za posledních 5 let; průměrná doba držení 2,8 roku." }, { "code": "short_current_ownership", "severity": "warning", "title": "Současný vlastník má vozidlo krátce", "detail": "Současný vlastník je zapsán teprve od 29.04.2026 (méně než 6 měsíců)." }, { "code": "odometer_inconsistency", "severity": "info", "title": "Nesrovnalost v zápisu tachometru", "detail": "Při prohlídce 25.01.2016 je zapsán stav, který neodpovídá okolním záznamům (pravděpodobně chyba zápisu na stanici STK)." } ], "positives": [ "Bez podezření na stočení tachometru (14 záznamů)", "Platná STK do 11.03.2028", "Žádná neúspěšná technická kontrola", "Vozidlo pochází z českého trhu (bez dovozu)" ] }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } }, "400": { "description": "Neplatný VIN", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_vin": { "value": { "error": { "code": "invalid_vin", "message": "VIN musí mít 17 znaků (písmena A–Z kromě I, O, Q a číslice)." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "description": "Hodnocení rizik je dočasně nedostupné", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_available": { "value": { "error": { "code": "not_available", "message": "Hodnocení rizik není momentálně k dispozici. Zkuste to prosím později." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/plates/{spz}": { "get": { "tags": [ "SPZ" ], "operationId": "getPlate", "summary": "Převod SPZ na VIN", "description": "Vyhledá vozidlo podle registrační značky a vrátí VIN se základními údaji. Mezery a pomlčky se ignorují. Na API se nevztahuje hodinový limit webového převodu SPZ – počítá se do limitů API.\\n\\n**Upozornění: funkčnost tohoto endpointu není garantována.** Je poskytován „tak, jak je“, bez záruky dostupnosti, funkčnosti a správnosti výsledků, a může být kdykoliv bez upozornění omezen nebo ukončen. Provozovatel za jeho funkčnost neručí (VOP čl. 4.8 písm. f).", "parameters": [ { "name": "spz", "in": "path", "required": true, "description": "Registrační značka (5–10 znaků).", "schema": { "type": "string", "minLength": 5, "maxLength": 12 }, "example": "4T81234" } ], "responses": { "200": { "description": "Vozidlo k registrační značce", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Minute-Limit": { "$ref": "#/components/headers/X-RateLimit-Minute-Limit" }, "X-RateLimit-Minute-Remaining": { "$ref": "#/components/headers/X-RateLimit-Minute-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plate" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "plate": "4T81234", "vin": "TMBHG41U942882738", "make": "ŠKODA", "model": "OCTAVIA", "category": "M1", "fuel": "NM", "color": "ŠEDÁ-METAL", "first_registration": "2004-01-22", "status": { "code": "registered", "label": "PROVOZOVANÉ" } }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/companies/{ico}/vehicles": { "get": { "tags": [ "Firmy" ], "operationId": "getCompanyVehicles", "summary": "Vozidla firmy podle IČO", "description": "Seznam vozidel, u kterých je nebo byl subjekt s daným IČO vlastníkem či provozovatelem. Příznak `current` značí aktuální vztah. Řazení: aktuální vozidla první, poté podle data od.", "parameters": [ { "name": "ico", "in": "path", "required": true, "description": "IČO (až 8 číslic, kratší se doplní nulami zleva).", "schema": { "type": "string", "pattern": "^\\d{1,8}$" }, "example": "25596641" }, { "name": "status", "in": "query", "required": false, "description": "Filtr: all (výchozí), current, historical.", "schema": { "type": "string", "enum": [ "all", "current", "historical" ], "default": "all" } } ], "responses": { "200": { "description": "Vozidla firmy", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Minute-Limit": { "$ref": "#/components/headers/X-RateLimit-Minute-Limit" }, "X-RateLimit-Minute-Remaining": { "$ref": "#/components/headers/X-RateLimit-Minute-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyVehicles" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "ico": "25596641", "total": 2, "current_count": 1, "historical_count": 1, "vehicles": [ { "vin": "TMBDS23U939025601", "make": "ŠKODA", "model": "SUPERB", "category": "M1", "fuel": "NM", "color": "ŠEDÁ-METAL", "year": 2002, "first_registration": "2002-11-06", "status": { "code": "registered", "label": "PROVOZOVANÉ" }, "current": true, "relations": [ "operator" ], "from": "2002-11-06", "to": null }, { "vin": "WOL000031V7127033", "make": "OPEL", "model": "VECTRA CARAVAN", "category": "M1", "fuel": "BA 95 B", "color": "MODRÁ-TMAVÁ", "year": 1997, "first_registration": "1997-01-01", "status": { "code": "terminated", "label": "ZÁNIK" }, "current": false, "relations": [ "operator" ], "from": "2002-02-01", "to": "2003-06-30" } ] }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "$ref": "#/components/responses/BadGateway" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/usage": { "get": { "tags": [ "Účet" ], "operationId": "getUsage", "summary": "Čerpání limitů", "description": "Aktuální čerpání denního a minutového limitu účtu a informace o použitém klíči. Tento požadavek se do limitu také započítává.", "responses": { "200": { "description": "Čerpání limitů", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Minute-Limit": { "$ref": "#/components/headers/X-RateLimit-Minute-Limit" }, "X-RateLimit-Minute-Remaining": { "$ref": "#/components/headers/X-RateLimit-Minute-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Usage" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "plan": "business", "subscription_valid_until": "2027-10-09T19:36:15+02:00", "daily": { "limit": 1000, "used": 128, "remaining": 872, "resets_at": "2026-10-10T00:00:00+02:00" }, "minute": { "limit": 60, "used": 3, "remaining": 57 }, "key": { "id": 12, "name": "Skladový systém", "prefix": "kstk_3fa94c2", "created_at": "2026-09-01T10:15:00+02:00", "last_used_at": "2026-10-09T14:31:58+02:00" } }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "kstk_live_…", "description": "Hlavička `Authorization: Bearer kstk_live_…`" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternativně hlavička `X-API-Key: kstk_live_…`" } }, "headers": { "X-Request-Id": { "description": "Jedinečný identifikátor požadavku (uveďte při kontaktu s podporou).", "schema": { "type": "string" }, "example": "req_4f1c2a9be07d3a51c6e2" }, "X-RateLimit-Limit": { "description": "Denní limit požadavků účtu.", "schema": { "type": "integer" }, "example": 1000 }, "X-RateLimit-Remaining": { "description": "Zbývající požadavky do konce dne (Europe/Prague).", "schema": { "type": "integer" }, "example": 872 }, "X-RateLimit-Reset": { "description": "Unix timestamp obnovení denního limitu (nejbližší půlnoc Europe/Prague).", "schema": { "type": "integer" }, "example": 1791583200 }, "X-RateLimit-Minute-Limit": { "description": "Limit požadavků za 60 sekund.", "schema": { "type": "integer" }, "example": 60 }, "X-RateLimit-Minute-Remaining": { "description": "Zbývající požadavky v aktuálním minutovém okně.", "schema": { "type": "integer" }, "example": 57 }, "Retry-After": { "description": "Počet sekund, po kterých lze požadavek zopakovat.", "schema": { "type": "integer" }, "example": 17 } }, "responses": { "BadRequest": { "description": "Neplatný vstup", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_vin": { "value": { "error": { "code": "invalid_vin", "message": "VIN musí mít 17 znaků (písmena A–Z kromě I, O, Q a číslice)." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "Unauthorized": { "description": "Chybějící, neplatný nebo zneplatněný API klíč", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_api_key": { "value": { "error": { "code": "invalid_api_key", "message": "Neplatný API klíč." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "Forbidden": { "description": "Účet nemá aktivní tarif Business nebo je zablokován", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "business_required": { "value": { "error": { "code": "business_required", "message": "API je součástí tarifu Business, který u tohoto účtu není aktivní. Obnovte si předplatné na https://kontrola-stk.cz/premium." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "NotFound": { "description": "Záznam nebyl v registru nalezen", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "Vozidlo s VIN TMBHG41U942882739 nebylo v registru nalezeno." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "TooManyRequests": { "description": "Překročen minutový nebo denní limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limit_exceeded": { "value": { "error": { "code": "rate_limit_exceeded", "message": "Příliš mnoho požadavků – limit je 60 požadavků za minutu. Zkuste to znovu za chvíli." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } }, "BadGateway": { "description": "Zdroj dat je dočasně nedostupný", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "upstream_error": { "value": { "error": { "code": "upstream_error", "message": "Zdroj dat registru vozidel je dočasně nedostupný. Zkuste to prosím později." }, "meta": { "request_id": "req_4f1c2a9be07d3a51c6e2", "generated_at": "2026-10-09T14:32:05+02:00" } } } } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifikátor požadavku (shodný s hlavičkou X-Request-Id)." }, "generated_at": { "type": "string", "description": "Čas vytvoření odpovědi (ISO 8601).", "format": "date-time" } }, "required": [ "request_id", "generated_at" ] }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Strojově čitelný kód chyby.", "enum": [ "invalid_vin", "invalid_plate", "invalid_ico", "invalid_parameter", "missing_api_key", "invalid_api_key", "revoked_api_key", "business_required", "account_blocked", "not_found", "rate_limit_exceeded", "daily_limit_exceeded", "internal_error", "upstream_error", "not_available" ] }, "message": { "type": "string", "description": "Popis chyby v češtině." } }, "required": [ "code", "message" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "error", "meta" ] }, "Status": { "type": [ "object", "null" ], "description": "Stav vozidla v registru.", "properties": { "code": { "type": "string", "description": "Normalizovaný stav.", "enum": [ "registered", "deregistered", "terminated", "unregistered", "other" ] }, "label": { "type": "string", "description": "Původní hodnota z registru (např. PROVOZOVANÉ, ZÁNIK)." } }, "required": [ "code", "label" ] }, "Summary": { "type": "object", "properties": { "inspections_count": { "type": "integer" }, "defects_count": { "type": "integer", "description": "Součet závad ze všech prohlídek." }, "owners_count": { "type": "integer", "description": "Počet zápisů vlastníka v historii." }, "last_inspection": { "type": [ "string", "null" ], "format": "date", "description": "Datum poslední prohlídky." }, "last_result": { "type": [ "string", "null" ], "description": "Výsledek poslední prohlídky.", "enum": [ "passed", "passed_with_defects", "failed", "repeat_required", "unknown", null ] }, "next_inspection": { "type": [ "string", "null" ], "format": "date", "description": "Termín příští STK dle poslední prohlídky." }, "next_inspection_days": { "type": [ "integer", "null" ], "description": "Počet dní do příští STK (záporné = po termínu)." }, "last_odometer_km": { "type": [ "integer", "null" ] }, "odometer_rollback": { "type": "boolean", "description": "Zda byl zjištěn pokles stavu tachometru." } } }, "Engine": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Typ motoru." }, "manufacturer": { "type": [ "string", "null" ] }, "displacement_ccm": { "type": [ "integer", "null" ] }, "power_kw": { "type": [ "number", "null" ] }, "max_speed_kmh": { "type": [ "integer", "null" ] }, "electric": { "type": [ "boolean", "null" ] }, "hybrid": { "type": [ "boolean", "null" ] } } }, "Emissions": { "type": "object", "properties": { "standard": { "type": [ "string", "null" ], "description": "Emisní stupeň (např. EURO 6)." }, "co2": { "type": [ "string", "null" ], "description": "Emise CO2 dle TP (g/km, může obsahovat více hodnot oddělených lomítkem)." }, "consumption": { "type": [ "string", "null" ], "description": "Spotřeba (město / mimo město / kombinovaná)." } } }, "Dimensions": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "mm" }, "width": { "type": [ "integer", "null" ], "description": "mm" }, "height": { "type": [ "integer", "null" ], "description": "mm" }, "wheelbase": { "type": [ "integer", "null" ], "description": "Rozvor (mm)." } } }, "Weights": { "type": "object", "properties": { "curb_kg": { "type": [ "integer", "null" ], "description": "Provozní hmotnost." }, "max_kg": { "type": [ "integer", "null" ], "description": "Největší technicky přípustná hmotnost." }, "max_trailer_braked_kg": { "type": [ "integer", "null" ] }, "max_trailer_unbraked_kg": { "type": [ "integer", "null" ] } } }, "Registration": { "type": "object", "properties": { "plate": { "type": [ "string", "null" ], "description": "Registrační značka (pokud ji registr poskytuje)." }, "plate_type": { "type": [ "string", "null" ] }, "tp_number": { "type": [ "string", "null" ], "description": "Číslo technického průkazu." }, "orv_number": { "type": [ "string", "null" ], "description": "Číslo osvědčení o registraci (malý TP)." }, "pcv": { "type": [ "string", "null" ], "description": "Pořadové číslo vozidla v registru." }, "purpose": { "type": [ "string", "null" ], "description": "Účel využití." }, "type_approval": { "type": [ "string", "null" ], "description": "Číslo schválení technické způsobilosti." } } }, "Station": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] } } }, "Defect": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Kód závady dle metodiky STK." }, "severity": { "type": [ "string", "null" ], "description": "A = lehká, B = vážná, C = nebezpečná.", "enum": [ "A", "B", "C", null ] }, "description": { "type": [ "string", "null" ] } } }, "Inspection": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date" }, "type": { "type": [ "string", "null" ], "description": "Druh prohlídky (Pravidelná, Opakovaná, Evidenční kontrola…)." }, "result_code": { "type": [ "integer", "null" ], "description": "1 = způsobilé, 2 = způsobilé s vadami, 3 = nezpůsobilé, 4 = opakovaná prohlídka." }, "result": { "type": [ "string", "null" ], "enum": [ "passed", "passed_with_defects", "failed", "repeat_required", "unknown", null ] }, "result_label": { "type": [ "string", "null" ], "description": "Výsledek česky." }, "odometer_km": { "type": [ "integer", "null" ] }, "next_inspection": { "type": [ "string", "null" ], "format": "date" }, "station": { "$ref": "#/components/schemas/Station" }, "protocol_number": { "type": [ "string", "null" ] }, "emission_check": { "type": "boolean", "description": "Součástí bylo měření emisí." }, "defects": { "type": "array", "items": { "$ref": "#/components/schemas/Defect" } } } }, "Rollback": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date", "description": "Datum záznamu s nižším stavem." }, "previous_date": { "type": [ "string", "null" ], "format": "date" }, "from_km": { "type": "integer" }, "to_km": { "type": "integer" } } }, "Odometer": { "type": "object", "properties": { "last_km": { "type": [ "integer", "null" ] }, "records": { "type": "integer" }, "km_per_year": { "type": [ "integer", "null" ], "description": "Průměrný roční nájezd mezi prvním a posledním záznamem." }, "rollback_detected": { "type": "boolean" }, "rollbacks": { "type": "array", "items": { "$ref": "#/components/schemas/Rollback" } } } }, "Owner": { "type": "object", "properties": { "relation": { "type": "string", "enum": [ "owner", "operator" ] }, "subject_type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ], "description": "Název firmy; u fyzických osob vždy null." }, "ico": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": [ "string", "null" ], "format": "date" }, "current": { "type": "boolean" } } }, "Import": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date" }, "country": { "type": [ "string", "null" ] } } }, "Deregistration": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": [ "string", "null" ], "format": "date" }, "reason": { "type": [ "string", "null" ] } } }, "Equipment": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": [ "string", "null" ], "format": "date" } } }, "Vehicle": { "type": "object", "description": "Sekce engine, emissions, dimensions, weights a seats patří do skupiny „technical“; ostatní sekce mají stejný název jako hodnota parametru include.", "properties": { "vin": { "type": "string" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "Typové označení." }, "kind": { "type": [ "string", "null" ], "description": "Druh vozidla." }, "category": { "type": [ "string", "null" ], "description": "Kategorie (M1, N1, L3e…)." }, "body": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/Status" }, "first_registration": { "type": [ "string", "null" ], "format": "date" }, "first_registration_cz": { "type": [ "string", "null" ], "format": "date", "description": "První registrace v ČR." }, "year": { "type": [ "integer", "null" ], "description": "Rok výroby." }, "color": { "type": [ "string", "null" ] }, "fuel": { "type": [ "string", "null" ], "description": "Palivo dle registru (BA = benzin, NM = nafta, EL = elektřina…)." }, "summary": { "$ref": "#/components/schemas/Summary" }, "engine": { "$ref": "#/components/schemas/Engine" }, "emissions": { "$ref": "#/components/schemas/Emissions" }, "dimensions": { "$ref": "#/components/schemas/Dimensions" }, "weights": { "$ref": "#/components/schemas/Weights" }, "seats": { "type": [ "integer", "null" ] }, "registration": { "$ref": "#/components/schemas/Registration" }, "inspections": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" }, "description": "Od nejnovější." }, "odometer": { "$ref": "#/components/schemas/Odometer" }, "owners": { "type": "array", "items": { "$ref": "#/components/schemas/Owner" }, "description": "Od nejnovějšího." }, "imports": { "type": "array", "items": { "$ref": "#/components/schemas/Import" } }, "deregistrations": { "type": "array", "items": { "$ref": "#/components/schemas/Deregistration" } }, "equipment": { "type": "array", "items": { "$ref": "#/components/schemas/Equipment" } } }, "required": [ "vin", "summary" ] }, "RiskFlag": { "type": "object", "properties": { "code": { "type": "string", "description": "Kód zjištění (např. odometer_rollback)." }, "severity": { "type": "string", "description": "info = informace, warning = upozornění, danger = vážné riziko.", "enum": [ "info", "warning", "danger" ] }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "code", "severity", "title" ] }, "Risk": { "type": "object", "properties": { "vin": { "type": "string" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "string", "enum": [ "low", "medium", "high" ] }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/RiskFlag" }, "description": "Zjištění seřazená od nejzávažnějšího." }, "positives": { "type": "array", "items": { "type": "string" }, "description": "Pozitivní zjištění (česky)." } }, "required": [ "vin", "score", "level", "flags", "positives" ] }, "Plate": { "type": "object", "properties": { "plate": { "type": "string" }, "vin": { "type": "string" }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "fuel": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "first_registration": { "type": [ "string", "null" ], "format": "date" }, "status": { "$ref": "#/components/schemas/Status" } }, "required": [ "plate", "vin" ] }, "CompanyVehicle": { "type": "object", "properties": { "vin": { "type": [ "string", "null" ] }, "make": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "fuel": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ] }, "first_registration": { "type": [ "string", "null" ], "format": "date" }, "status": { "$ref": "#/components/schemas/Status" }, "current": { "type": "boolean", "description": "Firma je aktuálně vlastníkem nebo provozovatelem." }, "relations": { "type": "array", "items": { "type": "string", "enum": [ "owner", "operator" ] } }, "from": { "type": [ "string", "null" ], "format": "date", "description": "Začátek vztahu firmy k vozidlu." }, "to": { "type": [ "string", "null" ], "format": "date", "description": "Konec vztahu (null u aktuálních)." } } }, "CompanyVehicles": { "type": "object", "properties": { "ico": { "type": "string" }, "total": { "type": "integer" }, "current_count": { "type": "integer" }, "historical_count": { "type": "integer" }, "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyVehicle" } } }, "required": [ "ico", "total", "vehicles" ] }, "Usage": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "business" ] }, "subscription_valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "daily": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } } }, "minute": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } } }, "key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "externalDocs": { "description": "Dokumentace API", "url": "https://kontrola-stk.cz/api/docs" } }