{"openapi":"3.1.0","info":{"title":"B2BGlobal Middleware — API dla dystrybutorów","version":"1.0.0","description":"Stany magazynowe i katalog produktów VTAC. Uwierzytelnianie kluczem API w nagłówku Authorization. Znaczniki czasu w ISO 8601 (UTC), ceny netto."},"servers":[{"url":"https://panel.b2bglobal.pl"}],"tags":[{"name":"Stany magazynowe","description":"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."},{"name":"Katalog produktów","description":"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."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Klucz API dystrybutora w formacie dist_<id>.<sekret>, przekazywany jako `Authorization: Bearer <klucz>`."}}},"paths":{"/api/v1/stock/{sku}":{"get":{"operationId":"stockSku","summary":"Stan pojedynczego SKU","description":"Zwraca dostępność jednego indeksu. Nieznane SKU nie jest błędem — dostaniesz 200 z polem known: false.","tags":["Stany magazynowe"],"parameters":[{"name":"sku","in":"path","required":true,"description":"Indeks produktu.","schema":{"type":"string"},"example":"24426"}],"responses":{"200":{"description":"Stan produktu.","content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"known":{"type":"boolean"},"in_stock":{"type":"boolean"},"stock_status":{"type":"string"},"as_of":{"type":"string"},"stale":{"type":"boolean"}}},"example":{"sku":"24426","known":true,"in_stock":true,"stock_status":"in_stock","as_of":"2026-07-28T08:30:00.000Z","stale":false}}}},"401":{"description":"Brak lub nieprawidłowy klucz.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Przekroczony limit zapytań.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"description":"VTAC niedostępny.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/stock/batch":{"post":{"operationId":"stockBatch","summary":"Stany wielu SKU naraz","description":"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.","tags":["Stany magazynowe"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"}}}},"example":{"skus":["24426","11525"]}}}},"responses":{"200":{"description":"Lista stanów.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"known":{"type":"boolean"},"in_stock":{"type":"boolean"},"stock_status":{"type":"string"}}}}}},"example":{"items":[{"sku":"24426","known":true,"in_stock":true,"stock_status":"in_stock"},{"sku":"11525","known":true,"in_stock":false,"stock_status":"out_of_stock"}]}}}},"400":{"description":"Pusta lista lub więcej niż 100 SKU.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Brak lub nieprawidłowy klucz.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Przekroczony limit zapytań.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/stock/meta":{"get":{"operationId":"stockMeta","summary":"Świeżość danych","description":"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ę…”.","tags":["Stany magazynowe"],"responses":{"200":{"description":"Metadane synchronizacji.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"sync_interval_minutes":{"type":"integer"},"latest_run_completed_at":{"type":"string"},"latest_item_synced_at":{"type":"string"},"stale_after_minutes":{"type":"integer"},"stale":{"type":"boolean"}}},"example":{"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}}}},"401":{"description":"Brak lub nieprawidłowy klucz.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/products":{"get":{"operationId":"productsList","summary":"Lista produktów","description":"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ą.","tags":["Katalog produktów"],"parameters":[{"name":"page","in":"query","required":false,"description":"Numer strony, od 1. Domyślnie 1.","schema":{"type":"integer"},"example":"2"},{"name":"limit","in":"query","required":false,"description":"Liczba pozycji na stronie, od 1 do 100. Domyślnie 50.","schema":{"type":"integer"},"example":"50"},{"name":"category","in":"query","required":false,"description":"Dopasowanie dokładne do dowolnego z trzech poziomów kategorii.","schema":{"type":"string"},"example":"Oświetlenie"},{"name":"search","in":"query","required":false,"description":"Fraza szukana w SKU, nazwie i kodzie EAN. Wielkość liter nie ma znaczenia.","schema":{"type":"string"},"example":"panel"},{"name":"all","in":"query","required":false,"description":"all=true (lub limit=all) zwraca cały katalog w jednej odpowiedzi.","schema":{"type":"boolean"},"example":"true"}],"responses":{"200":{"description":"Strona wyników.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"category_1":{"type":"string"},"ean":{"type":"string"},"catalog_price_net":{"type":"number"},"sale_price_net":{"type":"number"}}}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}},"example":{"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}}}},"400":{"description":"Nieprawidłowe parametry stronicowania.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Brak lub nieprawidłowy klucz.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/products/{sku}":{"get":{"operationId":"productsDetail","summary":"Szczegóły produktu","description":"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.","tags":["Katalog produktów"],"parameters":[{"name":"sku","in":"path","required":true,"description":"Indeks produktu.","schema":{"type":"string"},"example":"24426"}],"responses":{"200":{"description":"Produkt ze zdjęciami.","content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"category_1":{"type":"string"},"category_2":{"type":"string"},"model":{"type":"string"},"ean":{"type":"string"},"catalog_price_net":{"type":"number"},"sale_price_net":{"type":"number"},"status":{"type":"string"},"product_url":{"type":"string"},"synced_at":{"type":"string"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"sku":{"type":"string"},"url":{"type":"string"},"sort_order":{"type":"integer"}}}}}},"example":{"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}]}}}},"401":{"description":"Brak lub nieprawidłowy klucz.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Nie ma produktu o takim SKU.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}