PrestaShop API: jak skonfigurować dostęp i bezpiecznie zintegrować sklep

PrestaShop Webservice API udostępnia zewnętrznym systemom wybrane dane sklepu i operacje CRUD: tworzenie, odczyt, aktualizowanie oraz usuwanie rekordów. To interfejs komunikacji, a nie gotowa integracja z ERP. Zakres faktycznych działań wynika z uprawnień klucza, zasobów dostępnych w instalacji oraz logiki systemu po drugiej stronie.

Typowy przepływ obejmuje odczyt zamówień przez ERP, aktualizację stanów magazynowych albo przesyłanie danych katalogowych. Webservice działa na zasobach takich jak products, combinations, orders, customers, categories i stock_availables, ale konkretna instalacja może udostępniać inny zestaw. Moduł może dodać własny zasób lub logikę, której standardowy interfejs nie wykonuje.

Jeśli integracja wymaga złożonych przekształceń, walidacji lub koordynacji kilku systemów, samo przyznanie dostępu do API nie wystarczy. Trzeba zaprojektować przepływ i obsługę procesu poza samym endpointem.

Przed utworzeniem klucza przygotuj listę danych, które integracja ma odczytywać lub zmieniać. Dzięki temu przyznasz konkretne prawa, a nie szeroki dostęp, który później trudno kontrolować.

• Ustal wersję PrestaShop, PHP oraz moduły zmieniające produkty, zamówienia lub stany.
• Zapisz dokładny adres sklepu i lokalizację instalacji. Standardowy endpoint znajduje się pod /api/ w katalogu instalacji.
• Potwierdź, że sklep działa przez HTTPS, a certyfikat jest poprawny.
• Wypisz zasoby oraz operacje wymagane przez integrację, rozdzielając odczyt od zapisu.
• Przygotuj kopię lub środowisko testowe, na którym można bezpiecznie sprawdzić żądania modyfikujące dane.

Dokumentację dobieraj do wersji sklepu. Dla PrestaShop 9 dostępna jest bieżąca dokumentacja Webservice, a dokumentacja PrestaShop 8 jest oznaczona jako dotycząca starszej wersji. Wersja sklepu, moduły i konfiguracja serwera mogą wpływać na to, jakie dane oraz operacje będą dostępne.

W Back Office otwórz Zaawansowane > Usługi sieciowe, włącz opcję Webservice PrestaShop i zapisz ustawienie. Nazwa menu może zależeć od tłumaczenia panelu, ale dokumentacja opisuje stronę Webservice pod menu Advanced Parameters.

Wybierz dodanie nowego klucza, wygeneruj losową wartość i wpisz opis wskazujący system oraz środowisko, na przykład ERP produkcja albo magazyn test. W tabeli praw zaznacz operacje wyłącznie przy zasobach potrzebnych temu połączeniu. Przykładowo integracja pobierająca zamówienia może wymagać odczytu orders, order_details i order_histories, a aktualizacja katalogu może potrzebować odczytu lub zapisu products i combinations. Synchronizacja stanów może dotyczyć stock_availables; sprawdź, czy ta nazwa i potrzebne operacje występują w konkretnej instalacji.

Dostępne zasoby i ich pola zależą od wersji PrestaShop oraz zainstalowanych modułów. Nie przyznawaj automatycznie pełnego dostępu. Zapisz klucz w menedżerze sekretów albo bezpiecznej konfiguracji integracji, a do logów zapisuj wyłącznie identyfikator klucza lub nazwę połączenia.

Test zacznij od odczytu listy zasobów, a zapis wykonuj dopiero na kopii sklepu lub kontrolnym rekordzie. W Postmanie utwórz żądanie GET do https://twoj-sklep.pl/api/; jeśli instalacja znajduje się w podkatalogu, uwzględnij go przed /api/.

W ustawieniach autoryzacji wybierz Basic Auth. Jako nazwę użytkownika podaj klucz Webservice, a pole hasła pozostaw puste. Nie umieszczaj klucza w adresie URL, ponieważ może zostać zapisany w historii narzędzia lub logach serwera. PrestaShop opisuje test dostępu przez endpoint /api/ oraz klienta API.

Kod HTTP sam nie potwierdza jednej przyczyny. Dokumentacja PrestaShop opisuje między innymi ponawianie promptu autoryzacji, gdy klucz nie ma uprawnień do żądanego zasobu. Dlatego przy 403 odczytaj komunikat odpowiedzi i sprawdź prawa przypisane do konkretnego zasobu oraz operacji. Przy problemach z 401 sprawdź również, czy serwer przekazuje nagłówek Authorization do aplikacji.

Zakres praw wynika z konkretnego przepływu danych. Poniższa macierz jest punktem do weryfikacji w panelu, a nie gwarancją, że każda instalacja zawiera identyczne zasoby i pola.

