Dostęp do VirtualCar360 API wymaga aktywnego klucza API.

Klucz API jest generowany indywidualnie dla klienta i może obsługiwać pojedyncze konto lub wiele kont w ramach grupy dealerskiej.

Aby uzyskać dostęp:

1. Skontaktuj się z działem wsparcia VirtualCar360.
2. Przekaż informacje o planowanej integracji.
3. Otrzymaj dane dostępowe.
4. Przeprowadź testy integracyjne.

• Nigdy nie publikuj klucza API po stronie przeglądarki.
• Przechowuj klucze w bezpiecznych magazynach sekretów.
• Regularnie rotuj klucze w przypadku incydentów bezpieczeństwa.

API VirtualCar360 wykorzystuje autoryzację za pomocą klucza API przekazywanego w parametrze key. Klucz API identyfikuje konto, lokalizację albo grupę kont, do których dana integracja ma dostęp.

Wszystkie endpointy API wymagają przekazania poprawnego klucza API. Bez poprawnego klucza API nie należy zakładać, że integracja będzie mogła pobrać dane galerii, zdjęcia, hotspoty albo linki do materiałów video.

Wszystkie endpointy API są dostępne pod adresem bazowym:

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

Przykład pełnego zapytania:

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

Parametr key jest wymagany w każdym zapytaniu do API.

Przykład:

?key=TWOJ_KLUCZ_API

VirtualCar360 może wykorzystywać różne typy kluczy API w zależności od modelu integracji.

Standardowy przypadek integracji to klucz API przypisany do jednej lokalizacji, jednego salonu albo jednego konta dealerskiego.

Taki klucz pozwala pobierać dane pojazdów należących do konkretnego konta VirtualCar360.

Przykładowe zastosowania:

• pojedynczy salon dealerski,
• jedna marka,
• jedna lokalizacja,
• jedna strona internetowa prezentująca pojazdy z jednego źródła.

Przykład zapytania:

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

W przypadku większych organizacji możliwe jest przygotowanie klucza grupowego. Klucz grupowy agreguje dane z wielu kont albo lokalizacji VirtualCar360.

Taki model jest przydatny, gdy jedna integracja ma obsługiwać wiele salonów lub wiele marek.

Przykładowe zastosowania:

• dealer wielomarkowy,
• grupa dealerska,
• portal prezentujący pojazdy z wielu lokalizacji,
• centralny system CRM albo DMS,
• jedna strona internetowa z ofertami wielu oddziałów.

Dzięki kluczowi grupowemu jedna integracja może pobierać dane z wielu kont bez konieczności wykonywania osobnej konfiguracji dla każdej lokalizacji.

Klucz API jest generowany podczas zakładania lub konfiguracji konta w systemie VirtualCar360.

Aby uzyskać klucz API, należy skontaktować się z supportem VirtualCar360 i przekazać informacje dotyczące planowanej integracji.

W zgłoszeniu warto podać:

• nazwę klienta lub dealera,
• lokalizację albo listę lokalizacji,
• informację, czy potrzebny jest klucz dla jednej lokalizacji czy klucz grupowy,
• planowane zastosowanie API,
• środowisko, w którym API będzie wykorzystywane,
• adresy systemów lub aplikacji, które będą korzystać z API,
• dane kontaktowe osoby odpowiedzialnej za integrację.

Po wygenerowaniu klucza support przekazuje dane dostępowe integratorowi albo osobie technicznej po stronie klienta.

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

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

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 https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/numberplates/WW4433E?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

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

Najczęstszy proces integracji wygląda następująco:

1. Uzyskaj klucz API od supportu VirtualCar360.
2. Wyszukaj galerię pojazdu po numerze VIN albo numerze rejestracyjnym.
3. Odczytaj id galerii z odpowiedzi API.
4. Przekaż id jako carId do endpointu /image-set.
5. Pobierz zestawy zdjęć, hotspoty oraz linki do materiałów video.
6. Wyświetl dane we własnej aplikacji albo zapisz je w systemie klienta.

Przykład procesu:

GET /vin/{vin}?key=TWOJ_KLUCZ_API

Odpowiedź zawiera id galerii:

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

Następnie użyj id jako carId:

GET /image-set?carId=10209937&key=TWOJ_KLUCZ_API

API i Player korzystają z danych VirtualCar360, ale są przeznaczone do innych scenariuszy.

Klucz API daje dostęp do danych przypisanych do konta lub lokalizacji. Należy traktować go jak dane poufne.

Zalecenia:

