API ключ
Ключът не е проверен
Статистика на заявките
Статистиката ще се появи след проверка на активен ключ.
Защо данните са по-чисти
Не просто API, а интелигентен слой за доверие в автомобилните данни.
Превръщаме разпръснати обяви от много източници в една подредена, сравнима и предвидима база. Системата премахва шума, слива дубликати, стандартизира обекти и ви дава данни, върху които може да се строи продукт без хаос.
Докладите от инспекции се привеждат към единен стандарт за данни
Източниците предоставят инспекциите в различни формати: от структурирани API до сканирани документи и PDF. Нормализираме заключенията, проверките, повредите, диагностиката, медиите и файловете в един предвидим договор, без отделни parser-и за всеки източник.
Дубликатите се откриват дори без VIN
Когато VIN липсва, системата сравнява снимки, характеристики, история на обявите и десетки косвени сигнали. Решението за сливане се взема по множество индикатори, затова резултатът изглежда почти като магия.
Марки и модели се привеждат към един стандарт
Всяка марка и модел може да има десетки или стотици синоними. Тази база се поддържа от човек, защото редът и високата достоверност в този слой не могат да бъдат поверени изцяло на AI.
Локациите стават точни и сравними
Всяка локация се привежда към единна база: държава, регион, град и координати. Автомобилът получава ширина и дължина, което позволява умно сортиране, търсене по радиус и географски анализи.
Опциите на автомобилите се стандартизират отделно
AI моделите помагат при сложни, локални и многоезични имена на опции, а човек се включва там, където моделът не е сигурен. Така taxonomy остава силна, разширяема и подходяща за филтри.
Заявки по дни
—Статистиката ще се появи след проверка на активен ключ.
Заявки по месеци
—Статистиката ще се появи след проверка на активен ключ.
Важно уточнение преди използване на API
/cars е предназначен за изтегляне на всички автомобили. Използва scroll пагинация: сървърът създава временен scroll контекст и броят заявки за продължаване на такава пагинация технически не може да бъде безлимитен.
/search е предназначен за търсене на автомобили по филтри. Той няма такова техническо ограничение за scroll заявки, но максималният прозорец на пагинацията е ограничен до 10k резултата.
Препоръчителен процес на синхронизация: 2-3 пъти дневно обходете пълния списък през /cars и запазете получените автомобили. Всеки автомобил, който не е присъствал в последното завършено пълно обхождане, трябва да се счита за архивен във вашата система.
Когато автомобилът се архивира, той изчезва от /search и /cars, но обикновено остава в базата още около 1 месец. През този период /cars/{car_id} и /listing/{domain_id}/{listing_id} все още могат да го върнат с отделна архивна маркировка. След около 1 месец автомобилът може да изчезне и от тези ендпоинти.
Нови полета на автомобила и обявата
Полетата са добавени, без да се променя съществуващият договор. Посочените boolean полета са и филтри за /search и /search/count.
- cylinders
- Брой цилиндри в основния обект на автомобила.
- doors
- Брой врати.
- seats
- Брой места; приема се и като точен филтър в /search.
- has_inspections
- Флаг за налична инспекция и филтър за търсене.
- has_history_reports
- Флаг за налична история и филтър за търсене.
- listings[].has_history_reports
- Флаг за историята на конкретната обява.
- listings[].is_manufacturer_certified
- Сертифициране от производител или официална дилърска програма; също е филтър.
- inspections
- Масив от пълни публични доклади от инспекции в подробните крайни точки.
- vehicle_history_reports
- Масив от пълни доклади за история, свързани с vehicle_ref на обявата.
Доклади от инспекции на автомобили
Автомобилът може да съдържа стандартизирани доклади от инспекции. Лекият булев флаг has_inspections означава, че към активна обява е свързан поне един публикуван доклад.
Поведение на крайните точки
- GET /search
- Връща само has_inspections. Масивът inspections умишлено се пропуска, за да останат отговорите при търсене компактни.
- GET /cars
- Връща has_inspections и inspections. Масивът съдържа публични публикувани доклади за активни обяви, достъпни за API ключа.
- GET /cars/{car_id}
- Връща всички публични публикувани доклади за активните обяви на автомобила, достъпни за API ключа.
- GET /listing/{domain_id}/{listing_id}
- Връща доклади само за точната двойка domain_id и listing_id.
Публичен формат на доклада
{
"schema_version": 1,
"mapper_contract_version": 1,
"report_id": "inspection_987654",
"uuid": null,
"status": "published",
"visibility": "public",
"language": "ko",
"inspected_at": "2026-05-31T04:20:00+00:00",
"valid_until": "2026-08-31T23:59:59+00:00",
"created_at": "2026-05-31T04:27:33+00:00",
"updated_at": null,
"system_updated_at": "2026-07-07T12:30:00+00:00",
"vehicle_ref": {
"domain_id": 123,
"listing_id": "987654",
"site_car_id": null,
"vin": "..."
},
"vehicle_snapshot": {
"title": "...", "brand": "...", "model": "...",
"year": 2024, "vin": "...", "mileage_km": 24000,
"fuel_type": "...", "transmission": "...", "engine_type": "..."
},
"source": {
"source_key": "provider", "source_type": "external_api",
"source_report_id": "987654", "source_language": "ko",
"mapper_version": "provider-v1", "imported_at": "..."
},
"access": {"attach_to_listing": true},
"participants": [{
"role_key": "inspector", "name": "...",
"company_id": 10, "user_id": 20, "source_label": "..."
}],
"conclusions": {
"overall_result_key": "issue", "accident_status_key": "issue",
"water_damage_status_key": "ok", "fire_damage_status_key": "ok",
"chemical_damage_status_key": "ok", "biohazard_status_key": "ok",
"notes": "..."
},
"source_claims": [{
"id": "claim_1", "type_key": "accident", "result_key": "issue",
"source_code": "...", "source_label": "...", "description": "..."
}],
"inspection_blocks": [{
"id": "exterior", "key": "exterior", "result_key": "issue",
"source_code": "...", "source_label": "...",
"description": "...", "sort_order": 10
}],
"checked_items": [{
"id": "item_1", "block_id": "exterior", "block_key": "exterior",
"part_key": "front_fender_left", "part_label": "...",
"location_key": "left_front", "location_label": "...",
"result_key": "issue", "issue_type_keys": ["replaced", "painted"],
"severity_key": "medium", "damage_rank_key": "rank_2",
"accident_relevance_key": "cosmetic", "source_code": "...",
"source_label": "...", "description": "...",
"recommendation_key": "monitor", "clarification": "...",
"evidence_media_ids": ["photo_1"], "visual_map_id": "body_map",
"visual_marker_id": "marker_1", "visual_marker_label": "X",
"visual_x": 42.5, "visual_y": 21.0,
"visual_width": 12.0, "visual_height": 8.0,
"visual_shape_key": "polygon",
"measurements": [{
"id": "measurement_1", "type_key": "paint_thickness",
"value_number": 210, "value_text": null, "unit_key": "micrometer",
"result_key": "issue", "description": "..."
}]
}],
"diagnostic_errors": [{
"id": "dtc_1", "system_key": "engine", "system_label": "...",
"code": "P0001", "description": "...", "status_key": "stored",
"severity_key": "medium", "source_label": "..."
}],
"media": [{
"id": "photo_1", "type_key": "inspection_photo",
"external_url": "https://...", "local_path": null, "server_id": null,
"description": "...", "block_id": "exterior",
"checked_item_id": "item_1", "sort_order": 1
}],
"files": [{
"id": "file_1", "type_key": "source_report",
"external_url": "https://...", "local_path": null, "server_id": null,
"original_name": "report.pdf", "extension": "pdf",
"description": "...", "block_id": null,
"checked_item_id": null, "sort_order": 1
}],
"limitations": [{
"id": "limit_1", "type_key": "partial_coverage",
"description": "...", "source_label": "..."
}]
}Правила на договора
- Когато няма наличен доклад, inspections е празен масив.
- Връщат се само доклади с видимост public и статус, различен от archived.
- Докладите се сортират низходящо по system_updated_at, после низходящо по created_at и възходящо по report_id.
- language определя езика на изходния доклад, а не езика на интерфейса. Стандартните ключове трябва да се превеждат в клиентското приложение.
- id идентифицира обект само в рамките на един доклад и не е ключ за превод. Превеждайте каноничните block_key, part_key, location_key, result_key и другите документирани полета *_key; не създавайте речници от съкращения на източника.
- Превеждайте при наличие: conclusions.*_result_key; source_claims type_key/result_key; inspection_blocks key/result_key; checked_items block_key/part_key/location_key/result_key/issue_type_keys/severity_key/damage_rank_key/accident_relevance_key/recommendation_key/visual_shape_key; measurements type_key/unit_key/result_key; diagnostic_errors system_key/status_key/severity_key; както и type_key в media, files и limitations.
- result_key е нормализираният общ резултат. Пълният текущ набор е ok, issue, not_checked, not_applicable, not_equipped и unknown. None при проверка за теч, Good и Adequate могат правилно да означават ok; unknown никога не означава ok.
- Текущите стабилни issue_type_keys са scratch, dent, crack, broken, missing, replaced, repaired, painted, corrosion, wear, leak, noise, malfunction, contamination, water_damage, fire_damage, chemical_damage, biohazard, structural_damage, damage, accident_trace и other. Стабилните block_key са exterior, interior, body_structure, mechanical, powertrain, electrical, equipment_operation, driver_assistance, tires_wheels, brakes, diagnostics, road_test, documents и other. part_key е разширяема, независима от източника taxonomy, обща за всички настоящи и бъдещи източници. Значението на съществуващите канонични стойности не се променя, но след повторна обработка елемент може да премине от unknown към по-точен ключ. Могат да се добавят нови стойности, затова е нужен fallback. Използвайте namespace по поле, например inspection.result.not_checked и inspection.issue_type.replaced.
- source_code идентифицира поле на източника и може да бъде дума, път, число или единичен символ като O. source_label назовава проверката, а description обикновено съдържа точния избран отговор. Това са доказателства от източника, а не стабилни ключове за превод.
- vehicle_snapshot е исторически контекст, записан с доклада. Текущите стойности от основния обект на автомобила са с приоритет.
- created_at е времето на създаване при източника. system_updated_at е времето на записване или обновяване на доклада в слоя с API данни.
Препоръчително представяне във frontend
Доклади за историята на автомобила
Историята е отделен стандартизиран доклад за конкретна обява и не се смесва с техническата инспекция.
Поведение на крайните точки
- GET /search
- Връща само has_history_reports, без vehicle_history_reports.
- GET /cars
- Връща флага и пълните публични доклади за достъпните активни обяви.
- GET /cars/{car_id}
- Връща публичните публикувани доклади на активните обяви на автомобила.
- GET /listing/{domain_id}/{listing_id}
- Връща историята само за точната двойка domain_id и listing_id.
Публичен формат на доклада
{
"schema_version": 1,
"mapper_contract_version": 1,
"report_id": "provider_vehicle_history_987654",
"status": "published",
"visibility": "public",
"language": "ko",
"created_at": "2026-05-31T04:27:33+00:00",
"checked_at": "2026-05-31T04:27:33+00:00",
"system_updated_at": "2026-07-07T12:30:00+00:00",
"vehicle_ref": {
"domain_id": 123, "listing_id": "987654",
"site_car_id": null, "vin": "..."
},
"vehicle_snapshot": {
"title": "...", "brand": "...", "model": "...",
"year": 2024, "vin": "...", "mileage_km": 24000,
"listing_id": "987654", "source_domain": "cars.example.com",
"fuel_type": "gasoline"
},
"source": {
"source_key": "provider_example", "source_type": "external_api",
"source_report_id": "987654", "source_language": "ko",
"mapper_version": "provider-history-v1", "imported_at": "..."
},
"access": {"attach_to_listing": true},
"coverage": {
"completeness_key": "complete", "period_start": "2024-01-01T00:00:00Z",
"period_end": "2026-05-31T00:00:00Z",
"section_keys": ["registration", "ownership", "insurance", "usage"]
},
"summary": {
"first_registered_at": "2024-01-15T00:00:00Z",
"owner_change_count": 1, "registration_change_count": 0,
"insurance_claim_count": 2, "vehicle_damage_claim_count": 1,
"vehicle_damage_claim_cost": 1200000,
"third_party_damage_claim_count": 1,
"third_party_damage_claim_cost": 350000,
"total_loss_count": 0, "flood_total_loss_count": 0,
"flood_partial_loss_count": 0, "theft_count": 0, "currency": "krw"
},
"checks": [{
"id": "check_1", "type_key": "total_loss_history", "result_key": "not_present",
"count": 0, "source_code": "...", "source_label": "...",
"description": "...", "evidence_type_key": "source_record",
"verification_key": "source_reported"
}],
"events": [{
"id": "event_1", "type_key": "owner_change",
"subtype_key": null, "occurred_at": "2025-03-01T00:00:00Z",
"ended_at": null, "date_precision_key": "day", "status_key": "completed",
"mileage_km": 18000, "source_code": "...", "source_label": "...",
"description": "...", "evidence_type_key": "source_record",
"verification_key": "source_reported", "organization_name": "...",
"organization_role_key": "insurer", "currency": "krw",
"amount_total": 1200000, "amount_insurance_benefit": 1000000,
"amount_parts": 500000, "amount_labor": 300000, "amount_painting": 400000,
"details": [{
"key": "transaction_type", "value_text": "private_transfer",
"value_number": null, "value_date": null, "unit_key": null,
"source_code": "...", "source_label": "..."
}]
}],
"media": [{
"id": "media_1", "type_key": "photo", "external_url": "https://...",
"local_path": null, "server_id": null, "original_name": "history.jpg",
"description": "...", "sort_order": 1
}],
"files": [{
"id": "file_1", "type_key": "source_report", "external_url": "https://...",
"local_path": null, "server_id": null, "original_name": "history.pdf",
"description": "...", "sort_order": 1
}],
"limitations": [{
"id": "limit_1", "type_key": "partial_coverage",
"description": "...", "source_label": "..."
}]
}Правила на договора
- Докладът принадлежи на обява, а не на обединения автомобил. Не го копирайте автоматично.
- При липса на доклад vehicle_history_reports е празен масив. Точно търсене може да върне наскоро архивиран автомобил, но масивите с доклади на ниво автомобил се събират само от активни обяви; използвайте точния listing endpoint, докато архивираната обява се пази.
- Връщат се само публични доклади със статус, различен от archived.
- created_at е времето на източника, checked_at е времето на проверка, а system_updated_at е техническото обновяване в API.
- summary е обобщение; events и checks остават подробните доказателства.
- За речници използвайте стабилните checks type_key/result_key и events type_key/subtype_key/date_precision_key. Същото правило важи за каноничните evidence_type_key, verification_key, status_key, organization_role_key, details[].key и другите документирани *_key полета. Използвайте namespace на полето, например history.event.initial_registration.
- Превеждайте при наличие: coverage completeness_key/section_keys; checks type_key/result_key/evidence_type_key/verification_key; events type_key/subtype_key/date_precision_key/status_key/evidence_type_key/verification_key/organization_role_key; details key/unit_key; както и type_key в media, files и limitations.
- Стойности на history result_key: present, not_present, unknown, not_applicable. Точност на датата: datetime, day, month, year, unknown. Типове събития: initial_registration, owner_change, registration_change, insurance_claim, insurance_coverage_started, insurance_coverage_gap, maintenance, statutory_inspection, recall, comparative_quote, total_loss, flood_damage, theft, usage_change. Типове проверки: accident_history, total_loss_history, flood_total_loss_history, flood_partial_loss_history, theft_history, lien_history, business_use_history, rental_use_history, government_use_history, insurance_gap_history, odometer_rollback. Значението на съществуващите канонични стойности не се променя, но повторна обработка може да замени unknown с по-точен ключ. Могат да се добавят нови стойности, затова е нужен четим fallback.
- id, source_code, source_label, description и суровите стойности не са ключове за превод. source_code зависи от източника и може да е път, число като 0, единичен символ като O или друга техническа стойност.
- API не връща регистрационни номера, processing_info и check_tokens.
Препоръчително представяне във frontend
Стойности на enum в API
Използвайте числовия ID в API заявките. Всяка група показва кратък преглед; пълният списък позволява търсене, избор на стойности за /search и копиране на готови фрагменти.
Ендпоинти
Параметрите се добавят автоматично към GET заявката.
Заключено
Промпт за AI агент
Копирайте този блок и го изпратете на Codex, Claude, Copilot или друг AI агент, за да разбере API, ограниченията, ендпоинтите и текущия контекст на ключа.