API administracyjne PrestaShop 9: praktyczny poradnik dla programistów

Nowe API administracyjne PrestaShop 9 to jedna z najważniejszych zmian architektonicznych w generacji PrestaShop 9.

Zaprojektowano je, aby ulepszyć starsze API Webservice dzięki nowocześniejszemu modelowi bezpieczeństwa, operacjom biznesowym i architekturze rozszerzanej przez moduły.

Nowe API bazuje na:

• API Platform 3;
• OAuth2 uwierzytelnianiu i autoryzacji;
• poleceniach i zapytaniach CQRS;
• zakresach uprawnień;
• dokumentacji OpenAPI/Swagger;
• zasobach API definiowanych przez moduły.

Jest więc szczególnie interesujące dla programistów tworzących:

• integracje ERP;
• integracje PIM;
• synchronizację stanów magazynowych;
• platformy dostawców;
• połączenia SaaS;
• systemy zarządzania zamówieniami;
• usługi raportowania;
• narzędzia automatyzacji.

Ten poradnik wyjaśnia architekturę, działanie uwierzytelniania, tworzenie klientów i możliwości rozbudowy API przez twórców modułów.

Uwaga dotycząca wersji: Ten artykuł zweryfikowano 22 września 2026 r. na podstawie aktualnej dokumentacji PrestaShop 9 dla programistów. API administracyjne stale się rozwija, dlatego zawsze sprawdzaj specyfikację OpenAPI wygenerowaną dla dokładnej wersji integrowanego sklepu.

Dlaczego PrestaShop stworzył nowe API administracyjne

Starsze API Webservice PrestaShop jest ściśle związane z przestarzałymi operacjami CRUD opartymi na ObjectModel.

Projekt PrestaShop wskazuje kilka ograniczeń tego starszego podejścia:

• ograniczone zarządzanie uprawnieniami i bezpieczeństwem;
• podstawowe operacje CRUD;
• przestarzała architektura;
• trudniejsze utrzymanie;
• ścisłe powiązanie z ObjectModel.

Nowe API administracyjne ma inne cele.

Zaprojektowano je tak, aby było:

• bezpieczniejsze;
• łatwiejsze do audytowania;
• lepiej dostosowane do operacji biznesowych;
• bliższe nowoczesnym standardom;
• rozszerzalne przez moduły.

To ważne.

Nowoczesne API e-commerce nie powinno jedynie udostępniać rekordów bazy danych.

Powinno udostępniać operacje zrozumiałe dla biznesu.

API Platform 3 jako fundament HTTP/API

PrestaShop 9 używa API Platform 3 dla nowego API administracyjnego.

API Platform zapewnia infrastrukturę do obsługi:

• trasami;
• zasobów API;
• serializacji;
• walidacji;
• generowania OpenAPI;
• interfejsu Swagger UI;
• providerów danych;
• procesorów.

Następnie PrestaShop integruje z tym frameworkiem własną architekturę aplikacji.

Rezultat nie jest zwykłym CRUD-em API Platform.

Wbudowane punkty końcowe mogą wywoływać zapytania i polecenia CQRS PrestaShop.

CQRS: odczyt i zapis jako operacje biznesowe

PrestaShop korzysta z CQRS od czasu migracji do Symfony.

CQRS rozdziela operacje, które:

odczytaj dane

od operacji, które:

zmień stan

API administracyjne ponownie wykorzystuje te rozwiązania.

Zgodnie z oficjalną architekturą:

• operacja odczytu może uruchomić zapytanie CQRS;
• operacja listowania może użyć fabryki danych tabeli;
• operacja zapisu może wykonać polecenie CQRS.

Pomaga to utrzymać spójne zachowanie między panelem administracyjnym a API.

Dlaczego CQRS jest ważny

Wyobraź sobie dwa sposoby modyfikacji produktu.

Podejście z bezpośrednim dostępem do bazy danych

żądanie API
→ UPDATE ps_product ...

Może to ominąć:

• walidację;
• hooki;
• zasady domenowe;
• powiązane encje.

Podejście z poleceniem aplikacji

żądanie API
→ zasób API
→ polecenie CQRS
→ procedura obsługi aplikacji
→ reguły domeny