• nie zapisuj klucza API w publicznym repozytorium,
• nie umieszczaj klucza API bezpośrednio w kodzie frontendowym aplikacji,
• przechowuj klucz w zmiennych środowiskowych,
• wykonuj zapytania do API przez backend albo proxy serwerowe,
• nie loguj pełnych adresów URL zawierających key,
• nie przekazuj klucza osobom spoza zespołu integracyjnego,
• w przypadku podejrzenia wycieku skontaktuj się z supportem VirtualCar360,
• dla wielu lokalizacji używaj klucza grupowego zamiast wielu niezależnych kluczy w aplikacji frontendowej.

Najbezpieczniejszy model integracji polega na tym, że aplikacja frontendowa nie komunikuje się bezpośrednio z API VirtualCar360.

Zalecany przepływ:

1. Frontend wysyła żądanie do backendu klienta.
2. Backend klienta dodaje parametr key.
3. Backend wykonuje zapytanie do API VirtualCar360.
4. Backend zwraca do frontendu tylko dane potrzebne do wyświetlenia oferty.

Przykład:

Frontend klienta
  -> GET /api/vehicles/{vin}/gallery

Backend klienta
  -> GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/{vin}?key=TWOJ_KLUCZ_API

Backend klienta
  -> odpowiedź do frontendu bez ujawniania klucza API

import express from 'express';

const app = express();

const VIRTUALCAR_API_KEY = process.env.VIRTUALCAR_API_KEY;
const VIRTUALCAR_BASE_URL = 'https://img-out.virtualcar360.pl/api/v6.0/virtual-360';

app.get('/api/vehicles/:vin/gallery', async (req, res) => {
  try {
    const { vin } = req.params;

    const url = new URL(`${VIRTUALCAR_BASE_URL}/vin/${encodeURIComponent(vin)}`);
    url.searchParams.set('key', VIRTUALCAR_API_KEY);

    const response = await fetch(url);

    if (!response.ok) {
      return res.status(response.status).json({
        error: 'VirtualCar360 request failed',
      });
    }

    const data = await response.json();

    return res.json(data);
  } catch (error) {
    return res.status(500).json({
      error: 'Unexpected integration error',
    });
  }
});

app.listen(3000);

<?php

$vin = $_GET['vin'] ?? null;

if (!$vin) {
    http_response_code(400);
    echo json_encode(['error' => 'VIN is required']);
    exit;
}

$apiKey = getenv('VIRTUALCAR_API_KEY');
$baseUrl = 'https://img-out.virtualcar360.pl/api/v6.0/virtual-360';

$url = $baseUrl . '/vin/' . rawurlencode($vin) . '?key=' . rawurlencode($apiKey);

$response = file_get_contents($url);

if ($response === false) {
    http_response_code(500);
    echo json_encode(['error' => 'VirtualCar360 request failed']);
    exit;
}

header('Content-Type: application/json');
echo $response;

Jeżeli zapytanie nie zwraca oczekiwanych danych, sprawdź:

• czy parametr key został przekazany,
• czy klucz API jest poprawny,
• czy klucz ma dostęp do lokalizacji, z której pochodzi pojazd,
• czy używany jest właściwy typ klucza: lokalizacyjny albo grupowy,
• czy VIN, numer rejestracyjny albo carId są poprawne,
• czy pojazd posiada galerię w systemie VirtualCar360.

Typowe odpowiedzi API:

• Używaj HTTPS dla wszystkich zapytań do API.
• Przechowuj klucz API poza kodem źródłowym.
• Dla aplikacji frontendowych stosuj backend proxy.
• Dla integracji wielooddziałowych używaj klucza grupowego.
• Nie loguj pełnych adresów URL zawierających key.
• Stosuj limity i cache po stronie własnej aplikacji, jeżeli dane są często pobierane.
• Waliduj VIN, numer rejestracyjny i carId przed wysłaniem zapytania.
• W przypadku problemów z dostępem przekazuj supportowi pełny kontekst techniczny, ale nie publikuj klucza w zgłoszeniach publicznych.
• Oddziel konfigurację środowiska testowego i produkcyjnego, jeżeli integracja korzysta z wielu środowisk.

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

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

Autoryzacja API VirtualCar360 opiera się na parametrze key, który identyfikuje konto, lokalizację albo grupę kont. Klucz API jest wymagany w każdym zapytaniu i powinien być traktowany jako informacja poufna.

Dla prostych integracji z jedną lokalizacją wystarczy klucz lokalizacyjny. Dla dealerów wielooddziałowych lub systemów agregujących pojazdy z wielu źródeł zalecany jest klucz grupowy.

W przypadku integracji API najlepszą praktyką jest wykonywanie zapytań przez backend klienta, aby nie ujawniać klucza API w kodzie frontendowym.