API dla dystrybutorów

Jedno REST-owe API do stanów magazynowych i katalogu produktów VTAC. Odpowiedzi są w formacie JSON, znaczniki czasu w ISO 8601 (UTC), ceny jako liczby netto.

Adres bazowy

https://panel.b2bglobal.pl

Format

application/json

Od czego zacząć

Stany magazynowe zmieniają się często — odpytuj je na bieżąco, najlepiej zbiorczo przez /stock/batch. Katalog zmienia się rzadko — pobierz go raz na dobę przez /products?all=true i trzymaj u siebie.

Uwierzytelnianie

Każde zapytanie wymaga Twojego klucza API w nagłówku Authorization. Klucz dostajesz od operatora i widzisz go tylko raz — przy tworzeniu. Jeśli go zgubisz, poproś o rotację; stary klucz przestaje wtedy działać natychmiast.

Nagłówek

Authorization: Bearer dist_xxxxxxxx.yyyyyyyyyyyy

Traktuj klucz jak hasło

Trzymaj go w zmiennych środowiskowych po stronie serwera. Nie umieszczaj go w kodzie front-endu ani w repozytorium — klucz daje dostęp do całego katalogu i stanów.

curl -i "https://panel.b2bglobal.pl/api/v1/stock/meta" \
  -H "Authorization: Bearer $VTAC_API_KEY"

Limity zapytań

Twój klucz ma indywidualny limit zapytań na minutę (domyślnie 60). Po jego przekroczeniu dostaniesz 429 — odczekaj do początku kolejnej minuty i ponów. Niezależnie działa limit po stronie VTAC, dlatego 429 może pojawić się także przy niskim ruchu z Twojej strony.

Pytaj o wiele SKU jednym zapytaniem /stock/batch zamiast w pętli — 100 indeksów kosztuje jedno zapytanie zamiast stu.
Przy 429 stosuj wykładnicze wycofanie (1 s, 2 s, 4 s…) zamiast natychmiastowego ponawiania.
Katalog pobieraj cyklicznie, nie przy każdym wyświetleniu produktu.

Obsługa błędów

Błędy mają zawsze ten sam kształt: kod statusu HTTP i pole error z opisem. Nie polegaj na treści komunikatu — rozgałęziaj logikę po kodzie statusu.

Kod	Znaczenie	Kiedy
`200`	OK	Zapytanie się powiodło.
`400`	Błędne zapytanie	Nieprawidłowy JSON, pusta lub zbyt duża lista SKU (>100), błędne parametry stronicowania.
`401`	Brak autoryzacji	Brak nagłówka Authorization, zły format klucza albo klucz nieznany.
`403`	Dostęp wyłączony	Klucz jest poprawny, ale konto zostało wyłączone w panelu operatora.
`404`	Nie znaleziono	Produkt o podanym SKU nie istnieje w katalogu.
`429`	Limit zapytań	Przekroczony Twój limit na minutę albo chwilowy limit po stronie VTAC.
`500`	Błąd serwera	Nieoczekiwany błąd middleware.
`502`	Błąd źródła	VTAC odpowiedział błędem lub jest niedostępny.

Przykładowy błąd · 429

{
  "error": "Rate limit exceeded"
}

Nieznane SKU to nie błąd

Pytanie o indeks spoza magazynu zwraca 200 z known: false. Kodu 404 używamy wyłącznie dla produktów nieobecnych w katalogu.

Stany magazynowe

Dostępność w czasie zbliżonym do rzeczywistego. Odpowiedzi są cache'owane na krótko, żeby nie przeciążać źródła — dlatego pytanie o ten sam SKU kilka razy pod rząd jest tanie.

GET/api/v1/stock/{sku}

Stan pojedynczego SKU

Zwraca dostępność jednego indeksu. Nieznane SKU nie jest błędem — dostaniesz 200 z polem known: false.

Parametry

Nazwa	Typ	Opis
`sku`* w ścieżce	`string`	Indeks produktu.

* pole wymagane

Pola odpowiedzi