Drugi model zwykle łatwiej zachować w zgodności z resztą aplikacji.

Ułatwia też testowanie zachowania API.

API administracyjne jest domyślnie włączone

Aktualna oficjalna dokumentacja PrestaShop podaje, że API administracyjne jest dostępne od razu w PrestaShop 9.

Przed użyciem API przez zewnętrzną aplikację trzeba jednak skonfigurować klientów API i uprawnienia.

Ścieżka w panelu administracyjnym do zarządzania klientami:

Parametry zaawansowane
→ API administracyjne

Tam administratorzy mogą tworzyć klientów API i przydzielać im zakresy uprawnień.

Na produkcji wymagany jest HTTPS

API administracyjne PrestaShop wymaga bezpiecznego dostępu w środowisku produkcyjnym.

Tryb deweloperski może poluzować kontrolę HTTPS lokalnie, ale produkcja wymaga bezpiecznego połączenia HTTPS.

Nie twórz integracji zależnej od wyłączenia bezpieczeństwa transportu.

Dane dostępowe i tokeny API są poufne.

Nigdy nie należy ich przesyłać zwykłym HTTP w sieci produkcyjnej.

OAuth2 to model uwierzytelniania

API administracyjne używa OAuth2.

OAuth2 rozdziela kilka pojęć:

• klient;
• serwer zasobów;
• serwer autoryzacji;
• token dostępu;
• zakresy uprawnień.

W domyślnej konfiguracji PrestaShop:

Aplikacja zewnętrzna = klient
PrestaShop = serwer zasobów
PrestaShop = serwer autoryzacji

PrestaShop może też współpracować z zewnętrznym serwerem autoryzacji.

Client Credentials dla integracji serwer-serwer

Dla standardowych integracji między systemami dokumentacja PrestaShop zaleca przepływ OAuth2 Client Credentials .

Typowe przykłady:

• ERP → PrestaShop;
• PIM → PrestaShop;
• WMS → PrestaShop;
• Usługa SaaS → PrestaShop.

Przy każdym żądaniu API nie trzeba logować użytkownika.

Integracja otrzymuje:

client_id
client_secret

a następnie wymienia je na token dostępu.

Tworzenie klienta API w panelu administracyjnym

Przejdź do:

Parametry zaawansowane
→ API administracyjne
→ Dodaj nowego klienta API

Konfiguracja klienta obejmuje między innymi:

• nazwę klienta;
• identyfikator klienta;
• opis;
• czas ważności;
• stan włączenia;
• zakresy uprawnień.

Użyj opisowej nazwy klienta.

Dobrze:

Synchronizacja stanów magazynu

Źle:

api2

Nawet po wielu miesiącach administrator powinien od razu wiedzieć, do czego służą te dane dostępowe.

Zapisz sekret klienta od razu

Dokumentacja API administracyjnego PrestaShop ostrzega, że wygenerowany sekret klienta wyświetlany jest tylko raz.

Zapisz go bezpiecznie podczas tworzenia klienta.

Nie umieszczaj go w:

• repozytorium kodu;
• publicznej konfiguracji;
• systemach śledzenia zgłoszeń;
• zrzutach ekranu;
• logach.

Jeśli to możliwe, używaj sekretów środowiskowych lub dedykowanego menedżera sekretów.

Tworzenie klientów API z CLI

PrestaShop udostępnia też polecenie konsoli:

bin/console prestashop:api-client create CLIENT_ID

Na przykład:

bin/console prestashop:api-client create warehouse-sync

Dodatkowe opcje pozwalają skonfigurować:

• nazwy;
• opisu;
• zakresów uprawnień;
• czasu życia tokenu.

Dokumentacja udostępnia również opcję --all-scopes , ale ostrzega przed przyznawaniem wszystkich zakresów rzeczywistym integracjom produkcyjnym.

Stosuj zasadę najmniejszych uprawnień

Każdy klient API powinien mieć tylko potrzebne zakresy uprawnień.

Usługa synchronizacji stanów może potrzebować dostępu do produktów lub magazynu.

Nie powinien automatycznie otrzymywać uprawnień do:

• zarządzania niepowiązanymi modułami;
• edytowania wszystkich klientów API;
• dostępu do niepowiązanych operacji na klientach.

