Certificate

Certyfikat pojazdu VirtualCar360 może być udostępniany niezależnie od Playera za pomocą dedykowanego endpointu API. Endpoint pozwala pobrać linki do certyfikatu w kilku formach:

jako widget do osadzenia w iframe,
jako onepage, czyli pełna strona certyfikatu,
jako pliki PDF w dostępnych wersjach językowych.

Certyfikaty mogą być również widoczne bezpośrednio w Playerze, jeżeli są dostępne dla danej galerii lub pojazdu. Endpoint opisany w tej sekcji służy jednak do rozszerzonego procesu udostępniania certyfikatu niezależnie od Playera, na przykład we własnym systemie, stronie pojazdu, CRM, DMS albo portalu ogłoszeniowym.

Informacja

Jeżeli korzystasz z Playera, certyfikat może być widoczny bezpośrednio w jego interfejsie. Endpoint certyfikatu jest przeznaczony dla integracji, które chcą pobrać i wyświetlić certyfikat samodzielnie.

Dostęp do certyfikatów

Dostęp do endpointu wymaga apiKey. Klucz może zostać wydany przez support VirtualCar360:

dla pojedynczej lokalizacji,
dla całej organizacji,
dla grupy lokalizacji lub dealerów.

Zakres danych zwracanych przez endpoint zależy od uprawnień przypisanych do danego klucza.

Bezpieczeństwo

apiKey powinien być traktowany jako informacja poufna. Jeżeli certyfikat pobierany jest przez API, zalecane jest wykonywanie zapytania przez backend klienta, aby nie ujawniać klucza w kodzie frontendowym.

Endpoint

GET https://api-certificate.vc360.app/api/v1/{apiKey}/certificate/vin/{vin}

Przykład:

GET https://api-certificate.vc360.app/api/v1/a0d8eb5cd984c08a58e7b88a/certificate/vin/WVWZZZ3H5RE500898

Parametry ścieżki

Parametr	Typ	Wymagany	Opis
`apiKey`	`string`	tak	Klucz API wydany przez support VirtualCar360 dla lokalizacji, grupy lokalizacji albo całej organizacji.
`vin`	`string`	tak	Numer VIN pojazdu, dla którego ma zostać pobrany certyfikat.

Przykład zapytania cURL

curl -X GET \
  "https://api-certificate.vc360.app/api/v1/TWOJ_API_KEY/certificate/vin/WVWZZZ3H5RE500898"

Przykładowa odpowiedź

{
  "widget": "https://certificate.vc360.app/widget/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl",
  "onepage": "https://certificate.vc360.app/certificate/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl",
  "pdf": [
    {
      "language": "pl",
      "code": "pia-pdf",
      "fileUrl": "https://vc360inspectionstorage.blob.core.windows.net/inspectiondata/2025/pdf/example/example-pia-pdf-pl.pdf?..."
    },
    {
      "language": "en",
      "code": "pia-pdf",
      "fileUrl": "https://vc360inspectionstorage.blob.core.windows.net/inspectiondata/2025/pdf/example/example-pia-pdf-en.pdf?..."
    }
  ]
}

Uwaga

Adresy PDF mogą zawierać czasowe parametry dostępu. Nie należy zakładać, że link do pliku PDF będzie ważny bezterminowo.

Pola odpowiedzi

Pole	Typ	Opis
`widget`	`string`	URL do wersji widgetowej certyfikatu. Najlepszy wybór do osadzenia w `iframe` we własnej stronie lub systemie.
`onepage`	`string`	URL do pełnej strony certyfikatu. Może zostać otwarty jako osobna strona albo osadzony w `iframe`.
`pdf`	`array`	Lista dostępnych wersji PDF certyfikatu.
`pdf[].language`	`string`	Kod języka pliku PDF, np. `pl`, `en`.
`pdf[].code`	`string`	Kod typu dokumentu PDF, np. `pia-pdf`.
`pdf[].fileUrl`	`string`	URL do pliku PDF. Link może być czasowy.

Formy udostępniania certyfikatu

Widget jest przeznaczony do osadzenia we własnym interfejsie za pomocą iframe. Jest to zalecany wariant, jeżeli certyfikat ma być częścią strony szczegółów pojazdu albo panelu klienta.

Przykład:

<div class="certificate-widget-wrapper">
  <iframe
    src="https://certificate.vc360.app/widget/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl"
    title="Certyfikat pojazdu VirtualCar360"
    frameborder="0"
    allowfullscreen
  ></iframe>
</div>

.certificate-widget-wrapper {
  width: 100%;
  min-height: 720px;
}