`sku`	`string`	Indeks produktu.
`known`	`boolean`	Czy SKU występuje w indeksie stanów VTAC. Gdy false, pozostałe pola mogą być puste.
`in_stock`	`boolean`	Czy produkt jest dostępny.
`stock_status`	`string`	Status tekstowy, np. in_stock / out_of_stock.
`available`	`number`	Dostępna ilość, jeśli VTAC ją udostępnia.
`as_of`	`string (ISO 8601)`	Moment, na który stan jest aktualny.
`stale`	`boolean`	Czy dane są starsze niż próg świeżości VTAC.

Kody odpowiedzi

200Stan produktu.
401Brak lub nieprawidłowy klucz.
429Przekroczony limit zapytań.
502VTAC niedostępny.

curl "https://panel.b2bglobal.pl/api/v1/stock/24426" \
  -H "Authorization: Bearer $VTAC_API_KEY"

Przykładowa odpowiedź · 200

{
  "sku": "24426",
  "known": true,
  "in_stock": true,
  "stock_status": "in_stock",
  "as_of": "2026-07-28T08:30:00.000Z",
  "stale": false
}

POST/api/v1/stock/batch

Stany wielu SKU naraz

Preferowany sposób odpytywania o więcej niż kilka indeksów — jedno zapytanie zamiast wielu. Maksymalnie 100 SKU. Jeśli źródło zawiedzie, a część danych jest w cache, otrzymasz odpowiedź częściową z flagą partial.

Parametry

Nazwa	Typ	Opis
`skus`* w treści	`string[]`	Lista indeksów, od 1 do 100 pozycji.

* pole wymagane

Pola odpowiedzi

`items`	`StockItem[]`	Stany w kolejności przesłanych SKU.
`partial`	`boolean`	Obecne tylko wtedy, gdy część danych pochodzi z cache, bo źródło było niedostępne.

Kody odpowiedzi

200Lista stanów.
400Pusta lista lub więcej niż 100 SKU.
401Brak lub nieprawidłowy klucz.
429Przekroczony limit zapytań.

curl -X POST "https://panel.b2bglobal.pl/api/v1/stock/batch" \
  -H "Authorization: Bearer $VTAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skus":["24426","11525"]}'

Treść zapytania

{
  "skus": [
    "24426",
    "11525"
  ]
}

Przykładowa odpowiedź · 200

{
  "items": [
    {
      "sku": "24426",
      "known": true,
      "in_stock": true,
      "stock_status": "in_stock"
    },
    {
      "sku": "11525",
      "known": true,
      "in_stock": false,
      "stock_status": "out_of_stock"
    }
  ]
}

GET/api/v1/stock/meta

Świeżość danych

Kiedy źródło ostatnio się zsynchronizowało i czy dane uznaje się za przestarzałe. Przydatne do wyświetlenia u siebie informacji „stan na godzinę…”.

Pola odpowiedzi

`latest_run_completed_at`	`string (ISO 8601)`	Koniec ostatniej synchronizacji.
`latest_item_synced_at`	`string (ISO 8601)`	Najnowszy zsynchronizowany rekord.
`sync_interval_minutes`	`number`	Co ile minut źródło się odświeża.
`stale_after_minutes`	`number`	Po ilu minutach dane uznaje się za przestarzałe.
`stale`	`boolean`	Czy dane są w tej chwili przestarzałe.

Kody odpowiedzi

200Metadane synchronizacji.
401Brak lub nieprawidłowy klucz.

curl "https://panel.b2bglobal.pl/api/v1/stock/meta" \
  -H "Authorization: Bearer $VTAC_API_KEY"

Przykładowa odpowiedź · 200

{
  "version": "1",
  "sync_interval_minutes": 15,
  "latest_run_completed_at": "2026-07-28T08:30:00.000Z",
  "latest_item_synced_at": "2026-07-28T08:29:12.000Z",
  "stale_after_minutes": 60,
  "stale": false
}

Katalog produktów

Dane produktowe: nazwy, kategorie, ceny netto, EAN-y i zdjęcia. Katalog jest odświeżany cyklicznie z plików źródłowych VTAC, więc zmienia się znacznie rzadziej niż stany magazynowe.

GET/api/v1/products

Lista produktów

Domyślnie stronicowana. Do pełnego zaciągnięcia katalogu (np. przy nocnej synchronizacji u siebie) użyj all=true — wtedy parametry stronicowania są ignorowane, a filtry nadal działają.