W razie kradzieży tokenu ograniczone zakresy zmniejszają potencjalne szkody.

Jedna integracja, jeden klient

Unikaj używania tego samego klienta API dla:

• ERP;
• CRM;
• automatyzacji marketingu;
• magazynu;
• raportowania.

Przydziel oddzielnego klienta każdej usłudze.

Korzyści:

• oddzielne dane dostępowe;
• oddzielne zakresy uprawnień;
• możliwość osobnego unieważnienia;
• lepsza możliwość audytu.

Jeśli platforma marketingowa zostanie przejęta, możesz unieważnić tylko jej klienta.

Uzyskiwanie tokenu dostępu

Przy wewnętrznym serwerze autoryzacji PrestaShop punkt końcowy tokenów to:

/admin-api/access_token

Oficjalna dokumentacja używa żądania podobnego do:

curl --location 'https://shop.example.com/admin-api/access_token' \
  --form 'grant_type="client_credentials"' \
  --form 'client_id="warehouse-sync"' \
  --form 'client_secret="YOUR_CLIENT_SECRET"' \
  --form 'scope[]="product_read"' \
  --form 'scope[]="product_write"'

Serwer autoryzacji zwraca token dostępu.

Następnie aplikacja używa tego tokenu w żądaniach API.

Wysyłanie tokenu Bearer

Uwierzytelnione żądania używają:

Authorization: Bearer YOUR_ACCESS_TOKEN

Na przykład:

curl --location \
  'https://shop.example.com/admin-api/api-client/infos' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Dostępne punkty końcowe zależą od zainstalowanej wersji PrestaShop i włączonych modułów.

Nie zapisuj na sztywno założeń z artykułu blogowego.

Korzystaj z dokumentacji API wygenerowanej przez sklep docelowy.

Zakresy uprawnień są częścią żądania tokenu

Ważnym szczegółem OAuth jest to, że klient może mieć dostęp do wielu zakresów, ale token otrzymuje tylko żądane zakresy.

Na przykład:

klient zezwala na:
product_read
product_write
customer_group_read

Konkretny token może żądać tylko:

product_read

Taki token ma wówczas węższe uprawnienia.

To pomaga jeszcze bardziej ograniczyć uprawnienia.

Brak zakresu uprawnień powoduje błąd autoryzacji

Jeśli punkt końcowy wymaga zakresu, którego nie ma token, PrestaShop zwraca błąd autoryzacji.

Właśnie o takie zachowanie chodzi.

Integracja powinna zgłosić czytelny błąd, a nie po cichu wykonać operację bez uprawnień.

Obsługuj jawnie kody statusu HTTP w kliencie API.

Tokeny dostępu wygasają

Konfiguracja klienta API obejmuje czas ważności tokenu.

Aplikacje powinny uwzględniać wygaśnięcie tokenów dostępu.

Nie traktuj tokenu dostępu jako trwałych danych uwierzytelniających.

Solidny klient:

1. pobiera token;
2. bezpiecznie zapisuje go w pamięci podręcznej;
3. śledzi jego wygaśnięcie;
4. w razie potrzeby pobiera nowy.

Nie żądaj nowego tokenu przed każdym wywołaniem API, chyba że architektura naprawdę tego wymaga.

PrestaShop zawsze jest serwerem zasobów

Dokumentacja PrestaShop wprowadza przydatne rozróżnienie.

Sklep zawsze pełni rolę serwera zasobów udostępniającego chronione zasoby.

Serwer autoryzacji może być:

• sam PrestaShop;
• zewnętrzny serwer autoryzacji.

Pozwala to większym organizacjom w razie potrzeby zintegrować centralną infrastrukturę tożsamości.

Zewnętrzne serwery autoryzacji

Architektura PrestaShop obsługuje zewnętrznych dostawców autoryzacji.

Może to być przydatne w większych środowiskach korzystających już ze scentralizowanej infrastruktury OAuth.

Oficjalna dokumentacja przedstawia założenia integracji i przykład zewnętrznego serwera autoryzacji.

Jest to bardziej złożone niż domyślny przepływ wewnętrzny.

Stosuj go tylko wtedy, gdy infrastruktura faktycznie wymaga centralnej autoryzacji.

