API

VirtualCar360 API umożliwia pobieranie danych galerii pojazdów, zestawów zdjęć, hotspotów oraz linków do materiałów video. API jest przeznaczone dla integracji, które chcą samodzielnie wykorzystać dane VirtualCar360 we własnej stronie internetowej, systemie CRM, systemie administracyjnym, portalu ogłoszeniowym albo narzędziu dealerskim.

API może być używane między innymi do:

• budowania listingów ofert,
• pobierania zdjęć pojazdów do własnej strony internetowej,
• archiwizacji zdjęć samochodów,
• importowania danych galerii do własnych systemów administracyjnych,
• integracji z systemami CRM lub DMS,
• zasilania systemów takich jak WebWizard lub inne narzędzia klienta,
• pobierania linków do materiałów video,
• pobierania hotspotów i zdjęć dodatkowych,
• budowania własnego interfejsu galerii pojazdu.

Adres produkcyjny API:

https://img-out.virtualcar360.pl/api/v6.0/virtual-360

Wszystkie endpointy opisane w tej sekcji znajdują się pod powyższym adresem bazowym.

Dostęp do API wymaga przekazania klucza API w parametrze query string key.

Przykład:

https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API

Klucz API może być przypisany do jednej lokalizacji albo do wielu lokalizacji w formie klucza grupowego. Szczegóły znajdują się w sekcji API Authorization.

Galeria reprezentuje sesję zdjęciową pojazdu. Jeden pojazd może posiadać więcej niż jedną galerię, na przykład wykonaną w różnym czasie albo w różnym standardzie zdjęć.

Podstawowy rekord galerii zawiera między innymi:

• id,
• name,
• vin,
• numberPlates,
• createdAt,
• type.

Pole id jest szczególnie ważne, ponieważ służy jako carId w endpoincie /image-set.

Zestaw zdjęć to kompletny zestaw zdjęć galerii. Endpoint /image-set zwraca dane potrzebne do zbudowania własnego widoku galerii, w tym:

• zestawy zdjęć,
• zdjęcia 1080p, jeżeli są dostępne,
• hotspoty,
• dane video,
• dane inspekcji, jeżeli są dostępne,
• metadane pojazdu i galerii.

Hotspot to oznaczony punkt na zdjęciu pojazdu. Może wskazywać konkretny element, na przykład reflektor, felgę, rysę albo uszkodzenie. Hotspot może posiadać zdjęcia dodatkowe pokazujące wskazany element w większym zbliżeniu.

Jeżeli dla galerii dostępny jest materiał video, API może zwrócić pole video. W obecnym modelu pole video może być stringiem zawierającym JSON z linkami do platform takich jak Vimeo lub YouTube.

W pliku OpenAPI endpointy są pogrupowane zgodnie z układem dokumentacji:

Dzięki temu wygenerowana sekcja API Reference w Redocly nie pokazuje technicznych nazw kontrolerów, takich jak VirtualCarControllerV lub VirtualCarControllerV2, tylko nazwy zrozumiałe dla integratora.

Najczęstszy proces integracji z API składa się z dwóch kroków.

Pobierz najnowszą galerię po numerze VIN:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API

albo po numerze rejestracyjnym:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/numberplates/WW4433E?key=TWOJ_KLUCZ_API

Przykładowa odpowiedź:

{
  "id": 10209937,
  "name": "WBA1234567890_skodaplus",
  "vin": "WBA1234567890",
  "numberPlates": "WW4433E",
  "createdAt": "2026-04-21T10:42:30.3038179",
  "type": "3000_2250_8_JPG_SKODAPLUS"
}

Wartość id z odpowiedzi wykorzystaj jako carId w kolejnym zapytaniu.

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set?carId=10209937&key=TWOJ_KLUCZ_API

Endpoint zwraca pełny obiekt galerii, w tym zestawy zdjęć, hotspoty i linki do materiałów video.

GET /vin/{vin}

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API

Użyj tego endpointu, jeżeli interesuje Cię aktualna, najnowsza galeria pojazdu.

GET /numberplates/{numberplates}

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/numberplates/WW4433E?key=TWOJ_KLUCZ_API

Ten endpoint jest przydatny, gdy system klienta identyfikuje pojazdy po numerze rejestracyjnym zamiast po numerze VIN.

Jeden pojazd może posiadać wiele galerii. Endpointy listujące pozwalają pobrać historię galerii przypisanych do konkretnego VIN albo numeru rejestracyjnego.

GET /list/vin/{vin}

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/vin/WBA1234567890?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

GET /list/numberplates/{numberplates}

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/numberplates/WW4433E?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

Endpointy listujące obsługują parametry:

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/vin/WBA1234567890?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

Endpoint /image-set jest głównym endpointem do pobierania zdjęć i danych galerii.