.certificate-widget-wrapper iframe {
  width: 100%;
  height: 720px;
  border: 0;
}

Onepage

Onepage to pełna strona certyfikatu. Może być wykorzystana jako osobny link, przycisk Zobacz certyfikat albo osadzona w iframe.

Przykład linku:

<a
  href="https://certificate.vc360.app/certificate/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl"
  target="_blank"
  rel="noopener"
>
  Zobacz certyfikat pojazdu
</a>

Przykład osadzenia onepage w iframe:

<div class="certificate-onepage-wrapper">
  <iframe
    src="https://certificate.vc360.app/certificate/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl"
    title="Certyfikat pojazdu VirtualCar360"
    frameborder="0"
    allowfullscreen
  ></iframe>
</div>

.certificate-onepage-wrapper {
  width: 100%;
  min-height: 900px;
}

.certificate-onepage-wrapper iframe {
  width: 100%;
  height: 900px;
  border: 0;
}

PDF

Pole pdf zawiera listę dostępnych plików PDF. Każdy element listy reprezentuje jeden wariant językowy dokumentu.

Przykład wyświetlenia linków PDF:

<div class="certificate-pdf-links">
  <a
    href="https://vc360inspectionstorage.blob.core.windows.net/inspectiondata/2025/pdf/example/example-pia-pdf-pl.pdf?..."
    target="_blank"
    rel="noopener"
  >
    Pobierz certyfikat PDF — PL
  </a>

  <a
    href="https://vc360inspectionstorage.blob.core.windows.net/inspectiondata/2025/pdf/example/example-pia-pdf-en.pdf?..."
    target="_blank"
    rel="noopener"
  >
    Pobierz certyfikat PDF — EN
  </a>
</div>

Wersje językowe

Wersje widget, onepage oraz pdf mogą występować w wielu językach. Dostępne języki zależą od konfiguracji certyfikatu i danych zwróconych przez API.

Wersje językowe

Adresy widget i onepage mogą zawierać segment języka na końcu URL, na przykład:

/pl

Przykład wersji polskiej:

https://certificate.vc360.app/widget/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/pl

Jeżeli dostępne są inne wersje językowe, mogą zostać udostępnione analogicznie, na przykład:

https://certificate.vc360.app/widget/inspection-pia/1f093ac5-dd71-6f24-8abc-c735770b85d5/en

Pliki PDF zwracane są w tablicy pdf, gdzie język dokumentu określa pole language.

Przykład:

{
  "language": "en",
  "code": "pia-pdf",
  "fileUrl": "https://vc360inspectionstorage.blob.core.windows.net/inspectiondata/2025/pdf/example/example-pia-pdf-en.pdf?..."
}

Typowy proces integracji

Uzyskaj apiKey od supportu VirtualCar360.
Wywołaj endpoint certyfikatu dla wybranego numeru VIN.
Odczytaj z odpowiedzi pola widget, onepage i pdf.
Osadź widget w iframe albo pokaż link do onepage.
Udostępnij użytkownikowi pliki PDF w dostępnych językach.
Obsłuż przypadek, w którym certyfikat nie jest dostępny dla pojazdu.

Przykład integracji w JavaScript

async function getCertificateByVin({ apiKey, vin }) {
  const url = `https://api-certificate.vc360.app/api/v1/${encodeURIComponent(apiKey)}/certificate/vin/${encodeURIComponent(vin)}`;

  const response = await fetch(url);

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

  return response.json();
}

const certificate = await getCertificateByVin({
  apiKey: 'TWOJ_API_KEY',
  vin: 'WVWZZZ3H5RE500898',
});

console.log(certificate.widget);
console.log(certificate.onepage);
console.log(certificate.pdf);

Przykład renderowania widgetu

function renderCertificateWidget(certificate) {
  if (!certificate?.widget) {
    return '';
  }

  return `
    <iframe
      src="${certificate.widget}"
      title="Certyfikat pojazdu VirtualCar360"
      frameborder="0"
      allowfullscreen
      style="width: 100%; height: 720px; border: 0;"
    ></iframe>
  `;
}

Przykład renderowania linków PDF

function renderCertificatePdfLinks(certificate) {
  if (!certificate?.pdf?.length) {
    return '';
  }

  return certificate.pdf
    .map((item) => {
      const language = item.language.toUpperCase();

      return `
        <a href="${item.fileUrl}" target="_blank" rel="noopener">
          Pobierz certyfikat PDF — ${language}
        </a>
      `;
    })
    .join('');
}

Certyfikat w Playerze a endpoint API