Dokumentacja Swagger

Jedną z głównych zalet API Platform jest automatyczna dokumentacja.

PrestaShop udostępnia Swagger/OpenAPI, umożliwiając programistom poznanie API.

W środowisku deweloperskim panel administracyjny udostępnia link do Swagger.

Jest to bardzo przydatne, ponieważ strona Swagger odzwierciedla API faktycznie udostępniane przez instalację.

JSON OpenAPI

Dokumentacja API administracyjnego może być dostępna w formacie OpenAPI.

Oficjalna dokumentacja wskazuje:

/admin-api/docs.json

Tę specyfikację można zaimportować do narzędzi takich jak:

• Postman;
• klienty zgodne z Insomnia;
• generatory kodu OpenAPI.

To znacznie bezpieczniejsze niż ręczne utrzymywanie listy struktur punktów końcowych w innym projekcie.

Generowanie dokumentacji API z CLI

PrestaShop udostępnia również:

php bin/console prestashop:generate:apidoc

Wynik można przekierować:

php bin/console prestashop:generate:apidoc > api-spec.json

Zastosowania:

• dokumentacja API;
• generowanie klientów;
• porównywanie wersji;
• testy kontraktowe;
• CI.

Wersjonuj specyfikację API

W przypadku dużej integracji przechowuj wygenerowane specyfikacje OpenAPI obsługiwanych wersji PrestaShop.

Następnie porównuj wydania.

Na przykład:

prestashop-9.0-api.json
prestashop-9.1-api.json

Różnica może wykazać:

• nowe punkty końcowe;
• zmienione pola;
• nowe wymagane wartości.

Dzięki temu można zawczasu zadbać o kompatybilność.

Moduły mogą dodawać zasoby API

Nowe API zostało zaprojektowane z myślą o rozszerzaniu przez moduły.

PrestaShop wyszukuje klasy zasobów API w modułach, gdy zastosowano wymaganą konwencję.

Udokumentowana lokalizacja w module to:

src/ApiPlatform/Resources

Umożliwia to modułowi dodawanie własnych zasobów API.

Punkt końcowy jest dostępny, gdy moduł jest zainstalowany i włączony.

Moduły mogą definiować własne zakresy uprawnień

Funkcjonalność API definiowana przez moduły powinna mieć własne uprawnienia.

Przykłady:

security_audit_read
security_audit_write
supplier_import_read
supplier_import_run

To lepsze niż wymaganie szerokiego, ogólnego dostępu.

Konektor SaaS może otrzymać dokładnie potrzebne mu uprawnienia.

Zasoby API używają atrybutów PHP

Integracja API Platform z PrestaShop używa atrybutów PHP do konfiguracji zasobów.

Dzięki temu konfiguracja punktu końcowego znajduje się blisko klasy DTO/zasobu.

Koncepcyjnie:

#[ApiResource(
    operations: [
        // API operation definitions
    ]
)]
class ExampleResource
{
    // fields
}

PrestaShop udostępnia również niestandardowe operacje oparte na CQRS, które łączą zasoby z poleceniami i zapytaniami.

Providery obsługują odczyty

W zasobach API zintegrowanych z CQRS abstrakcje Provider obsługują odczyt.

PrestaShop zawiera providery do:

• zapytań o pojedynczy zasób;
• list i danych tabelarycznych.

Provider otrzymuje konfigurację zasobu API, przekształca dane w odpowiednie zapytanie i je wysyła.

Procesory obsługują zapis

Operacje zapisu używają abstrakcji Processor.

Żądania takie jak:

• POST;
• PUT;
• PATCH;
• DELETE;

można powiązać z poleceniami CQRS.

Tworzy to przejrzysty przepływ:

żądanie HTTP
→ zasób API
→ procesor
→ polecenie CQRS
→ magistrala poleceń
→ procedura obsługi

Dlaczego to przydatne w modułach komercyjnych

Wyobraź sobie moduł importu dostawcy.

Panel administracyjny potrzebuje:

• stan kolejki;
• uruchomienie importu;
• ponawianie błędów;
• odczyt stanu dostawcy.

Panel SaaS może wymagać tych samych operacji.

