# FAQ Ta sekcja zawiera najczęściej zadawane pytania dotyczące integracji z VirtualCar360. Obejmuje Player, Player 360, konfigurację, video, API, autoryzację oraz typowe problemy występujące podczas wdrożenia. ## Ogólne ### Czym jest VirtualCar360? VirtualCar360 to rozwiązanie do prezentacji pojazdów online. Umożliwia wykorzystanie zdjęć samochodów, galerii 360°, Playera, Playera 360, hotspotów, materiałów video oraz API do integracji z własną stroną internetową, systemem CRM, DMS, portalem ogłoszeniowym albo innym systemem klienta. ### Czym różni się Player od API? Player to gotowy komponent do osadzenia na stronie jako `iframe`. Nie wymaga budowania własnej galerii ani obsługi zdjęć po stronie klienta. API służy do pobierania danych, takich jak galerie, zdjęcia, hotspoty i linki video. API jest najlepszym wyborem, gdy klient chce samodzielnie zbudować własny interfejs galerii lub zintegrować dane VirtualCar360 z własnym systemem. ### Kiedy użyć Playera? Playera warto użyć, gdy chcesz szybko osadzić gotową prezentację pojazdu na stronie internetowej. Typowe zastosowania: - listing ofert, - strona szczegółów pojazdu, - główny slider pojazdu, - dodatkowa galeria w opisie pojazdu, - prezentacja zdjęć, hotspotów, certyfikatu i video. ### Kiedy użyć Playera 360? Player 360 warto użyć, gdy chcesz zaprezentować płynny obrót samochodu o 360 stopni. Player 360 najlepiej sprawdza się jako główny element multimedialny na stronie szczegółów pojazdu. ### Kiedy użyć API? API warto użyć, gdy chcesz: - pobierać zdjęcia do własnej strony, - budować własną galerię, - archiwizować zdjęcia, - importować dane do CRM lub DMS, - integrować dane z systemem dealerskim, - pobierać hotspoty i linki video, - zasilać własne narzędzia lub systemy administracyjne. ## Dostęp i autoryzacja ### Jak uzyskać klucz API? Aby uzyskać klucz API, skontaktuj się z supportem VirtualCar360. Klucz może zostać przypisany do jednej lokalizacji albo do wielu lokalizacji jako klucz grupowy. ### Czy klucz API jest wymagany? Tak. Klucz API jest wymagany w zapytaniach do API oraz w adresie Playera, jeżeli Player ma pobierać dane z systemu VirtualCar360. ### Gdzie przekazać klucz API? W API klucz przekazywany jest jako parametr query string `key`. Przykład: ```txt https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API ``` W Playerze klucz również przekazywany jest w adresie URL. Przykład: ```txt https://virtualcar360.pl/player/?vin=WBA1234567890&key=TWOJ_KLUCZ_API ``` ### Czy mogę użyć jednego klucza dla wielu lokalizacji? Tak, ale wymaga to przygotowania klucza grupowego. Klucz grupowy może agregować dane z wielu kont lub lokalizacji VirtualCar360. W celu konfiguracji klucza grupowego skontaktuj się z supportem VirtualCar360. ### Czy powinienem umieszczać klucz API w kodzie frontendowym? Dla bezpośrednich zapytań do API nie jest to zalecane. Najbezpieczniejszy model to wykonywanie zapytań przez backend klienta albo proxy serwerowe. W przypadku Playera osadzanego przez `iframe` klucz jest przekazywany w adresie Playera. ## Player ### Jak osadzić Playera na stronie? Player jest osadzany za pomocą `iframe`. Przykład: ```html ``` ### Czy Player wymaga backendu? Nie. Player nie wymaga własnej integracji backendowej, jeżeli chcesz tylko osadzić gotową prezentację pojazdu. Wystarczy wkleić `iframe` z odpowiednim adresem. ### Czy Player może działać po numerze VIN? Tak. Player może pobierać dane po numerze VIN. Przykład: ```txt https://virtualcar360.pl/player/?vin=WBA1234567890&key=TWOJ_KLUCZ_API ``` ### Czy Player może działać po numerze rejestracyjnym? Tak. Player może pobierać dane po numerze rejestracyjnym. Przykład: ```txt https://virtualcar360.pl/player/?numberplates=WW4433E&key=TWOJ_KLUCZ_API ``` ### Czy Player wymaga `carId`? Nie zawsze. Player może automatycznie wyszukać najnowszą galerię po numerze VIN albo numerze rejestracyjnym. `carId` jest przydatny wtedy, gdy chcesz wskazać konkretną galerię. ### Czy Player zawsze pokazuje najnowszą galerię? Jeżeli przekazujesz `vin` albo `numberplates`, Player wybiera najnowszą dostępną galerię dla danego pojazdu. ### Czy Player obsługuje hotspoty? Tak, jeżeli hotspoty są dostępne dla danej galerii. Hotspoty mogą oznaczać konkretne elementy pojazdu, takie jak reflektor, felga, rysa, uszkodzenie albo element wyposażenia. ### Czy Player może pokazywać certyfikat pojazdu? Tak, jeżeli certyfikat jest dostępny i skonfigurowany dla danej galerii lub lokalizacji, Player może go prezentować jako część widoku pojazdu. ### Czy Player może pokazywać inne pojazdy? Tak, po odpowiedniej konfiguracji Player może wyświetlać sekcję **Inne pojazdy**. Do tego służy między innymi parametr `ann_dealer_id`. ## Player 360 ### Czym jest Player 360? Player 360 to wariant Playera przeznaczony do prezentacji płynnego obrotu pojazdu o 360 stopni. ### Czym Player 360 różni się od zwykłego Playera? Player 360 wykorzystuje większą liczbę klatek oraz szybsze tempo odtwarzania. W zależności od konfiguracji może wykorzystywać 180 albo 360 zdjęć. Zwykły Player służy głównie do prezentacji galerii zdjęć, a Player 360 do płynnego obrotu samochodu. ### Z ilu zdjęć powstaje Player 360? Zdjęcia dla Playera 360 mogą być generowane na podstawie 4 albo 8 oryginalnych ujęć samochodu. Klatki pomiędzy ujęciami są generowane przez AI. ### Czy klatki wygenerowane przez AI mają hotspoty? Nie. Klatki wygenerowane przez AI nie posiadają hotspotów. Hotspoty mogą być dostępne tylko na oryginalnych zdjęciach, jeżeli zostały oznaczone w systemie. ### Jak działa zoom w Playerze 360? Powiększenie działa przez pinch zoom na urządzeniach dotykowych albo przez kółko myszy na desktopie. Jeżeli użytkownik powiększa widok na klatce wygenerowanej przez AI, Player przewija samochód do najbliższej pozycji oryginalnego zdjęcia i wykonuje zoom na zdjęciu źródłowym. ### Czy implementacja Playera 360 różni się od zwykłego Playera? Nie. Implementacja jest taka sama. Player 360 jest osadzany przez `iframe` i może korzystać z tych samych parametrów identyfikujących pojazd, takich jak `vin`, `numberplates`, `carId` i `key`. ## Konfiguracja ### Jakie parametry konfiguracji obsługuje Player? Player obsługuje między innymi: - `key`, - `carId`, - `vin`, - `numberPlates`, - `numberplates`, - `lang`, - `autoplay`, - `hudhide`, - `bg`, - `slide_mode`, - `ann_dealer_id`, - `ann_show_more`, - `interior_fullscreen`. ### Jak ustawić język Playera? Do ustawienia języka służy parametr `lang`. Przykład: ```txt https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&lang=pl ``` Jeżeli parametr nie zostanie przekazany, Player próbuje użyć języka przeglądarki. Jeżeli język nie jest obsługiwany, używany jest fallback `en`. ### Jak zmienić kolor tła Playera? Do zmiany tła służy parametr `bg`. Przykład: ```txt https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&bg=black ``` Dla wartości HEX znak `#` należy zakodować jako `%23`. Przykład: ```txt https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&bg=%23ffffff ``` ### Jak ukryć HUD? Do sterowania HUD-em służy parametr `hudhide`. Przykłady: ```txt hudhide=-1 ``` HUD zawsze widoczny. ```txt hudhide=0 ``` HUD niewyświetlany. ```txt hudhide=5 ``` HUD znika po 5 sekundach bez interakcji. ### Jak włączyć sekcję „Inne pojazdy”? Do wyświetlenia sekcji **Inne pojazdy** użyj parametru `ann_dealer_id`. Przykład: ```txt https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&ann_dealer_id=72 ``` Jeżeli `ann_dealer_id` nie zostanie przekazany albo jego wartość nie jest liczbą, przycisk **Inne pojazdy** nie jest wyświetlany. ## Video ### Czy video jest dostępne domyślnie? Nie zawsze. Aby video było dostępne, należy skontaktować się z supportem VirtualCar360 i zgłosić chęć aktywacji tej funkcji. ### Jak wygląda domyślne video? Domyślne video przedstawia obrót samochodu o 360 stopni. Materiał trwa około 20 sekund i jest tworzony na podstawie 4 albo 8 zdjęć pojazdu. ### Gdzie zapisywane jest video? Video jest zapisywane w systemie VirtualCar360 oraz na Vimeo. Na życzenie klienta może być również automatycznie przesyłane na konto YouTube klienta. ### Czy video może być automatycznie publikowane na YouTube? Tak. Automatyczne przesyłanie video na YouTube wymaga wcześniejszej konfiguracji i autoryzacji konta klienta. ### Czy linki video są widoczne w Playerze? Tak, jeżeli video jest dostępne dla galerii. Linki do filmu w systemie VirtualCar360, Vimeo i YouTube mogą być widoczne w Playerze. ### Jak pobrać linki video przez API? Linki video mogą być dostępne w polu `video` zwracanym przez endpoint `/image-set`. Pole `video` może być stringiem zawierającym JSON. Przed użyciem należy wykonać `JSON.parse()`. Przykład: ```js if (data.video) { const video = JSON.parse(data.video); console.log(video.vimeo); console.log(video.youtube); } ``` ## API ### Jaki jest adres bazowy API? Adres bazowy API: ```txt https://img-out.virtualcar360.pl/api/v6.0/virtual-360 ``` ### Jak pobrać najnowszą galerię po VIN? ```http GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API ``` ### Jak pobrać najnowszą galerię po numerze rejestracyjnym? ```http GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/numberplates/WW4433E?key=TWOJ_KLUCZ_API ``` ### Jak pobrać listę galerii pojazdu? Po VIN: ```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 ``` Po numerze rejestracyjnym: ```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 ``` ### Jak pobrać zdjęcia galerii? Najpierw pobierz galerię po VIN albo numerze rejestracyjnym, a następnie użyj pola `id` jako `carId` w endpoincie `/image-set`. ```http GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set?carId=10209937&key=TWOJ_KLUCZ_API ``` ### Co zawiera `/image-set`? Endpoint `/image-set` może zwracać między innymi: - `id`, - `vin`, - `numberPlates`, - `type`, - `inspection`, - `video`, - `hotspots`, - `carImageSets`, - `carImageSets1080p`. ### Co oznacza pole `type`? Pole `type` opisuje techniczny standard zdjęć. Przykład: ```txt 3000_2250_8_JPG_SKODAPLUS ``` Może oznaczać: - szerokość zdjęcia, - wysokość zdjęcia, - liczbę zdjęć, - format pliku, - nazwę standardu zdjęć. ## Błędy i problemy ### Player nie wyświetla galerii. Co sprawdzić? Sprawdź, czy: - przekazano poprawny `key`, - przekazano poprawny `vin`, `numberplates` albo `carId`, - pojazd posiada galerię w systemie VirtualCar360, - klucz API ma dostęp do właściwej lokalizacji, - używasz właściwego środowiska. ### API zwraca `404`. Co to oznacza? Najczęściej oznacza to, że nie znaleziono galerii dla podanego VIN, numeru rejestracyjnego albo `carId`. Sprawdź poprawność danych pojazdu oraz dostęp klucza API do właściwej lokalizacji. ### API zwraca `400`. Co to oznacza? Najczęściej oznacza to nieprawidłowe parametry zapytania. Sprawdź, czy wszystkie wymagane parametry są przekazane i mają poprawny format. ### API zwraca `500`. Co zrobić? Błąd `500` oznacza błąd serwera. W takim przypadku skontaktuj się z supportem VirtualCar360 i przekaż szczegóły zapytania. ### Dlaczego video nie jest dostępne? Możliwe przyczyny: - funkcja video nie została aktywowana, - video nie zostało jeszcze wygenerowane, - galeria nie posiada materiału video, - integracja YouTube nie została skonfigurowana, - link YouTube nie jest dostępny dla danej galerii. ### Dlaczego hotspoty nie są widoczne? Możliwe przyczyny: - galeria nie posiada hotspotów, - hotspoty nie zostały oznaczone w systemie, - aktualny widok Playera 360 pokazuje klatkę wygenerowaną przez AI, - dana galeria nie obsługuje hotspotów. ### Dlaczego Player pokazuje inną galerię niż oczekiwano? Jeżeli Player działa po VIN albo numerze rejestracyjnym, wybiera najnowszą dostępną galerię. Jeżeli pojazd ma wiele galerii, wyświetlona może zostać ostatnio utworzona galeria. Aby wskazać konkretną galerię, użyj `carId`. ## Redocly i dokumentacja ### Czy OpenAPI powinien zawierać techniczne nazwy kontrolerów? Nie. W dokumentacji publicznej nie należy używać technicznych nazw takich jak `VirtualCarControllerV` albo `VirtualCarControllerV2`. Endpointy powinny być pogrupowane według funkcji biznesowej, na przykład: - **Wyszukiwanie galerii**, - **Listowanie galerii**, - **Najnowsza galeria**, - **Zdjęcia**, - **Ogłoszenia**. ### Czy dokumentacja Markdown i OpenAPI powinny mieć te same nazwy sekcji? Tak. Nazwy sekcji w dokumentacji opisowej i w API Reference powinny być możliwie spójne. Ułatwia to użytkownikowi przechodzenie między opisem procesu integracji a szczegółami endpointów. ### Co powinien zawierać każdy opis endpointu? Każdy endpoint powinien zawierać: - krótki opis zastosowania, - listę parametrów, - przykład zapytania, - przykładową odpowiedź, - możliwe kody błędów, - informację, kiedy używać danego endpointu. ## Support ### Kiedy skontaktować się z supportem? Skontaktuj się z supportem VirtualCar360, gdy: - potrzebujesz klucza API, - potrzebujesz klucza grupowego, - chcesz aktywować video, - chcesz skonfigurować YouTube, - Player nie wyświetla galerii, - API zwraca błąd serwera, - pojazd nie jest znajdowany mimo poprawnych danych, - potrzebujesz pomocy przy wdrożeniu produkcyjnym. ### Jakie informacje przekazać supportowi? W zgłoszeniu warto podać: - nazwę klienta lub lokalizacji, - VIN albo numer rejestracyjny pojazdu, - identyfikator `carId`, jeżeli jest znany, - opis problemu, - środowisko: testowe lub produkcyjne, - fragment odpowiedzi API, - zrzut ekranu, - adres zapytania bez ujawniania pełnego klucza API. ## Podsumowanie Jeżeli chcesz szybko osadzić prezentację pojazdu, użyj Playera albo Playera 360. Jeżeli chcesz samodzielnie pobierać i przetwarzać dane, użyj API. W przypadku braku danych, problemów z dostępem, konfiguracją video albo integracją YouTube skontaktuj się z supportem VirtualCar360.