Parametry

Nazwa	Typ	Opis
`page` w zapytaniu	`integer`	Numer strony, od 1. Domyślnie 1.
`limit` w zapytaniu	`integer`	Liczba pozycji na stronie, od 1 do 100. Domyślnie 50.
`category` w zapytaniu	`string`	Dopasowanie dokładne do dowolnego z trzech poziomów kategorii.
`search` w zapytaniu	`string`	Fraza szukana w SKU, nazwie i kodzie EAN. Wielkość liter nie ma znaczenia.
`all` w zapytaniu	`boolean`	all=true (lub limit=all) zwraca cały katalog w jednej odpowiedzi.

* pole wymagane

Pola odpowiedzi

`items`	`Product[]`	Produkty na tej stronie.
`page`	`number`	Zwrócona strona.
`limit`	`number`	Rozmiar strony. Przy all=true równy liczbie zwróconych pozycji.
`total`	`number`	Łączna liczba produktów spełniających filtry.

Kody odpowiedzi

200Strona wyników.
400Nieprawidłowe parametry stronicowania.
401Brak lub nieprawidłowy klucz.

curl "https://panel.b2bglobal.pl/api/v1/products?page=1&limit=50&category=O%C5%9Bwietlenie" \
  -H "Authorization: Bearer $VTAC_API_KEY"

Przykładowa odpowiedź · 200

{
  "items": [
    {
      "sku": "24426",
      "name": "Panel LED 18W",
      "category_1": "Oświetlenie",
      "ean": "3800157627894",
      "catalog_price_net": 42.5,
      "sale_price_net": 38.9
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1234
}

GET/api/v1/products/{sku}

Szczegóły produktu

Pełny rekord produktu wraz z listą zdjęć posortowaną według kolejności wyświetlania. Zawiera też raw_data — komplet kolumn z pliku źródłowego, jeśli potrzebujesz pola, którego nie ma w modelu.

Parametry

Nazwa	Typ	Opis
`sku`* w ścieżce	`string`	Indeks produktu.

* pole wymagane

Pola odpowiedzi

`sku`	`string`	Indeks produktu (klucz główny).
`name`	`string \| null`	Nazwa handlowa.
`category_1..3`	`string \| null`	Trzy poziomy kategorii.
`model`	`string \| null`	Oznaczenie modelu.
`ean`	`string \| null`	Kod EAN.
`catalog_price_net`	`number \| null`	Cena katalogowa netto.
`sale_price_net`	`number \| null`	Cena wyprzedażowa netto.
`status`	`string \| null`	Status produktu wg VTAC.
`url_slug`	`string \| null`	Fragment adresu na stronie VTAC.
`product_url`	`string \| null`	Pełny adres karty produktu.
`raw_data`	`object`	Nieprzetworzony wiersz z CSV VTAC — wszystkie kolumny źródłowe.
`synced_at`	`string (ISO 8601)`	Kiedy rekord trafił do katalogu.
`images`	`ProductImage[]`	Zdjęcia posortowane rosnąco po sort_order.

Kody odpowiedzi

200Produkt ze zdjęciami.
401Brak lub nieprawidłowy klucz.
404Nie ma produktu o takim SKU.

curl "https://panel.b2bglobal.pl/api/v1/products/24426" \
  -H "Authorization: Bearer $VTAC_API_KEY"

Przykładowa odpowiedź · 200

{
  "sku": "24426",
  "name": "Panel LED 18W",
  "category_1": "Oświetlenie",
  "category_2": "Panele",
  "model": "PL-18",
  "ean": "3800157627894",
  "catalog_price_net": 42.5,
  "sale_price_net": 38.9,
  "status": "active",
  "product_url": "https://www.vtacexports.com/panel-led-18w",
  "synced_at": "2026-07-28T03:00:00.000Z",
  "images": [
    {
      "id": 1,
      "sku": "24426",
      "url": "https://…/24426-1.jpg",
      "sort_order": 0
    },
    {
      "id": 2,
      "sku": "24426",
      "url": "https://…/24426-2.jpg",
      "sort_order": 1
    }
  ]
}