Zamiast budować osobne, doraźne punkty końcowe, np.:

/modules/mymodule/run.php?secret=...

moduł może być zgodny z architekturą API administracyjnego.

Zyskujesz wtedy:

• OAuth2;
• zakresy uprawnień;
• spójną dokumentację API;
• routing frameworka;
• standardowe odpowiedzi.

Nie zamieniaj każdego długiego zadania w jedno żądanie API

API administracyjne nie eliminuje potrzeby stosowania kolejek.

Żądanie takie jak:

POST /admin-api/import-all-products

nie powinno pozostawać otwarte przez dwie godziny podczas przetwarzania 100 000 produktów.

Lepszy model:

POST /imports
→ 202 Accepted
→ identyfikator zadania

Następnie:

GET /imports/{id}

może zwrócić status.

Proces roboczy działa niezależnie.

Projektowanie operacji asynchronicznych

Dla dużych procesów:

API
→ utwórz zadanie
→ kolejka
→ proces roboczy
→ postęp

Dzięki temu opóźnienie API jest przewidywalne.

Integracja może okresowo odpytywać o status lub odbierać webhook, jeśli moduł go udostępnia.

Zapewnij idempotentność zapisów

Sieci zawodzą.

Klienci ponawiają żądania.

Załóżmy, że integracja wysyła:

utwórz mapowanie produktu dostawcy

i otrzymuje timeout, mimo że serwer wykonał operację.

Jeżeli ponowienie tworzy kolejne mapowanie, powstaje duplikat.

Stosuj:

• stabilne identyfikatory zewnętrzne;
• ograniczenia unikalności;
• klucze idempotentności w razie potrzeby.

Bezpieczne ponowienie nie może powodować drugiego skutku biznesowego.

Ograniczaj liczbę kosztownych operacji

Nawet uwierzytelnieni klienci mogą przypadkowo przeciążyć sklep.

Błąd programistyczny może wysłać tysiące żądań na sekundę.

Chroń kosztowne niestandardowe punkty końcowe przez:

• rozsądne stronicowanie;
• limity partii;
• ograniczenie liczby żądań w razie potrzeby.

Nie udostępniaj punktu końcowego zwracającego 500 000 kompletnie załadowanych produktów w jednej odpowiedzi.

Stronicuj listy

Operacje listowania API powinny mieć ograniczenia.

Preferuj:

page
limit
filters

zamiast:

podaj mi cały katalog

Do synchronizacji zwykle wydajniejsze są odczyty przyrostowe.

Stosuj synchronizację przyrostową

Jeśli zewnętrzny system raportowy zna wczorajszy katalog, nie powinien pobierać całego katalogu co godzinę.

Stosuj:

• znaczniki czasu modyfikacji;
• kursory;
• zewnętrzne identyfikatory zdarzeń;
• punkty kontrolne charakterystyczne dla domeny.

To zmniejsza:

• ruch API;
• obciążenie CPU;
• obciążenie bazy danych.

Obsługuj jawnie błędy HTTP

Twoja integracja powinna rozróżniać:

• 400: błąd walidacji;
• 401: problem z uwierzytelnianiem;
• 403: brak zakresu uprawnień;
• 404: brak zasobu;
• 409: konflikt, jeśli dotyczy;
• 429: limit żądań, jeśli wprowadzono go w infrastrukturze;
• 5xx: błąd serwera.

Nie ponawiaj każdego błędu.

Brakujące pole wymagane nie stanie się prawidłowe po dziesięciu próbach.

Loguj identyfikatory korelacji

W złożonych integracjach przypisz identyfikator korelacji do żądania lub zadania.

Logi mogą wtedy powiązać:

żądanie zewnętrzne
→ żądanie API
→ polecenie CQRS
→ zadanie w tle
→ wywołanie dostawcy

To znacznie ułatwia wsparcie techniczne.

Nigdy nie loguj sekretów

Nie zapisuj w logach:

• sekret klienta;
• pełny token Bearer;
• nagłówki autoryzacji.

Usuwaj wrażliwe dane z logów żądań.

Jeśli narzędzia debugowania zapisują pełne żądania HTTP, ogranicz dostęp i okres przechowywania.

Rotuj dane dostępowe