Nazwy w tabeli odpowiadają zasobom opisanym w dokumentacji Webservice PrestaShop 9. Lista widoczna w panelu danej instalacji może różnić się przez wersję sklepu i moduły. Przed dodaniem prawa sprawdź, czy zakres operacji obejmuje rzeczywiście potrzebną metodę HTTP. Nie przyznawaj zapisu do klientów lub zamówień, jeśli system ma je wyłącznie pobierać.

Każde pole powinno mieć jedno źródło prawdy i jednoznaczny klucz dopasowania. Ustal te dwie rzeczy przed uruchomieniem automatycznej wymiany, bo identyfikator produktu PrestaShop nie zawsze jest tym samym co SKU, EAN lub numer z ERP.

Dla produktów zapisz mapowanie identyfikatorów, a dla wariantów potwierdź, że integracja dopasowuje konkretną kombinację, a nie wyłącznie produkt nadrzędny. Następnie przypisz właściciela danych na poziomie pól. Przykładowo ERP może zarządzać ceną i stanem, a PrestaShop opisem i zdjęciami. Statusy zamówień wymagają osobnej mapy, ponieważ systemy mogą używać innych nazw i momentów zmiany statusu.

Synchronizację projektuj tak, by ponowienie żądania po przerwaniu nie tworzyło drugiego produktu ani zamówienia. Zapisuj identyfikator rekordu, czas, endpoint, metodę i wynik operacji bez klucza API oraz zbędnych danych osobowych. Dla dużych lub długotrwałych zadań użyj kolejki, która pozwala ponowić nieudane rekordy bez blokowania całego przebiegu.

Klucz API traktuj jak hasło o zakresie ograniczonym do wybranych danych. Używaj HTTPS, oddzielnych kluczy dla różnych integracji i środowisk oraz przechowuj je w zabezpieczonej konfiguracji, do której dostęp mają tylko osoby utrzymujące połączenie.

Rotację zaplanuj jako kontrolowaną zmianę: wygeneruj nowy klucz, ustaw go w integracji, wykonaj test odczytu i wymaganych zapisów, a dopiero potem wyłącz stary. Po podejrzeniu ujawnienia wyłącz klucz w panelu i sprawdź logi dostępu. Klucza nie zapisuj w kodzie źródłowym, logach, zgłoszeniach serwisowych ani adresie URL.

Na środowisku testowym sprawdź także, czy kopia nie wysyła prawdziwych powiadomień lub danych do systemów produkcyjnych. Log powinien pozwolić zidentyfikować nieudany rekord, ale nie może zawierać sekretów ani pełnych danych klienta.

Wolne odpowiedzi diagnozuj przez pomiar czasu żądania, rozmiaru odpowiedzi i liczby rekordów. Jeśli integracja za każdym razem pobiera cały katalog, opóźnienie może wynikać z zakresu odczytu, dodatkowej logiki modułów lub konfiguracji hostingu.

Dokumentacja Webservice opisuje parametry list, w tym display i filter. Używaj ich do ograniczania pól i filtrowania rekordów, jeśli są obsługiwane przez dany zasób i wersję. Pobieraj dane porcjami, a w integracji zapisuj czas ostatniego poprawnego przebiegu, żeby nie przetwarzać ponownie całej historii bez potrzeby.

Gdy odpowiedź jest duża lub praca trwa dłużej niż pojedyncze żądanie, kolejka pozwala rozdzielić synchronizację na mniejsze zadania. Jeśli czasy nadal rosną, porównaj logi aplikacji i serwera, limity czasu PHP, odpowiedzi dla pojedynczego zasobu oraz wyniki na kopii bez dodatkowych modułów.

Natywny Webservice wystarczy, jeśli dostępne zasoby i standardowe operacje obejmują wymagane dane oraz proces. Moduł lub integracja dedykowana są uzasadnione, gdy trzeba dodać własny zasób, przekształcić dane albo obsłużyć reguły biznesowe, których API nie wykonuje.

Przed wdrożeniem zapisz zakres synchronizacji, odpowiedzialność za błędy i testy odbiorcze. Jeśli sklep ma wymieniać dane z systemem sprzedażowym lub magazynowym, integracja sklepu z ERP pozwala zaplanować mapowanie i obsługę przepływu. Przygotowanie samego sklepu opisujemy w poradniku konfiguracji PrestaShop.

• WooCommerce API: jak połączyć sklep z innymi systemami
• Magento API w praktyce: endpointy, integracje i bezpieczeństwo
• PrestaShop i PHP 8.0: jak sprawdzić zgodność oraz bezpiecznie zmienić wersję
• Jak wyłączyć sklep PrestaShop i bezpiecznie włączyć tryb konserwacji