# 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

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

Przykład:

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

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

## Przykładowa odpowiedź

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

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:

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

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

```html
<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`:

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

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

```html
<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:

```txt
/pl
```

Przykład wersji polskiej:

```txt
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:

```txt
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:

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

## Typowy proces integracji

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


## Przykład integracji w JavaScript

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

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

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

### Widget nie wyświetla się w iframe

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.