Przygotuj proces rotacji sekretów klienta.

Nie czekaj na podejrzenie naruszenia bezpieczeństwa.

Dojrzała integracja może:

1. utworzyć klienta zastępczego;
2. wdrożyć nowy sekret;
3. sprawdzić ruch;
4. wyłączyć starego klienta.

Oddzielni klienci to ułatwiają.

API administracyjne a starszy Webservice

Starszy Webservice nadal istnieje w ekosystemie PrestaShop, ale nowe API administracyjne reprezentuje nowoczesną architekturę wprowadzoną w PrestaShop 9.

Przy nowych integracjach najpierw rozważ API administracyjne.

Powody obejmują:

• OAuth2;
• zakresy uprawnień;
• API Platform;
• CQRS;
• rozszerzalność przez moduły;
• generowaną dokumentację OpenAPI.

Nie przepisuj stabilnej starszej integracji tylko z powodu mody.

Unikaj jednak zwiększania długu technicznego, gdy nowoczesne API spełnia już wymagania.

Proponowana architektura integracji

Integracja produkcyjna może wyglądać tak:

ERP / PIM
   ↓
token OAuth2
   ↓
API administracyjne PrestaShop
   ↓
CQRS
   ↓
Logika biznesowa
   ↓
Baza danych

Duże zadania:
API → kolejka → proces roboczy

API stanowi granicę dostępu.

Kolejka obsługuje długotrwałe zadania.

Lista kontrolna bezpieczeństwa

• HTTPS na produkcji
• Jeden klient API na integrację
• Minimalne zakresy uprawnień
• Bezpieczne przechowywanie sekretów
• Tokeny nie są logowane
• Obsługa wygasania tokenów
• Stare klienty wyłączone
• Dane wejściowe zweryfikowane
• Duże operacje asynchroniczne
• Błędy API monitorowane

Lista kontrolna programowania

• Sprawdź aktualny Swagger
• Wyeksportuj specyfikację OpenAPI
• Testuj wymagane zakresy
• Testuj wygasły token
• Testuj nieprawidłowy token
• Testuj brak zakresu
• Testuj błędy walidacji
• Testuj ponowienia
• Testuj stronicowanie
• Testuj stan wyłączonego modułu

Najczęściej zadawane pytania

Czy API administracyjne PrestaShop 9 jest domyślnie włączone?

Tak. Aktualna oficjalna dokumentacja podaje, że jest dostępne od razu w PrestaShop 9, ale nadal trzeba skonfigurować klientów i zakresy.

Jakiego uwierzytelniania używa API administracyjne?

OAuth2.

Jakiego rodzaju uwierzytelnienia użyć dla integracji serwer-serwer?

Dokumentacja PrestaShop zaleca przepływ Client Credentials dla integracji serwer-serwer.

Jaki framework obsługuje API administracyjne?

API Platform 3.

Czy API administracyjne korzysta z CQRS?

Tak. PrestaShop integruje zasoby API z istniejącymi poleceniami i zapytaniami CQRS.

Gdzie utworzyć klienta API?

W panelu administracyjnym w Parametrach zaawansowanych → Admin API lub poleceniem konsoli prestashop:api-client polecenie konsoli.

Jaki jest adres URL tokenu dostępu?

Przy wewnętrznym serwerze autoryzacji udokumentowany punkt końcowy to /admin-api/access_token.

Czy moduły mogą dodawać punkty końcowe?

Tak. Rozszerzalność przez moduły jest głównym założeniem nowego API. Zasoby modułów mogą być ładowane z src/ApiPlatform/Resources.

Czy Swagger jest dostępny?

Tak. API Platform generuje dokumentację API, a PrestaShop udostępnia Swagger/OpenAPI dla API administracyjnego.

Czy należy przyznawać integracji wszystkie zakresy uprawnień?

Nie. Dokumentacja PrestaShop wyraźnie zaleca ograniczanie zakresów klienta do niezbędnego minimum.

Powiązane poradniki i zasoby PrestaShop 9

• 10 rzeczy do zautomatyzowania za pomocą API administracyjnego PrestaShop 9
• Poradnik tworzenia modułów PrestaShop 9
• Przegląd platformy PrestaShop 9