API key
Key nuk është verifikuar
Statistikat e kërkesave
Statistikat do të shfaqen pas verifikimit të një key aktiv.
Pse të dhënat janë më të pastra
Jo thjesht API, por një shtresë inteligjente besimi për të dhënat e makinave.
Ne i kthejmë listing-et e shpërndara nga shumë burime në një bazë të pastër, të krahasueshme dhe të parashikueshme. Sistemi heq zhurmën, bashkon dublikatat, standardizon entitetet dhe ju jep të dhëna mbi të cilat mund të ndërtoni pa kaos.
Raportet e inspektimit kthehen në një standard të përbashkët
Burimet i japin inspektimet në formate të ndryshme, nga API të strukturuara deri te skanimet dhe PDF-të. Ne standardizojmë përfundimet, kontrollet, dëmtimet, diagnostikën, mediat dhe skedarët në një kontratë të parashikueshme, pa parser të veçantë për çdo burim.
Dublikatat gjenden edhe pa VIN
Kur VIN mungon, sistemi krahason fotografitë, specifikimet, historinë e listing-eve dhe dhjetëra sinjale indirekte. Vendimi për bashkim merret nga shumë indikatorë, prandaj rezultati duket pothuajse si magji.
Markat dhe modelet kthehen në një standard
Çdo markë dhe model mund të ketë dhjetëra ose qindra sinonime. Kjo bazë mirëmbahet nga një njeri, sepse rendi dhe besueshmëria e lartë në këtë shtresë nuk mund t’i besohet plotësisht AI.
Lokacionet bëhen të sakta dhe të krahasueshme
Çdo lokacion lidhet me një bazë të përbashkët: shtet, rajon, qytet dhe koordinata. Makina merr gjerësi dhe gjatësi gjeografike, duke mundësuar renditje inteligjente, kërkim me rreze dhe analiza gjeografike.
Opsionet e makinave standardizohen në një sistem të veçantë
Modelet AI ndihmojnë me emra opsionesh të ndërlikuar, lokalë dhe shumëgjuhësh, ndërsa njeriu përfshihet kur modeli nuk është i sigurt. Kështu taxonomy mbetet e fortë, e zgjerueshme dhe e përdorshme për filtra.
Kërkesa sipas ditëve
—Statistikat do të shfaqen pas verifikimit të një key aktiv.
Kërkesa sipas muajve
—Statistikat do të shfaqen pas verifikimit të një key aktiv.
Shënim i rëndësishëm para përdorimit të API
/cars përdoret për të shkarkuar të gjitha makinat. Përdor scroll pagination: serveri krijon një scroll context të përkohshëm, prandaj numri i kërkesave për vazhdimin e kësaj pagination teknikisht nuk mund të jetë pa limit.
/search përdoret për kërkimin e makinave me filtra. Nuk ka këtë limit teknik të scroll requests, por dritarja maksimale e pagination është e kufizuar në 10k rezultate.
Procesi i rekomanduar i sinkronizimit: 2-3 herë në ditë kaloni të gjithë listën përmes /cars dhe ruani makinat e marra. Çdo makinë që nuk ishte në kalimin e fundit të plotë duhet të konsiderohet e arkivuar në sistemin tuaj.
Kur makina arkivohet, ajo zhduket nga /search dhe /cars, por zakonisht mbetet në bazë rreth 1 muaj. Gjatë kësaj periudhe /cars/{car_id} dhe /listing/{domain_id}/{listing_id} mund ta kthejnë ende me një shenjë arkivi. Pas rreth 1 muaji mund të zhduket edhe nga këto endpoint-e.
Fushat e reja të makinës dhe listing-ut
Fushat shtohen pa ndryshuar kontratën ekzistuese. Fushat boolean të shënuara pranohen edhe si filtra në /search dhe /search/count.
- cylinders
- Numri i cilindrave në objektin kryesor të makinës.
- doors
- Numri i dyerve.
- seats
- Numri i vendeve; pranohet edhe si filtër i saktë në /search.
- has_inspections
- Flag për inspektim të disponueshëm dhe filtër kërkimi.
- has_history_reports
- Flag për histori të disponueshme dhe filtër kërkimi.
- listings[].has_history_reports
- Flag i historisë për listing-un konkret.
- listings[].is_manufacturer_certified
- Certifikim nga prodhuesi ose program zyrtar i dealer-it; gjithashtu filtër.
- inspections
- Array me raportet e plota publike të inspektimit në endpoint-et e detajuara.
- vehicle_history_reports
- Array me raportet e plota të historisë të lidhura me vehicle_ref të listing-ut.
Raportet e inspektimit të automjeteve
Një makinë mund të përmbajë raporte të standardizuara inspektimi. Flag-u boolean has_inspections tregon se të paktën një raport i publikuar lidhet me një listing aktiv.
Sjellja e endpoint-eve
- GET /search
- Kthen vetëm has_inspections. Array inspections lihet qëllimisht jashtë për t’i mbajtur përgjigjet e kërkimit kompakte.
- GET /cars
- Kthen has_inspections dhe inspections. Array përmban raporte publike të publikuara, të lidhura me listing-e aktive të dukshme për API key.
- GET /cars/{car_id}
- Kthen të gjitha raportet publike të publikuara, të lidhura me listing-et aktive të makinës dhe të dukshme për API key.
- GET /listing/{domain_id}/{listing_id}
- Kthen raporte vetëm për çiftin e saktë domain_id dhe listing_id.
Formati publik i raportit
{
"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": "..."
}]
}Rregullat e kontratës
- Kur nuk ka raport, inspections është një array bosh.
- Kthehen vetëm raportet me visibility public dhe status të ndryshëm nga archived.
- Raportet renditen sipas system_updated_at në zbritje, created_at në zbritje dhe pastaj report_id në rritje.
- language tregon gjuhën e raportit burimor, jo gjuhën e ndërfaqes. Përktheji key standard në aplikacionin klient.
- id identifikon një objekt vetëm brenda raportit dhe nuk është key për përkthim. Përkthe key kanonike block_key, part_key, location_key, result_key dhe fushat e tjera të dokumentuara *_key; mos krijo fjalorë nga shkurtesat e burimit.
- Përkthe kur janë të pranishme: 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; dhe type_key te media, files dhe limitations.
- result_key është rezultati i përgjithshëm i normalizuar. Bashkësia e plotë aktuale është ok, issue, not_checked, not_applicable, not_equipped dhe unknown. None për kontrollin e rrjedhjes, Good dhe Adequate mund të nënkuptojnë saktë ok; unknown nuk do të thotë kurrë ok.
- issue_type_keys stabile aktuale janë 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 dhe other. block_key stabile janë exterior, interior, body_structure, mechanical, powertrain, electrical, equipment_operation, driver_assistance, tires_wheels, brakes, diagnostics, road_test, documents dhe other. part_key është taxonomy e zgjerueshme dhe e pavarur nga burimi, e përbashkët për të gjitha burimet aktuale dhe të ardhshme. Kuptimi i vlerave kanonike ekzistuese nuk ndryshon, por pas ripërpunimit një element mund të kalojë nga unknown në një key më të saktë. Mund të shtohen vlera të reja, ndaj mbaj fallback. Përdor namespace sipas fushës, p.sh. inspection.result.not_checked dhe inspection.issue_type.replaced.
- source_code identifikon fushën e burimit dhe mund të jetë fjalë, path, numër ose simbol i vetëm si O. source_label emërton kontrollin dhe description zakonisht përmban përgjigjen e saktë të zgjedhur. Ato janë prova të burimit, jo key të qëndrueshme për përkthim.
- vehicle_snapshot është kontekst historik i ruajtur me raportin. Vlerat aktuale nga objekti kryesor i makinës kanë përparësi.
- created_at është koha e krijimit te burimi. system_updated_at është koha kur raporti u ruajt ose u rifreskua në shtresën e të dhënave API.
Paraqitja e rekomanduar në frontend
Raportet e historisë së automjetit
Historia është raport i veçantë dhe i standardizuar për një listing konkret. Nuk përzihet me inspektimin teknik.
Sjellja e endpoint-eve
- GET /search
- Kthen vetëm has_history_reports, pa vehicle_history_reports.
- GET /cars
- Kthen flag-un dhe raportet e plota publike për listing-et aktive të lejuara.
- GET /cars/{car_id}
- Kthen raportet publike të publikuara të listing-eve aktive të makinës.
- GET /listing/{domain_id}/{listing_id}
- Kthen historinë vetëm për çiftin e saktë domain_id dhe listing_id.
Formati publik i raportit
{
"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": "..."
}]
}Rregullat e kontratës
- Raporti i përket listing-ut, jo makinës së bashkuar. Mos e kopjo automatikisht në një listing tjetër.
- Kur nuk ka raport, vehicle_history_reports është array bosh. Kërkimi i saktë mund të kthejë një makinë të arkivuar së fundmi, por array-t e raporteve në nivel makine ndërtohen vetëm nga listimet aktive; përdor endpoint-in e saktë listing sa kohë listimi i arkivuar ruhet.
- Kthehen vetëm raportet public me status të ndryshëm nga archived.
- created_at vjen nga burimi, checked_at është koha e kontrollit dhe system_updated_at është rifreskimi teknik në API.
- summary është përmbledhje; events dhe checks mbeten provat e detajuara.
- Për fjalorët përdor checks type_key/result_key dhe events type_key/subtype_key/date_precision_key stabile. I njëjti rregull vlen për evidence_type_key, verification_key, status_key, organization_role_key, details[].key dhe fushat e tjera kanonike *_key. Përdor namespace të fushës, për shembull history.event.initial_registration.
- Përkthe kur janë të pranishme: 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; dhe type_key te media, files dhe limitations.
- Vlerat history result_key: present, not_present, unknown, not_applicable. Saktësia e datës: datetime, day, month, year, unknown. Llojet e ngjarjeve: 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. Llojet e kontrolleve: 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. Kuptimi i vlerave kanonike ekzistuese nuk ndryshon, por ripërpunimi mund ta zëvendësojë unknown me një key më të saktë. Mund të shtohen vlera të reja, ndaj mbaj një fallback të lexueshëm.
- id, source_code, source_label, description dhe vlerat e papërpunuara nuk janë key për përkthim. source_code varet nga burimi dhe mund të jetë path, numër si 0, simbol i vetëm si O ose vlerë tjetër teknike.
- API nuk kthen targa regjistrimi, processing_info ose check_tokens.
Paraqitja e rekomanduar në frontend
Vlerat enum të API
Përdor ID-në numerike në kërkesat API. Çdo grup tregon një pamje të shkurtër; lista e plotë lejon kërkim, zgjedhje për /search dhe kopjim të fragmenteve gati.
Endpoint-e
Parametrat shtohen automatikisht në kërkesën GET.
I bllokuar
Prompt për AI agent
Kopjo këtë bllok dhe dërgoja Codex, Claude, Copilot ose një AI agent tjetër që të kuptojë API, limitet, endpoint-et dhe kontekstin aktual të key.