Shopware oferuje dwa interfejsy REST, Store API i Admin API, ale nie ma oficjalnego API GraphQL. Pokazujemy uwierzytelnianie i przykładowe zapytania dla obu oraz oceniamy, co dają projekty GraphQL, takie jak SwagGraphQL.
REST (Representational State Transfer) to styl architektury dla aplikacji sieciowych. Z interfejsami REST API komunikuje się przez HTTP, a typowe operacje realizują metody GET (odczyt), POST (tworzenie), PATCH lub PUT (zmiana) oraz DELETE (usuwanie). Shopware 6 udostępnia dwa interfejsy REST:
Oba interfejsy wymieniają dane w formacie JSON i zwracają wynik za pomocą kodów statusu HTTP, np. 200 przy powodzeniu lub 401 przy braku uprawnień. Poniższe sekcje pokazują uwierzytelnianie i przykładowe zapytania. Podstawowe informacje o platformie znajdą Państwo na naszej stronie poświęconej tworzeniu sklepów w Shopware.
Store API to dostęp do Storefront w Shopware. Oto jak się autoryzować i wysłać pierwsze zapytania.
Store API wymaga klucza sw-access-key, przypisanego do kanału sprzedaży:
https://twoj-sklep.pl/admin.Shopware udostępnia interfejs Swagger do testowania Store API:
https://twoj-sklep.pl/store-api/_info/swagger.html.sw-access-key i potwierdzić.Następnie wszystkie endpointy można testować bezpośrednio w przeglądarce.
Listę produktów zwraca zapytanie POST do /store-api/product. Store API przyjmuje w treści zapytania kryteria wyszukiwania, takie jak limit, filtry i sortowanie. Z użyciem cURL:
curl -X POST https://twoj-sklep.pl/store-api/product \
-H "sw-access-key: TWOJ_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'
Odpowiedź to JSON z tablicą elements, która zawiera produkty z nazwami, cenami i identyfikatorami:
{
"elements": [
{
"id": "0190d2e8f2b47c6f9d1a0c5e8b3f1a2b",
"name": "Produkt przykładowy",
"calculatedPrice": { "totalPrice": 19.99 },
"stock": 100
}
],
"total": 1
}
Sklepy headless działają w całości na tych interfejsach. Wybór między REST a GraphQL jest więc decyzją architektoniczną: REST jest dojrzały i wspierany przez oficjalne narzędzia Shopware, GraphQL umożliwia bardziej elastyczne pobieranie danych w złożonych frontendach, ale w Shopware nie ma oficjalnego statusu (więcej poniżej).
Admin API służy do integracji zaplecza i daje dostęp do danych podstawowych Shopware. Korzysta z OAuth 2.0.
Za pomocą danych dostępowych integracji token pobiera się zapytaniem POST /api/oauth/token:
curl -X POST https://twoj-sklep.pl/api/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "ID_KLUCZA_DOSTEPU",
"client_secret": "KLUCZ_BEZPIECZENSTWA"
}'
Odpowiedź zawiera token ważny przez dziesięć minut:
{
"token_type": "Bearer",
"expires_in": 600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
Z tokenem można wywoływać Admin API. Listę produktów zwraca GET /api/product:
curl -X GET https://twoj-sklep.pl/api/product \
-H "Authorization: Bearer TWOJ_ACCESS_TOKEN" \
-H "Content-Type: application/json"
Stan magazynowy zmienia się zapytaniem PATCH do /api/product/{id-produktu}:
curl -X PATCH https://twoj-sklep.pl/api/product/0190d2e8f2b47c6f9d1a0c5e8b3f1a2b \
-H "Authorization: Bearer TWOJ_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "stock": 150 }'
Do zmian masowych Admin API oferuje endpoint synchronizacji POST /api/_action/sync, który zapisuje wiele rekordów w jednym wywołaniu. Przydaje się to np. przy regularnym imporcie stanów magazynowych z polskiego systemu ERP lub WMS. A jeśli chcą Państwo otrzymywać informacje o zmianach zamiast je odpytywać, polecamy nasz artykuł o webhookach w Shopware 6.
GraphQL to język zapytań, w którym klient określa dokładnie, jakich danych potrzebuje. Pozwala to uniknąć pobierania nadmiarowych danych (over-fetching) i bywa wydajniejsze niż REST. Zamiast wielu endpointów jest jeden, zwykle /graphql. Shopware nie oferuje jednak oficjalnego API GraphQL. GraphQL można dodać wyłącznie za pomocą projektów społecznościowych, takich jak SwagGraphQL.
SwagGraphQL to proof of concept od shopwareLabs, który nakłada API GraphQL na podstawowe API Shopware. Bazuje na bibliotece webonyx/graphql-php i jest osadzony w Shopware 6 jako wtyczka. Projekt nie jest już rozwijany, powstał dla wczesnych wersji Shopware 6 i bez gruntownych modyfikacji nie powinien być używany produkcyjnie.
Do testów w środowisku deweloperskim:
# Sklonowanie repozytorium do katalogu wtyczek
git clone https://github.com/shopwareLabs/SwagGraphQL.git custom/plugins/SwagGraphQL
# Instalacja zależności wtyczki
cd custom/plugins/SwagGraphQL && composer install && cd -
# Rejestracja i aktywacja wtyczki
bin/console plugin:refresh
bin/console plugin:install --activate SwagGraphQL
bin/console cache:clear
Po instalacji endpoint jest dostępny pod adresem https://twoj-sklep.pl/graphql/query i można się z nim komunikować za pomocą narzędzi takich jak GraphiQL. Zapytanie o produkty wygląda następująco:
query {
products {
id
name
price
}
}
Kto potrzebuje GraphQL we frontendzie, w praktyce buduje własną warstwę: BFF (Backend for Frontend) w Node.js lub PHP, który udostępnia GraphQL na zewnątrz, a wewnętrznie wywołuje Store API i Admin API. Platformy middleware, takie jak Alumio, łączą Shopware z systemami opartymi na GraphQL, ale nie zastępują natywnego API GraphQL w rdzeniu Shopware. Do prostych automatyzacji między systemami często wystarczy również n8n.
sw-access-key, klucz jest błędny lub należy do innego kanału sprzedaży./store-api/product.includes i associations), stosować paginację wyników i cache odpowiedzi.Dzięki Store API i Admin API Shopware w pełni obsługuje przez REST podłączanie własnych frontendów i systemów zewnętrznych. Oficjalnego API GraphQL nie ma, a projekty społecznościowe, takie jak SwagGraphQL, nadają się wyłącznie do eksperymentów. Kto potrzebuje GraphQL we frontendzie, stawia własną warstwę przed interfejsami REST. Prawidłowo skonfigurowane i używane zgodnie z opisanymi zasadami API Shopware stanowią podstawę frontendów headless, synchronizacji z CRM i automatyzacji, także w sklepach w Polsce łączonych z lokalnymi systemami ERP, Allegro czy przewoźnikami. Jeśli potrzebują Państwo do tego wtyczki lub aplikacji, wspieramy Państwa w zakresie tworzenia wtyczek Shopware; pierwszy przegląd Państwa sklepu zapewni nasza analiza sklepu.