Klucz API
Klucz niesprawdzony
Statystyki zapytań
Statystyki pojawią się po sprawdzeniu aktywnego klucza.
Dlaczego dane są czystsze
To nie tylko API, ale inteligentna warstwa zaufania do danych samochodowych.
Zmieniamy rozproszone ogłoszenia z wielu źródeł w jedną uporządkowaną, porównywalną i przewidywalną bazę. System usuwa szum, scala duplikaty, standaryzuje encje i daje dane, na których można budować produkt bez chaosu.
Raporty z inspekcji trafiają do jednego standardu danych
Źródła dostarczają inspekcje w różnych formatach, od strukturyzowanych API po skany i pliki PDF. Normalizujemy wnioski, kontrole, uszkodzenia, diagnostykę, multimedia i pliki do jednego przewidywalnego kontraktu, bez osobnych parserów dla każdego źródła.
Duplikaty wykrywamy nawet bez VIN
Gdy VIN nie jest dostępny, system porównuje zdjęcia, specyfikacje, historię ogłoszeń i dziesiątki sygnałów pośrednich. Decyzja o scaleniu opiera się na wielu wskaźnikach, dlatego efekt wygląda niemal jak magia.
Marki i modele trafiają do jednego standardu
Każda marka i model mogą mieć dziesiątki albo setki synonimów. Ta baza jest utrzymywana przez człowieka, bo porządku i wysokiej wiarygodności w tej warstwie nie można w pełni oddać AI.
Lokalizacje są dokładne i porównywalne
Każda lokalizacja jest mapowana do jednej wspólnej bazy: kraj, region, miasto i współrzędne. Samochód może otrzymać szerokość i długość geograficzną, co pozwala tworzyć inteligentne sortowanie, wyszukiwanie po promieniu i analitykę geograficzną.
Opcje samochodów mają własną standaryzację
Modele AI pomagają rozumieć złożone, lokalne i wielojęzyczne nazwy opcji, a człowiek weryfikuje przypadki, w których model nie ma pewności. Efektem jest mocna, rozszerzalna taxonomy gotowa do filtrów.
Zapytania według dni
—Statystyki pojawią się po sprawdzeniu aktywnego klucza.
Zapytania według miesięcy
—Statystyki pojawią się po sprawdzeniu aktywnego klucza.
Ważna uwaga przed użyciem API
/cars służy do pobierania wszystkich samochodów. Używa paginacji scroll: serwer tworzy tymczasowy kontekst scroll, dlatego liczba zapytań kontynuujących taką paginację technicznie nie może być nieograniczona.
/search służy do wyszukiwania samochodów po filtrach. Nie ma technicznego limitu zapytań scroll, ale maksymalne okno paginacji jest ograniczone do 10k wyników.
Zalecany proces synchronizacji: 2-3 razy dziennie przejdź przez pełną listę przez /cars i zapisz otrzymane samochody. Każdy samochód, którego nie było w ostatnim zakończonym pełnym przebiegu, należy traktować w swoim systemie jako archiwalny.
Po archiwizacji samochód znika z /search i /cars, ale zwykle pozostaje w bazie jeszcze około 1 miesiąca. W tym czasie /cars/{car_id} i /listing/{domain_id}/{listing_id} mogą nadal go zwrócić ze znacznikiem archiwum. Po około 1 miesiącu może zniknąć także z tych endpointów.
Nowe pola pojazdu i ogłoszenia
Pola są dodawane bez zmiany istniejącego kontraktu. Wskazane pola logiczne są również filtrami /search i /search/count.
- cylinders
- Liczba cylindrów w głównym obiekcie samochodu.
- doors
- Liczba drzwi w głównym obiekcie samochodu.
- seats
- Liczba miejsc. /search i /search/count przyjmują seats jako dokładny filtr liczbowy.
- has_inspections
- Flaga inspekcji samochodu i filtr wyszukiwania. Pełne raporty są tylko w szczegółowych endpointach.
- has_history_reports
- Flaga dostępności historii samochodu i filtr wyszukiwania.
- listings[].has_history_reports
- Flaga historii dla konkretnego ogłoszenia.
- listings[].is_manufacturer_certified
- Certyfikacja przez producenta lub oficjalny program dealerski; dostępna także jako filtr.
- inspections
- Pełne publiczne raporty inspekcji w szczegółowych endpointach.
- vehicle_history_reports
- Pełne publiczne raporty historii przypisane do vehicle_ref danego ogłoszenia.
Raporty z inspekcji pojazdów
Samochód może zawierać ustandaryzowane raporty z inspekcji. Lekka flaga logiczna has_inspections oznacza, że z aktywnym ogłoszeniem powiązany jest co najmniej jeden opublikowany raport.
Działanie endpointów
- GET /search
- Zwraca tylko has_inspections. Tablica inspections jest celowo pomijana, aby odpowiedzi wyszukiwania pozostały małe.
- GET /cars
- Zwraca has_inspections i inspections. Tablica zawiera publiczne, opublikowane raporty powiązane z aktywnymi ogłoszeniami dostępnymi dla klucza API.
- GET /cars/{car_id}
- Zwraca wszystkie publiczne, opublikowane raporty powiązane z aktywnymi ogłoszeniami samochodu dostępnymi dla klucza API.
- GET /listing/{domain_id}/{listing_id}
- Zwraca raporty wyłącznie dla dokładnej pary domain_id i listing_id.
Publiczny format raportu
{
"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": "..."
}]
}Zasady kontraktu
- Gdy raport nie jest dostępny, inspections jest pustą tablicą.
- Zwracane są tylko raporty o widoczności public i statusie innym niż archived.
- Raporty są sortowane malejąco po system_updated_at, następnie malejąco po created_at i rosnąco po report_id.
- language określa język raportu źródłowego, a nie interfejsu. Standardowe klucze należy tłumaczyć w aplikacji klienckiej.
- id identyfikuje obiekt tylko wewnątrz raportu i nie jest kluczem tłumaczenia. Tłumacz kanoniczne block_key, part_key, location_key, result_key i inne udokumentowane pola *_key; nie buduj słowników z abrewiacji dostawcy.
- Tłumacz, gdy występują: 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; oraz type_key w media, files i limitations.
- result_key jest znormalizowanym wynikiem ogólnym. Pełny aktualny zestaw to ok, issue, not_checked, not_applicable, not_equipped i unknown. None przy kontroli wycieku, Good i Adequate mogą prawidłowo oznaczać ok; unknown nigdy nie oznacza ok.
- Aktualne stabilne 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 i other. Stabilne block_key: exterior, interior, body_structure, mechanical, powertrain, electrical, equipment_operation, driver_assistance, tires_wheels, brakes, diagnostics, road_test, documents i other. part_key jest rozszerzalną, niezależną od źródła taxonomy wspólną dla wszystkich obecnych i przyszłych źródeł. Znaczenie istniejących wartości kanonicznych nie zmienia się, ale po ponownym przetworzeniu element może przejść z unknown do dokładniejszego klucza. Mogą dochodzić nowe wartości, dlatego potrzebny jest fallback. Używaj przestrzeni nazw pola, np. inspection.result.not_checked i inspection.issue_type.replaced.
- source_code identyfikuje pole źródłowe i może być słowem, ścieżką, liczbą albo pojedynczym symbolem, takim jak O. source_label nazywa kontrolę, a description zwykle zawiera dokładnie wybraną odpowiedź. To dane źródłowe, a nie stabilne klucze tłumaczeń.
- vehicle_snapshot to kontekst historyczny zapisany z raportem. Aktualne wartości z głównego obiektu samochodu mają pierwszeństwo.
- created_at to czas utworzenia u źródła. system_updated_at to czas zapisania lub odświeżenia raportu w warstwie danych API.
Zalecana prezentacja na frontendzie
Raporty historii pojazdu
Historia pojazdu jest oddzielnym, ustandaryzowanym raportem dla konkretnego ogłoszenia. Nie jest mieszana z inspekcją techniczną.
Działanie endpointów
- GET /search
- Zwraca tylko has_history_reports, bez tablicy vehicle_history_reports.
- GET /cars
- Zwraca flagę i pełne publiczne raporty dla aktywnych ogłoszeń dostępnych dla klucza.
- GET /cars/{car_id}
- Zwraca publiczne, opublikowane raporty aktywnych ogłoszeń samochodu.
- GET /listing/{domain_id}/{listing_id}
- Zwraca historię wyłącznie dla dokładnej pary domain_id i listing_id.
Publiczny format raportu
{
"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": "..."
}]
}Zasady kontraktu
- Raport należy do ogłoszenia, a nie do scalonego samochodu. Nie kopiuj go automatycznie do innego ogłoszenia.
- Brak raportu oznacza pustą tablicę vehicle_history_reports w szczegółowych endpointach. Dokładne wyszukiwanie może zwrócić niedawno zarchiwizowany samochód, ale tablice raportów na poziomie samochodu są budowane tylko z aktywnych ogłoszeń; użyj dokładnego endpointu listing, dopóki ogłoszenie jest przechowywane.
- Zwracane są tylko publiczne raporty o statusie innym niż archived.
- created_at pochodzi ze źródła, checked_at oznacza czas sprawdzenia, a system_updated_at techniczne odświeżenie w API.
- summary jest agregatem; events i checks pozostają szczegółowym dowodem.
- W słownikach używaj stabilnych checks type_key/result_key oraz events type_key/subtype_key/date_precision_key. Ta sama zasada dotyczy kanonicznych evidence_type_key, verification_key, status_key, organization_role_key, details[].key i innych udokumentowanych pól *_key. Dodawaj przestrzeń nazw pola, na przykład history.event.initial_registration.
- Tłumacz, gdy występują: 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; oraz type_key w media, files i limitations.
- Wartości history result_key: present, not_present, unknown, not_applicable. Dokładność daty: datetime, day, month, year, unknown. Typy zdarzeń: 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. Typy kontroli: 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. Znaczenie istniejących wartości kanonicznych nie zmienia się, ale ponowne przetworzenie może zastąpić unknown dokładniejszym kluczem. Mogą dochodzić nowe wartości, dlatego potrzebny jest czytelny fallback.
- id, source_code, source_label, description i surowe wartości nie są kluczami tłumaczeń. source_code zależy od źródła i może być ścieżką, liczbą taką jak 0, pojedynczym symbolem takim jak O lub inną wartością techniczną.
- API nie ujawnia numerów rejestracyjnych ani wewnętrznych processing_info i check_tokens.
Zalecana prezentacja na frontendzie
Wartości enum API
W zapytaniach API używaj numerycznego ID. Każda grupa pokazuje krótki podgląd; pełna lista umożliwia wyszukiwanie, wybór wartości dla /search i kopiowanie gotowych fragmentów.
Endpointy
Parametry są automatycznie dodawane do zapytania GET.
Zablokowane
Prompt dla agenta AI
Skopiuj ten blok i przekaż go do Codex, Claude, Copilot lub innego agenta AI, aby rozumiał API, limity, endpointy i aktualny kontekst klucza.