GET /image-set?carId={carId}

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set?carId=10209937&key=TWOJ_KLUCZ_API

Odpowiedź może zawierać:

• id,
• vin,
• numberPlates,
• type,
• inspection,
• video,
• hotspots,
• carImageSets,
• carImageSets1080p.

Przykładowa uproszczona odpowiedź:

{
  "id": "10209937",
  "vin": "WBA1234567890",
  "numberPlates": "WW4433E",
  "type": "3000_2250_8_JPG_SKODAPLUS",
  "inspection": null,
  "video": "{\"vimeo\":\"https://vimeo.com/1185086568/3943c5fe00\",\"youtube\":\"https://youtu.be/mQRMs7IyYtk\"}",
  "hotspots": [],
  "carImageSets": [
    {
      "type": "exterior-closed",
      "images": [
        {
          "url": "https://vc360prodeuwstorageacc.blob.core.windows.net/example/keyframe_1.jpg",
          "type": "exterior-closed"
        }
      ]
    }
  ],
  "carImageSets1080p": []
}

Najczęściej spotykane typy zestawów zdjęć:

Zakres typów może zależeć od standardu zdjęć i konfiguracji konta.

Pole type opisuje techniczny standard zdjęć. Może zawierać między innymi:

• szerokość zdjęcia,
• wysokość zdjęcia,
• liczbę zdjęć,
• format pliku,
• nazwę standardu.

Przykład:

3000_2250_8_JPG_SKODAPLUS

Interpretacja:

Jeżeli galeria posiada materiał video, pole video może zawierać string z JSON-em.

Przykład wartości pola video:

"{\"vimeo\":\"https://vimeo.com/1185086568/3943c5fe00\",\"youtube\":\"https://youtu.be/mQRMs7IyYtk\"}"

Aby odczytać linki, wykonaj JSON.parse():

if (data.video) {
  const video = JSON.parse(data.video);

  console.log(video.vimeo);
  console.log(video.youtube);
}

Jeżeli galeria nie posiada video, pole może mieć wartość null.

Hotspoty są zwracane w polu hotspots. Hotspot wskazuje konkretny punkt na zdjęciu i może posiadać powiązane zdjęcia dodatkowe albo materiały video.

Przykładowy hotspot:

{
  "imageId": "1f78b180-7f0b-4a8a-a6a4-2a2e95b36436",
  "ox": 45.5,
  "oy": 62.25,
  "category": 1,
  "categoryName": "Damage",
  "info": "Rysa na zderzaku",
  "relatedPhotos": [
    "7f2d4e6f-7e2c-41a3-a907-97be32f0b5de"
  ],
  "relatedVideos": []
}

Współrzędne ox i oy określają pozycję hotspotu na zdjęciu.

Endpoint /idsWithNames umożliwia wyszukiwanie galerii z użyciem filtrów.

Dostępne filtry:

Przykład:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/idsWithNames?key=TWOJ_KLUCZ_API&vinLike=WBA&Sorting=-1&Page=1&PageSize=20

async function getLatestGalleryByVin(vin, apiKey) {
  const url = new URL(
    `https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/${encodeURIComponent(vin)}`
  );

  url.searchParams.set('key', apiKey);

  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`VirtualCar360 API error: ${response.status}`);
  }

  return response.json();
}

async function getImageSet(carId, apiKey) {
  const url = new URL('https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set');

  url.searchParams.set('carId', carId);
  url.searchParams.set('key', apiKey);

  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`VirtualCar360 API error: ${response.status}`);
  }

  return response.json();
}

const gallery = await getLatestGalleryByVin('WBA1234567890', 'TWOJ_KLUCZ_API');
const imageSet = await getImageSet(gallery.id, 'TWOJ_KLUCZ_API');

console.log(imageSet.carImageSets);

API oraz Player rozwiązują podobny problem, ale w inny sposób.

• Używaj backend proxy i nie ujawniaj klucza API w kodzie frontendowym.
• Jeżeli masz carId, używaj /image-set bezpośrednio.
• Jeżeli masz VIN albo numer rejestracyjny, najpierw pobierz najnowszą galerię, a następnie użyj jej id.
• Dla listingów ofert stosuj cache po stronie własnego systemu, aby nie pobierać tych samych danych wielokrotnie.
• W przypadku wielu lokalizacji używaj klucza grupowego.
• Obsługuj sytuację, w której galeria nie posiada video albo hotspotów.
• Nie zakładaj, że każdy pojazd ma więcej niż jedną galerię.
• Przy listowaniu danych używaj paginacji.
• W logach nie zapisuj pełnych URL-i zawierających parametr key.

Szczegółowy opis endpointów, parametrów, schematów odpowiedzi i przykładów znajduje się w pliku openapi.json.

Plik może być użyty w Redocly jako źródło dla sekcji API Reference.