Certyfikat może być widoczny bezpośrednio w Playerze, jeżeli jest dostępny dla danego pojazdu. W takim przypadku użytkownik może zobaczyć certyfikat w ramach gotowej prezentacji pojazdu.

Endpoint certyfikatu jest przeznaczony dla bardziej zaawansowanych integracji, które chcą:

wyświetlić certyfikat poza Playerem,
osadzić certyfikat w innym miejscu strony,
dodać przycisk Zobacz certyfikat,
pobrać pliki PDF,
wykorzystać certyfikat w CRM, DMS lub systemie administracyjnym,
udostępnić certyfikat w wielu językach.

Scenariusz	Zalecane rozwiązanie
Certyfikat jako część gotowej prezentacji pojazdu	Player
Certyfikat osadzony w osobnej sekcji strony	`widget` w `iframe`
Certyfikat jako osobna strona	`onepage`
Certyfikat do pobrania lub wysłania klientowi	`pdf`
Certyfikat w CRM lub DMS	endpoint API

Obsługa braku certyfikatu

Nie każdy pojazd musi posiadać certyfikat. Integracja powinna obsługiwać sytuacje, w których:

certyfikat nie istnieje dla podanego VIN,
klucz API nie ma dostępu do danej lokalizacji,
certyfikat nie posiada wersji PDF,
certyfikat nie posiada wybranej wersji językowej,
link PDF wygasł i wymaga ponownego pobrania z API.

Dobra praktyka

Nie zapisuj na stałe linków PDF z odpowiedzi API jako bezterminowych adresów. Jeżeli plik PDF ma czasowy URL, pobieraj aktualny link z API przed jego pokazaniem użytkownikowi.

Dobre praktyki

Pobieraj certyfikat przez backend klienta, aby nie ujawniać apiKey.
Używaj widget, gdy certyfikat ma być osadzony w stronie.
Używaj onepage, gdy certyfikat ma otwierać się jako osobna strona.
Używaj pdf, gdy użytkownik ma pobrać dokument lub przekazać go dalej.
Sprawdzaj, czy odpowiedź zawiera oczekiwane pola.
Obsługuj wiele wersji językowych.
Nie zakładaj, że certyfikat istnieje dla każdego pojazdu.
Nie przechowuj czasowych linków PDF jako stałych adresów.
Dla wielu lokalizacji używaj klucza organizacyjnego lub grupowego.

Najczęstsze problemy

Certyfikat nie został znaleziony

Sprawdź, czy:

VIN jest poprawny,
pojazd posiada certyfikat,
apiKey ma dostęp do właściwej lokalizacji,
certyfikat został już wygenerowany.

Link PDF nie działa

Możliwe przyczyny:

link PDF wygasł,
plik PDF nie jest dostępny w wybranym języku,
certyfikat został ponownie wygenerowany,
dostęp do pliku wymaga pobrania aktualnego URL z API.

W takim przypadku pobierz dane certyfikatu ponownie przez endpoint API.

Sprawdź, czy:

URL z pola widget jest poprawny,
certyfikat jest dostępny,
strona nie blokuje osadzania iframe,
iframe ma ustawioną odpowiednią wysokość,
użytkownik ma dostęp do internetu i domeny certificate.vc360.app.

Brakuje wersji językowej

Dostępne języki zależą od konfiguracji certyfikatu i danych zwróconych przez API. Jeżeli wymagana wersja językowa nie jest dostępna, skontaktuj się z supportem VirtualCar360.

Podsumowanie

Endpoint certyfikatu pozwala pobrać certyfikat pojazdu niezależnie od Playera. Odpowiedź zawiera link do widgetu, pełnej strony onepage oraz listę plików PDF w dostępnych wersjach językowych.

Certyfikat może być prezentowany bezpośrednio w Playerze, ale dedykowany endpoint API daje większą elastyczność: pozwala osadzać certyfikat w dowolnym miejscu strony, udostępniać pliki PDF i integrować dane certyfikatu z systemami klienta.

Certificate

Dostęp do certyfikatów

Endpoint

Parametry ścieżki

Przykład zapytania cURL

Przykładowa odpowiedź

Pola odpowiedzi

Formy udostępniania certyfikatu

Widget

Onepage

PDF

Wersje językowe

Typowy proces integracji

Przykład integracji w JavaScript

Przykład renderowania widgetu

Przykład renderowania linków PDF

Certyfikat w Playerze a endpoint API

Obsługa braku certyfikatu

Dobre praktyki

Najczęstsze problemy

Certyfikat nie został znaleziony

Link PDF nie działa

Widget nie wyświetla się w iframe

Brakuje wersji językowej

Podsumowanie

Czy to było pomocne?