Główne zastosowania API
REST API · v6.0
VirtualCar360
Dokumentacja API
Integracja API img-out.virtualcar360.pl umożliwia pobranie zdjęć i danych ogłoszeń 360° bezpośrednio do Twojej strony dealerskiej — według numeru VIN, tablicy rejestracyjnej lub identyfikatora pojazdu.
Niniejsza dokumentacja obejmuje API v6.0. Wszystkie ścieżki zaczynają się od prefiksu /api/v6.0/virtual-360/.
Autoryzacja — klucz API
Dostęp do każdego endpointu wymaga przekazania parametru key w query stringu. Klucz API jest unikalnym identyfikatorem przypisanym do konta lub kont w systemie VirtualCar360.
Standardowy przypadek — jeden klucz API przypisany do jednego konta dealerskiego. Idealny dla pojedynczego salonu lub marki.
Dealer wielomarkowy może uzyskać jeden klucz API, który agreguje dane z wielu kont VirtualCar360. Wszystkie pojazdy trafiają do jednej strony www za pomocą jednego zapytania.
Klucz API jest generowany podczas zakładania konta w systemie VirtualCar360. W przypadku integracji wielokontowej (dealer wielomarkowy) należy skontaktować się z supportem VirtualCar360 w celu skonfigurowania klucza zbiorczego.
Przykład użycia klucza
Base URL
Wszystkie endpointy są dostępne pod następującym adresem bazowym:
https://img-out.virtualcar360.pl/api/v6.0/virtual-360
Parametr key jest wymagany we wszystkich zapytaniach GET oraz w nagłówku/ciele zapytań POST.
Endpointy API
API udostępnia 6 endpointów GET do pobierania danych oraz 1 endpoint POST do dodawania ogłoszeń. Poniżej znajduje się pełna dokumentacja każdego z nich.
Zwraca listę ogłoszeń z nazwami. Umożliwia filtrowanie po VIN, tablicy rejestracyjnej, zakresie dat oraz sortowanie i stronicowanie wyników.
Parametry zapytania
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| key*wymagany | string | query | Klucz API |
| vinopcjonalny | string | query | Dokładny numer VIN pojazdu |
| numberPlatesopcjonalny | string | query | Dokładna tablica rejestracyjna |
| vinLikeopcjonalny | string | query | Część numeru VIN (wyszukiwanie częściowe) |
| numberPlatesLikeopcjonalny | string | query | Część tablicy rejestracyjnej (wyszukiwanie częściowe) |
| createdAtFromopcjonalny | date-time | query | Data dolna zakresu (ISO 8601). Zwraca ogłoszenia od tej daty |
| createdAtToopcjonalny | date-time | query | Data górna zakresu (ISO 8601). Zwraca ogłoszenia do tej daty |
| Sortingopcjonalny | integer | query | Kierunek sortowania: 1 = ASC (rosnąco), -1 = DESC (malejąco) |
| Pageopcjonalny | integer | query | Numer strony. Domyślnie: 1 |
| PageSizeopcjonalny | integer | query | Liczba wyników na stronie. Zakres: 1–100. Domyślnie: 20 |
Przykład zapytania
?key=TWOJ_KLUCZ
&vinLike=WBA
&Sorting=-1
&Page=1
&PageSize=20
Odpowiedzi
Zwraca stronicowaną listę wszystkich ogłoszeń przypisanych do danej tablicy rejestracyjnej.
Parametry
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| numberplates*wymagany | string | path | Dokładna tablica rejestracyjna |
| key*wymagany | string | query | Klucz API |
| Sortingopcjonalny | integer | query | 1 = ASC, -1 = DESC |
| Pageopcjonalny | integer | query | Numer strony. Domyślnie: 1 |
| PageSizeopcjonalny | integer | query | Wyniki na stronę: 1–100. Domyślnie: 20 |
Przykład zapytania
?key=TWOJ_KLUCZ&Sorting=-1&Page=1&PageSize=10
Odpowiedzi
Zwraca najnowszy rekord (ostatnio utworzony) powiązany z podaną tablicą rejestracyjną.
Parametry
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| numberplates*wymagany | string | path | Dokładna tablica rejestracyjna |
| key*wymagany | string | query | Klucz API |
Przykład zapytania
Odpowiedzi
Zwraca najnowszy rekord powiązany z danym numerem VIN.
Parametry
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| vin*wymagany | string | path | Dokładny numer VIN (17 znaków) |
| key*wymagany | string | query | Klucz API |
Przykład zapytania
Odpowiedzi
Zwraca stronicowaną listę wszystkich ogłoszeń przypisanych do danego numeru VIN.
Parametry
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| vin*wymagany | string | path | Dokładny numer VIN |
| key*wymagany | string | query | Klucz API |
| Sortingopcjonalny | integer | query | 1 = ASC, -1 = DESC |
| Pageopcjonalny | integer | query | Numer strony. Domyślnie: 1 |
| PageSizeopcjonalny | integer | query | Wyniki na stronę: 1–100. Domyślnie: 20 |
Przykład zapytania
?key=TWOJ_KLUCZ&Page=1&PageSize=10
Odpowiedzi
Zwraca zestawy zdjęć (image sets) przypisane do ogłoszenia identyfikowanego przez carId. Jest to główny endpoint do pobierania zdjęć na stronę.
Parametry zapytania
| Parametr | Typ | Źródło | Opis |
|---|---|---|---|
| carId*wymagany | integer | query | Identyfikator pojazdu/ogłoszenia (uzyskany z innych endpointów) |
| key*wymagany | string | query | Klucz API |
Przykład zapytania
1. Pobierz dane ogłoszenia przez /vin/{vin} lub /numberplates/{plates} → uzyskaj carId
2. Przekaż carId do /image-set → pobierz zestawy zdjęć
3. Wyświetl zdjęcia w galerii lub widoku 360° na swojej stronie
Odpowiedzi
Kody odpowiedzi HTTP
API zwraca standardowe kody HTTP. W przypadku błędów odpowiedź zawiera obiekt JSON z komunikatem statusu.
| Kod | Nazwa | Znaczenie |
|---|---|---|
| 200 | OK | Zapytanie wykonane pomyślnie. Odpowiedź zawiera dane. |
| 400 | Bad Request | Nieprawidłowe parametry lub walidacja danych nie powiodła się. Sprawdź format daty (ISO 8601), zakres PageSize (1–100) i obecność wymaganych pól. |
| 404 | Not Found | Nie znaleziono rekordu spełniającego podane kryteria. Sprawdź poprawność VIN/tablicy/carId. |
| 500 | Server Error | Wewnętrzny błąd serwera. Skontaktuj się z supportem VirtualCar360 podając szczegóły zapytania. |
Schematy obiektów
Poniżej opisano struktury danych używane w request body i response API.
"360", "gallery")1, 2 lub 3