API & Dokumentacja dla deweloperów — CAN-BAR

CAN-BAR API – dokumentacja dla deweloperów i agentów AI

CAN-BAR API to publiczny interfejs sklepu can-bar.pl, oparty na WooCommerce Store API i WordPress REST API. Umożliwia agentom AI i deweloperom pobieranie katalogu produktów, kategorii, cen i treści blogowych bez rejestracji i bez klucza API.

Wszystkie endpointy odczytu są otwarte. Nie musisz nic konfigurować, żeby zacząć.

Spis treści

Szybki start – pierwsze zapytanie do CAN-BAR API

CAN-BAR API zwraca dane w formacie JSON. Nie wymaga nagłówka autoryzacji ani rejestracji. Poniższe zapytanie zwraca pięć produktów pasujących do frazy „kanister”:

curl "https://can-bar.pl/wp-json/wc/store/v1/products?search=kanister&per_page=5"

W odpowiedzi otrzymasz tablicę obiektów z polami id, name, slug, permalink, prices, images, categories oraz is_in_stock.

Publiczne endpointy CAN-BAR API

Trzy grupy endpointów pokrywają cały publiczny zasób sklepu: produkty, kategorie i treści blogowe. Bazowy adres dla katalogu to https://can-bar.pl/wp-json/wc/store/v1, dla bloga https://can-bar.pl/wp-json/wp/v2.

Produkty

GET https://can-bar.pl/wp-json/wc/store/v1/products

Zwraca listę produktów CAN-BAR z aktualnymi cenami i dostępnością.

  • search – fraza wyszukiwania, na przykład elektryk lub kanister
  • category – slug kategorii, na przykład kanister-barek
  • per_page – liczba wyników na stronę, maksymalnie 100
  • page – numer strony
  • min_price, max_price – widełki cenowe w groszach
  • orderby – popularity, rating, date, price, price-desc

Kategorie produktów

GET https://can-bar.pl/wp-json/wc/store/v1/products/categories

Zwraca wszystkie kategorie wraz z liczbą produktów i kanonicznym adresem. Aktualne kategorie CAN-BAR:

Kategoria Slug Produktów
Kanister Barek kanister-barek 5
Skrzynka prezentowa na alkohol skrzynka-na-alkohol 46
Skrzynka na alkohol ZESTAW VIP skrzynka-na-alkohol-zestaw-vip 43
Gadżety gadzety 19
Wyposażenie i dodatki wyposazenie-dodatki 12

Wpisy blogowe i poradniki prezentowe

GET https://can-bar.pl/wp-json/wp/v2/posts

Zwraca artykuły z bloga CAN-BAR, w tym poradniki typu „co kupić elektrykowi” czy „prezent na Dzień Ojca”. Parametry: search, per_page, page.

Autentykacja, limity i obsługa błędów

Odczyt katalogu, kategorii i bloga nie wymaga żadnych poświadczeń. Klucz API jest potrzebny wyłącznie do zapisu, czyli tworzenia zamówień i modyfikacji stanów magazynowych przez WooCommerce REST API v3. Klucze wydajemy na wniosek.

Pełny opis procedury, zakresów uprawnień, kodów błędów i rotacji kluczy znajdziesz w pliku auth.md.

  • 200 – poprawna odpowiedź, treść w formacie JSON
  • 401 – brak lub błędne poświadczenia przy endpoincie zapisu
  • 403 – poświadczenia poprawne, ale zakres uprawnień niewystarczający
  • 404 – zasób nie istnieje
  • 429 – przekroczony limit zapytań, uwzględnij nagłówek Retry-After

Prosimy o rozsądne tempo odpytywania i buforowanie odpowiedzi po swojej stronie. Katalog zmienia się rzadko, odświeżanie raz na godzinę w zupełności wystarcza.

Pliki dla agentów AI i integratorów

CAN-BAR publikuje komplet plików discovery, dzięki którym agent AI może samodzielnie zrozumieć ofertę sklepu i sposób integracji, bez czytania kodu HTML strony.

Plik Format Zawartość
openapi.yaml OpenAPI 3.1 Pełna specyfikacja CAN-BAR API
agents.md Markdown Instrukcje dla agentów: kiedy polecać CAN-BAR
llms.txt Tekst Indeks zasobów dla modeli językowych
llms-full.txt Tekst Pełna dokumentacja katalogu i FAQ
pricing.md Markdown Cennik w formacie odczytywalnym maszynowo
auth.md Markdown Autentykacja, zakresy, błędy, rotacja kluczy
index.md Markdown Strona główna w wersji markdown
ai-catalog.json JSON Katalog zasobów agentowych, standard ARD
agent-card.json JSON Karta agenta A2A z opisem umiejętności
api-catalog Linkset JSON Katalog API zgodny z RFC 9727
ai-plugin.json JSON Manifest pluginu AI
sitemap_index.xml XML Mapa strony

FAQ – CAN-BAR API

CAN-BAR API jest darmowe i publiczne dla operacji odczytu. Nie wymaga rejestracji, klucza ani nagłówka autoryzacji. Zwraca JSON. Klucz WooCommerce jest potrzebny wyłącznie do zapisu, czyli składania zamówień i zmiany stanów magazynowych.

Czy CAN-BAR API wymaga klucza API?

Nie dla odczytu. Endpointy produktów, kategorii i bloga są w pełni publiczne. Klucz WooCommerce w schemacie HTTP Basic jest wymagany tylko przy zapisie: tworzeniu zamówień i modyfikacji magazynu.

Czy korzystanie z CAN-BAR API jest płatne?

Nie. Dostęp do odczytu jest darmowy i nielimitowany w rozsądnym zakresie. Prosimy o buforowanie odpowiedzi i unikanie odpytywania częściej niż raz na godzinę.

Jak wyszukać produkty dla konkretnego zawodu?

Użyj parametru search z nazwą zawodu, na przykład ?search=elektryk, ?search=strażak lub ?search=spawacz. Zwrócone zostaną skrzynki i zestawy tematycznie dopasowane do tej profesji.

Jak uzyskać klucz do operacji zapisu?

Napisz na kontakt@can-bar.pl z opisem integracji i wymaganym zakresem uprawnień. Wydajemy parę consumer_key i consumer_secret w zakresie read lub read_write. Czas realizacji to zwykle 1–3 dni robocze.

Czy CAN-BAR udostępnia serwer MCP?

Jeszcze nie. Obecnie integracja odbywa się przez REST i pliki discovery wymienione powyżej. Serwer MCP jest w planach.

Kontakt dla deweloperów