# 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.


Wskazówka
Jeżeli chcesz tylko osadzić gotową prezentację pojazdu, użyj Playera. Jeżeli chcesz samodzielnie pobrać zdjęcia i zbudować własny widok, użyj API.

## Base URL

Adres produkcyjny API:

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

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

## Autoryzacja

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

Przykład:

```txt
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**.

Bezpieczeństwo
W przypadku bezpośrednich zapytań do API nie zaleca się umieszczania klucza API w kodzie frontendowym. Najbezpieczniejszy model integracji to backend proxy po stronie klienta.

## Najważniejsze pojęcia

### Galeria

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ęć

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

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.

### Video

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.

## Endpointy

| Metoda | Endpoint | Opis |
|  --- | --- | --- |
| `GET` | `/vin/{vin}` | Pobiera najnowszą galerię po numerze VIN. |
| `GET` | `/numberplates/{numberplates}` | Pobiera najnowszą galerię po numerze rejestracyjnym. |
| `GET` | `/list/vin/{vin}` | Pobiera listę galerii przypisanych do numeru VIN. |
| `GET` | `/list/numberplates/{numberplates}` | Pobiera listę galerii przypisanych do numeru rejestracyjnego. |
| `GET` | `/image-set` | Pobiera kompletny zestaw zdjęć, hotspoty i dane video dla galerii. |
| `GET` | `/idsWithNames` | Wyszukuje galerie po filtrach, takich jak VIN, numer rejestracyjny i zakres dat. |
| `POST` | `/add-announcement` | Dodaje ogłoszenie do systemu VirtualCar360. Endpoint przeznaczony dla integracji eksportujących dane. |


## Podział endpointów w API Reference

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

| Sekcja API Reference | Endpointy | Zastosowanie |
|  --- | --- | --- |
| **Wyszukiwanie galerii** | `/idsWithNames` | Wyszukiwanie galerii po filtrach, np. VIN, numerze rejestracyjnym lub zakresie dat. |
| **Listowanie galerii** | `/list/vin/{vin}`, `/list/numberplates/{numberplates}` | Pobieranie listy wszystkich galerii przypisanych do pojazdu. |
| **Najnowsza galeria** | `/vin/{vin}`, `/numberplates/{numberplates}` | Pobieranie najnowszej galerii pojazdu. |
| **Zdjęcia** | `/image-set` | Pobieranie zestawów zdjęć, hotspotów, danych video i zdjęć 1080p. |
| **Ogłoszenia** | `/add-announcement` | Dodawanie ogłoszeń przez integracje eksportujące dane. |


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.

## Typowy proces integracji

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

### Krok 1 — wyszukaj galerię pojazdu

Pobierz najnowszą galerię po numerze VIN:

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

albo po numerze rejestracyjnym:

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

Przykładowa odpowiedź:

```json
{
  "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.

### Krok 2 — pobierz zestaw zdjęć

```http
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.

## Pobieranie najnowszej galerii

### Po numerze VIN

```http
GET /vin/{vin}
```

Przykład:

```http
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.

### Po numerze rejestracyjnym

```http
GET /numberplates/{numberplates}
```

Przykład:

```http
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.

## Listowanie galerii

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

### Lista galerii po VIN

```http
GET /list/vin/{vin}
```

Przykład:

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

### Lista galerii po numerze rejestracyjnym

```http
GET /list/numberplates/{numberplates}
```

Przykład:

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

## Paginacja i sortowanie

Endpointy listujące obsługują parametry:

| Parametr | Opis |
|  --- | --- |
| `Sorting` | Kierunek sortowania. `1` oznacza ASC, `-1` oznacza DESC. |
| `Page` | Numer strony. Domyślnie `1`. |
| `PageSize` | Liczba wyników na stronę. Zakres `1–100`, domyślnie `20`. |


Przykład:

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

## Pobieranie zestawu zdjęć

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

```http
GET /image-set?carId={carId}
```

Przykład:

```http
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ź:

```json
{
  "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": []
}
```

## Typy zestawów zdjęć

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

| Typ | Opis |
|  --- | --- |
| `exterior-closed` | Zdjęcia zewnętrzne samochodu, zwykle z zamkniętymi drzwiami. |
| `additional` | Zdjęcia dodatkowe, na przykład detale, wnętrze lub zdjęcia uzupełniające. |


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

## Pole `type`

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:

```txt
3000_2250_8_JPG_SKODAPLUS
```

Interpretacja:

| Segment | Wartość | Opis |
|  --- | --- | --- |
| szerokość | `3000` | Szerokość zdjęcia w pikselach. |
| wysokość | `2250` | Wysokość zdjęcia w pikselach. |
| liczba zdjęć | `8` | Liczba zdjęć w zestawie. |
| format | `JPG` | Format pliku. |
| standard | `SKODAPLUS` | Nazwa standardu fotograficznego. |


## Video w API

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

Przykład wartości pola `video`:

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

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

```js
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 w API

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:

```json
{
  "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.

## Wyszukiwanie po filtrach

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

Dostępne filtry:

| Parametr | Opis |
|  --- | --- |
| `vin` | Dokładny numer VIN. |
| `numberPlates` | Dokładny numer rejestracyjny. |
| `vinLike` | Fragment numeru VIN. |
| `numberPlatesLike` | Fragment numeru rejestracyjnego. |
| `createdAtFrom` | Data utworzenia od. |
| `createdAtTo` | Data utworzenia do. |
| `Sorting` | Kierunek sortowania. |
| `Page` | Numer strony. |
| `PageSize` | Liczba wyników na stronie. |


Przykład:

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

## Przykład integracji w JavaScript

```js
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 a Player

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

| Obszar | API | Player |
|  --- | --- | --- |
| Cel | Pobranie danych do własnej aplikacji | Gotowa prezentacja do osadzenia |
| Integracja | Backend, CRM, DMS, system klienta | `iframe` |
| UI | Budowany przez klienta | Dostarczany przez VirtualCar360 |
| Zdjęcia | Zwracane jako URL-e | Renderowane automatycznie |
| Hotspoty | Zwracane jako dane | Obsługiwane automatycznie w Playerze |
| Video | Zwracane jako linki | Widoczne w Playerze, jeśli dostępne |


## Kody odpowiedzi

| Kod | Znaczenie |
|  --- | --- |
| `200` | Zapytanie wykonane poprawnie. |
| `400` | Nieprawidłowe parametry zapytania. |
| `404` | Nie znaleziono galerii lub danych dla podanych kryteriów. |
| `500` | Błąd serwera. Skontaktuj się z supportem VirtualCar360. |


## Dobre praktyki

- 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`.


## Powiązany plik OpenAPI

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**.