Admin API i webservice w PrestaShop 9 - jak działa API do integracji z innymi systemami

Admin API w PrestaShop 9 - jak działa nowe API?

Admin API to API do zarządzania sklepem, które według dokumentacji dla deweloperów jest w PrestaShop 9 włączone domyślnie. Zamiast stałego klucza zewnętrzny system używa danych klienta API, czyli identyfikatora i sekretu, i za ich pomocą pobiera krótkotrwały token dostępu. Każde zapytanie wysyła z tym tokenem w nagłówku autoryzacji typu Bearer. Token wygasa po czasie ustawionym dla klienta, więc integracja co jakiś czas pobiera nowy.

Jak utworzyć klienta Admin API?

Klienta tworzysz w parametrach zaawansowanych, w sekcji Admin API (Advanced Parameters > Admin API), przyciskiem dodania klienta (Add new API Client). Formularz ma pola: nazwa klienta (Client name), identyfikator klienta (Client ID), opis (Description), czas życia tokenu w sekundach (Lifetime), włączenie (Enabled) i zakresy uprawnień (Scopes). Zapisujesz go przyciskiem generowania sekretu (Generate client secret and save). Dokumentacja ostrzega, że sekret widać tylko raz - jeśli go nie zapiszesz, trzeba wygenerować nowy.

Przepływ od utworzenia klienta do pierwszego zapytania wygląda tak:

[#chart:prs18b]

Token pobierasz zapytaniem POST na adres /admin-api/access_token, w którym przekazujesz identyfikator klienta, sekret, typ uwierzytelnienia client_credentials i listę zakresów. W przykładzie z dokumentacji token jest ważny 3600 sekund, czyli godzinę. Admin API domyślnie wymaga połączenia HTTPS. W sekcji konfiguracji Admin API jest opcja wymuszania zabezpieczeń w trybie debugowania (Force security in debug mode), która pozwala wyłączyć ten wymóg na środowisku deweloperskim. Na sklepie produkcyjnym zostaw HTTPS bez wyjątków.

Zakresy uprawnień i dokumentacja punktów dostępu

Zakresy (scopes) określają, co klient może zrobić. Dokumentacja podaje przykłady takie jak product_read, product_write, customer_group_read, customer_group_write, cart_rule_write, module_read czy hook_read. Bez odpowiedniego zakresu punkt dostępu odmówi odpowiedzi, a moduły mogą dodawać własne zakresy. Pełną listę dostępnych punktów dostępu, metod i parametrów sklep generuje automatycznie pod adresem /admin-api/docs.html, a w formacie OpenAPI pod /admin-api/docs.json. To najlepsze źródło do sprawdzenia, czy Twoja wersja sklepu obsługuje dane, których potrzebuje integracja.

Punkty dostępu Admin API dostarcza moduł ps_apiresources. Według bloga deweloperskiego PrestaShop kolejne punkty dostępu trafiają do tego modułu, dzięki czemu mogą działać zarówno w wersji 9.0, jak i 9.1. Wydanie 9.1 z marca 2026 r. wymienia m.in. usprawnienia punktów dostępu dla kombinacji. Lista wciąż rośnie i nie obejmuje jeszcze wszystkich obszarów sklepu, dlatego przed projektem integracji sprawdź dokumentację na własnym sklepie, a nie tylko zapowiedzi.

Typowe problemy przy pierwszym połączeniu z Admin API

Pierwsze zapytania do Admin API najczęściej kończą się błędem z kilku powtarzalnych powodów. Klient API jest zapisany, ale wyłączony - dokumentacja zaznacza, że wyłączony klient nie może korzystać z API. Token został pobrany bez zakresu potrzebnego do danego punktu dostępu, więc odpowiedź odmawia dostępu, choć sam token jest ważny. Integracja łączy się przez zwykłe HTTP, a sklep wymaga HTTPS. Token wygasł, bo integracja pobrała go raz i używa go dłużej, niż wynosi czas życia ustawiony w kliencie. Jeśli problemy się powtarzają, dokumentacja radzi sprawdzić w konfiguracji Admin API, czy API jest włączone.

Webservice czy Admin API - co wybrać do integracji w PrestaShop 9?

W praktyce wybór rzadko jest zero-jedynkowy. Gotowe integracje, np. z integratorami sprzedaży czy systemami ERP, często korzystają z webservice, bo działa on w PrestaShop od lat i ma szeroki zakres zasobów. Admin API warto rozważyć przy nowych integracjach budowanych od zera, zwłaszcza gdy potrzebne dane są już dostępne w punktach dostępu, a zależy Ci na tokenach z ograniczonym czasem życia i precyzyjnych zakresach. Typowe zastosowania zebraliśmy w zestawieniu:

[#chart:prs18c]

Jeśli Twoja integracja działa dziś na webservice, nie ma powodu przepisywać jej tylko dlatego, że pojawiło się Admin API. Rozsądniej zaplanować przejście etapami: nowe funkcje budować na Admin API tam, gdzie punkty dostępu już istnieją, a istniejące przepływy zostawić na webservice do czasu, aż nowe API obejmie potrzebne dane. Przy sklepach w trybie wielu sklepów sprawdź też w dokumentacji Admin API rozdział o multistore, zanim zaprojektujesz zapis danych dla kilku sklepów naraz.

Czego nie da żadne z API w rdzeniu?

Rdzeń PrestaShop nie wysyła webhooków, czyli powiadomień o zdarzeniach, np. o nowym zamówieniu. Integracja musi więc cyklicznie pytać sklep o zmiany albo w sklepie trzeba zainstalować moduł, który przy wybranych zdarzeniach powiadomi zewnętrzny system. Jak działają webhooki i jak je bezpiecznie wdrożyć, piszemy w tekście Webhooki w e-commerce - do czego służą i jak je bezpiecznie wdrożyć. Drugie ograniczenie to wydajność: masowa aktualizacja tysięcy produktów przez API to tysiące zapytań do serwera sklepu, więc zmiany warto wysyłać partiami i tylko dla rekordów, które faktycznie się zmieniły.

[#uwaga] Klucz webservice i sekret klienta Admin API dają dostęp do danych klientów i zamówień. Nie wysyłaj ich e-mailem ani w komunikatorze, nie zapisuj w kodzie i nie nadawaj pełnych uprawnień „na zapas”. Każda integracja powinna mieć własny klucz lub klienta z opisem, a nieużywane dostępy wyłączaj od razu po zakończeniu współpracy.

Jak zaplanować integrację przez API w PrestaShop 9?

Zanim programista napisze pierwszą linijkę kodu, warto odpowiedzieć na kilka pytań. Oszczędzają one najwięcej poprawek po wdrożeniu:

1. Jakie dane mają płynąć i w którą stronę: zamówienia do ERP, stany i ceny do sklepu, statusy z magazynu?

2. Który system jest źródłem prawdy dla produktów, stanów i cen?

3. Czy potrzebne zasoby są dostępne w Admin API Twojej wersji sklepu, czy trzeba użyć webservice?

4. Jak często integracja ma sprawdzać zmiany i ile zapytań wytrzyma serwer?

5. Kto przechowuje klucze i sekrety oraz kto dostaje powiadomienie, gdy integracja przestanie działać?

Przy integracjach produktów pamiętaj o danych z formularza produktu: indeksach, kodach GTIN, kombinacjach i cenach szczególnych. Jakie pola ma produkt w PrestaShop 9 i za co odpowiadają, opisujemy we wpisie Karta produktu w PrestaShop 9 - nowy formularz produktu i pola, które warto wypełnić. Po każdej aktualizacji sklepu lub modułu ps_apiresources przetestuj integrację na kopii sklepu, zanim wdrożysz zmianę na produkcji.

[#checklista] Integracja przez API w PrestaShop 9: SSL działa, wybrane API dla każdego zakresu danych, osobny klucz lub klient API na integrację, minimalne uprawnienia lub zakresy, opis przy każdym dostępie, sekrety w menedżerze haseł, harmonogram odpytywania ustalony, aktualizacje partiami, monitoring błędów, test na kopii sklepu po każdej aktualizacji.

Jak Vinson pomaga z integracjami API w PrestaShop

W Vinson wdrażamy, rozwijamy i utrzymujemy sklepy na PrestaShop. Przy integracjach przez API zajmujemy się zarówno konfiguracją, jak i programowaniem:

• dobieramy webservice lub Admin API do zakresu danych i systemu, który łączymy,

• konfigurujemy klucze, klientów API i uprawnienia według zasady minimum,

• budujemy integracje z ERP, magazynem, marketplace'ami i Base - jesteśmy certyfikowanym partnerem Base,

• testujemy integracje po aktualizacjach PrestaShop i modułów.

Szczegóły współpracy znajdziesz na stronie sklep na PrestaShop z Vinson.

Najczęściej zadawane pytania

Czy PrestaShop ma API?

Tak. PrestaShop ma wbudowany webservice, który włączasz w parametrach zaawansowanych i udostępniasz kluczem z uprawnieniami. Od wersji 9.0 jest też Admin API oparte na API Platform, z uwierzytelnianiem OAuth i tokenami o ograniczonym czasie życia.

Czym różni się Admin API od webservice w PrestaShop 9?

Webservice używa stałego klucza i daje dostęp do szerokiego zakresu zasobów opartych na obiektach sklepu. Admin API używa klientów z sekretem, tokenów Bearer i zakresów uprawnień, a jego punkty dostępu dostarcza moduł ps_apiresources, którego zakres rośnie z każdym wydaniem.

Jak włączyć webservice w PrestaShop?

Wejdź w parametry zaawansowane, sekcję webservice, i włącz opcję webservice sklepu. Następnie dodaj klucz, wpisz opis, nadaj uprawnienia tylko do potrzebnych zasobów i zapisz. Sklep powinien działać na połączeniu SSL.

Czy webservice w PrestaShop 9 jest przestarzały?

Dokumentacja dla deweloperów PrestaShop 9 nie oznacza webservice jako przestarzałego. Oba API działają równolegle, a wiele gotowych integracji nadal korzysta z webservice. Przy nowych projektach sprawdź, czy potrzebne dane są już dostępne w Admin API.

Czy PrestaShop wysyła webhooki?

Nie, rdzeń PrestaShop nie wysyła webhooków. Integracja musi cyklicznie pytać sklep o zmiany przez API albo trzeba zainstalować moduł, który powiadamia zewnętrzny system przy wybranych zdarzeniach, np. przy nowym zamówieniu.

Dobrze zaprojektowana integracja przez API sprawia, że PrestaShop wymienia dane z ERP, magazynem i marketplace'ami bez ręcznego przepisywania. Jeśli planujesz nową integrację albo chcesz uporządkować dostępy do API w swoim sklepie, sprawdź wdrożenie sklepu na PrestaShop z Vinson - zaczniemy od listy systemów i danych, które mają się wymieniać.