Czym jest PrestaShop API i kiedy naprawdę Ci się przyda

PrestaShop webservice to warstwa HTTP wystawiona przez rdzeń sklepu. Zasoby (products, orders, customers, stock_availables, combinations) mają własne endpointy i obsługują metody REST-owe: GET, POST, PUT, PATCH, DELETE. Domyślnie odpowiedź wraca w XML — parametr output_format=JSON przełącza format. To inny mechanizm niż moduły i hooki: moduł działa wewnątrz PHP sklepu, sięga do klas Cart, Order, Db i reaguje na zdarzenia (actionValidateOrder, actionOrderStatusPostUpdate). API działa z zewnątrz, po HTTP, nie wymaga wgrywania kodu na serwer sklepu i nie dotyka bazy bezpośrednio. Pełną listę zasobów i metod znajdziesz w dokumentacji dla deweloperów PrestaShop.

Cztery scenariusze, w których API zarabia na siebie:

• Synchronizacja z ERP lub Subiektem. Stany magazynowe i ceny schodzą z systemu księgowego do sklepu co 15 minut. Zasób stock_availables aktualizowany przez PUT jest szybszy i bezpieczniejszy niż eksport i import CSV z backoffice.
• Etykiety u kurierów. Zewnętrzny system pobiera zamówienia z zakresu dat (orders?date_add=[2024-01-01,2024-01-31]) i odsyła numer listu przewozowego do pola shipment w zamówieniu.
• Wystawianie ofert na marketplace. Potrzebne są produkty z kombinacjami, stanami i zdjęciami — wszystko przez GET na products i combinations.
• Raportowanie do BI. Hurtownia danych pobiera raz na dobę zamówienia, klientów i pozycje zamówień, zamiast obciążać bazę sklepu ciężkimi zapytaniami SQL.

Kiedy API to overkill: jeśli potrzebujesz wyłącznie zmiany statusu zamówienia po opłaceniu, wystarczy hook actionOrderStatusPostUpdate w module — kilkadziesiąt linii kodu, zero dodatkowego HTTP i zero kluczy do pilnowania. Tak samo przy zmianie wyglądu karty produktu czy liczeniu własnego pola w koszyku. Webservice ma sens wtedy, gdy dane muszą wyjść poza sklep albo wejść do niego z systemu, którego nie da się uruchomić na tym samym serwerze. Jeśli sklep dopiero startuje, kolejność prac opisujemy w sekcji PrestaShop, a samo planowanie integracji — na stronie o organizacji wdrożenia PrestaShop.

Jak włączyć webservice w PrestaShop w 5 krokach

Cała konfiguracja siedzi w backoffice i zajmuje kilkanaście minut. Kolejność ma znaczenie — klucz tworzony przed kontem pracownika nie zapisze się poprawnie.

1. Włącz usługę sieciową. Zaawansowane parametry → Webservice → suwak „Włącz usługę sieciową” ustaw na Tak i zapisz. Od tego momentu /api/ odpowiada.
2. Załóż osobne konto. Zaawansowane parametry → Zespół → Pracownicy → Dodaj. Nazwa: integracja-erp. Profil: Minimalny albo własny, z dostępem wyłącznie do webservice. Nie używaj konta administratora — klucz admina sięga wszystkiego, a po wycieku oznacza pełne przejęcie sklepu.
3. Wygeneruj klucz i nadaj uprawnienia. Zaawansowane parametry → Webservice → Dodaj nowy klucz, wybierz konto integracji i zapisz. PrestaShop wygeneruje klucz. W tabeli uprawnień zaznaczaj tylko to, czego integracja naprawdę używa: ERP do odczytu potrzebuje GET na products, combinations i stock_availables, do zapisu stanów — PUT na stock_availables. Zamówienia: GET na orders, order_details i customers.
4. Sprawdź .htaccess i przyjazne URL. Musi działać mod_rewrite, a reguły hostingu (WAF, blokady katalogów) nie mogą zamykać katalogu /api. Najczęstszy objaw problemu to 404 na poprawnym adresie przy sprawnym kluczu.
5. Test „czy żyje”. W przeglądarce wejdź na https://twojsklep.pl/api/ — pojawi się okno logowania, wpisz klucz i zostaw hasło puste. Zobaczysz listing zasobów w XML. W terminalu to samo sprawdzisz przez curl -u "KLUCZ:" https://twojsklep.pl/api/.

Po teście zapisz konfigurację w dokumentacji projektu: adres endpointu, nazwę konta integracji, zakres uprawnień i osobę odpowiedzialną za klucz. Po pół roku nikt tego nie odtworzy z pamięci. Przy kilku systemach i niestandardowych uprawnieniach lepiej potraktować to jak projekt — tak jak opisujemy to przy organizacji i koszcie wdrożenia PrestaShop.

Autoryzacja kluczem API — Basic Auth, HTTPS i rotacja

PrestaShop webservice uwierzytelnia przez HTTP Basic Auth. Klucz jest loginem, hasło jest puste. Nagłówek wygląda tak: Authorization: Basic base64(klucz:) — po kluczu musi zostać dwukropek, inaczej base64 zakoduje sam klucz i serwer zwróci 401. W curl wystarczy -u "KLUCZ:"; dwukropek na końcu wymusza puste hasło i pomija pytanie o nie. Mechanizm i kody statusu opisuje dokumentacja HTTP w MDN Web Docs.

Trzy zasady, których nie warto łamać:

• Wymuś HTTPS. Basic Auth przesyła dane zakodowane base64, ale nie zaszyfrowane. Po HTTP klucz jest do odczytania w każdej chwili. Przekierowanie ustaw w .htaccess regułą RewriteCond %{HTTPS} off.
• Ogranicz dostęp po IP. Jeśli integracja wychodzi ze stałych adresów, zamknij katalog webservice w .htaccess, np. <Files "webservice"> Require ip 203.0.113.10 </Files> (adres przykładowy z puli dokumentacyjnej). Wtedy sam wyciek klucza nie wystarczy, żeby się dostać.
• Klucz nie trafia do repozytorium ani do JavaScriptu na stronie sklepu. Trzymaj go w zmiennych środowiskowych systemu, który się łączy, albo w pliku konfiguracyjnym poza katalogiem web. W JS na froncie każdy użytkownik zobaczy go w narzędziach deweloperskich w kilka sekund.

Rotacja, gdy klucz wyciekł albo zmienia się wykonawca integracji:

Struktura zasobów i endpoints — jak czytać /api

Każda instalacja PrestaShop wystawia webservice pod tym samym prefiksem: https://twojsklep.pl/api/. Wpisanie tego adresu w przeglądarkę — po podaniu klucza w Basic Auth — zwraca listę zasobów dostępnych w Twojej wersji. To najszybszy test, czy klucz w ogóle działa i co można przez niego zrobić, bez zaglądania do dokumentacji.

Zasoby, które realnie pojawiają się w integracjach:

Adresy działają według schematu /api/{zasob} albo /api/{zasob}/{id}. /api/products to lista produktów, /api/orders/123 — konkretne zamówienie, /api/stock_availables — stany magazynowe. Ten ostatni zasób bywa zaskoczeniem: stanu nie zmienisz, edytując pole w produkcie, bo siedzi on w osobnym zasobie powiązanym z kombinacją. To najczęstsza przyczyna sytuacji „synchronizacja przeszła, a stany się nie zgadzają”.

Domyślnie wszystko wraca w XML. Dodanie ?output_format=JSON zmienia format odpowiedzi i upraszcza pracę z JavaScriptem oraz większością bibliotek HTTP. Przed pierwszym POST-em warto pobrać szkielet obiektu: /api/products?schema=blank zwraca XML z wszystkimi polami, które można wysłać — zamiast zgadywać nazwy, kopiujesz strukturę i uzupełniasz wartości.

PrestaShop nie wstawia numeru wersji do adresu API — endpoint to zawsze /api/ plus nazwa zasobu. O tym, którą wersję obsługujesz, decyduje instalacja; sprawdzisz ją w backoffice w Parametry zaawansowane → Informacje. Różnice między 1.7 a 8.x w zachowaniu webservice'u są realne, więc wersję zapisz w dokumentacji projektu. Przy planowaniu wdrożenia PrestaShop to jedna z pierwszych rzeczy do ustalenia. Listę zasobów i ich pól weryfikuj w dokumentacji deweloperskiej PrestaShop — jest aktualizowana razem z kolejnymi wydaniami.

Filtry, sortowanie i paginacja — konkretne parametry

Najczęstszy błąd przy pierwszej integracji: pobranie /api/products i założenie, że odpowiedź zawiera całą kartotekę. Nie zawiera. Domyślny limit to 50 rekordów i PrestaShop nie sygnalizuje tego żadnym komunikatem — po prostu ucina listę. Sklep z 4000 SKU „synchronizuje się” wtedy tylko częściowo i nikt nie potrafi powiedzieć dlaczego.

Paginację ustawiaj jawnie: ?limit=0,100 oznacza „od rekordu zerowego, sto sztuk”, kolejna porcja to ?limit=100,100. Przy pierwszym uruchomieniu zrób test kontrolny — pobierz listę bez limitu i z ?limit=0,100, a potem porównaj liczbę zwróconych identyfikatorów. Jeśli są równe, kartoteka jest mniejsza niż 100 pozycji.

Filtrowanie zawęża wynik po stronie serwera, co przy dużych sklepach skraca odpowiedź z sekund do milisekund. ?filter[active]=1 to dokładne dopasowanie. Alternatywę zapisujesz pionową kreską w nawiasach, np. ?filter[price]=[100|200], a zakres przecinkiem, np. ?filter[date_upd]=[2025-01-01,2025-01-31]. Składnia operatorów różni się między wydaniami — potwierdź ją dla swojej wersji przed wdrożeniem.

Sortowanie: ?sort=[id_DESC]. Odchudzanie odpowiedzi: ?display=[id,name,price] — zamiast kilkudziesięciu pól dostajesz trzy, a transfer spada nawet o 90%.

Do synchronizacji inkrementalnej użyj ?date=1, który dokłada do odpowiedzi znaczniki date_add i date_upd, i połącz go z filtrem po dacie modyfikacji. Zamiast ciągnąć 4000 rekordów co godzinę, pobierasz kilkadziesiąt zmienionych od ostatniego przebiegu. To różnica między dwusekundowym a czterominutowym cyklem — szczegóły znajdziesz w opisie organizacji wdrożenia i migracji PrestaShop.

Przykłady: curl i PHP krok po kroku

Zacznij od GET-a, żeby sprawdzić klucz i zobaczyć realną strukturę danych:

curl -s -u "TWOJ_KLUCZ:" \
  "https://twojsklep.pl/api/products?limit=0,10&display=[id,name,price]&output_format=JSON"

Dwukropek po kluczu jest istotny — w Basic Auth klucz pełni rolę loginu, a hasło pozostaje puste. Bez niego curl zapyta o hasło interaktywnie i skrypt zawiesi się w zadaniu cron.

Tworzenie produktu wymaga poprawnego XML. Minimalny zestaw to nazwa, link_rewrite, cena, kategoria domyślna i flaga aktywności:

curl -s -u "TWOJ_KLUCZ:" -X POST \
  -H "Content-Type: application/xml" \
  --data-binary @produkt.xml \
  "https://twojsklep.pl/api/products"

Zawartość produkt.xml najprościej zbudować, pobierając najpierw szkielet przez /api/products?schema=blank i wypełniając go. Pola językowe (np. name) wymagają zagnieżdżonego <language id="1"> — pominięcie tego elementu kończy się błędem 400 bez czytelnego komunikatu.

Najdroższa pomyłka przy aktualizacjach: PUT vs PATCH. PUT wysyła pełny obiekt — pola, których nie umieścisz w XML, zostaną wyczyszczone. Jeśli chcesz zmienić samą cenę, użyj PATCH: wysyłasz tylko identyfikator i pole do zmiany, reszta zostaje nietknięta. W integracjach magazynowych PUT na produkcie regularnie kasuje opisy i zdjęcia.

Zamiast pisać klienta od zera, wykorzystaj PSWebServiceLibrary.php — plik dołączony do instalacji w katalogu /webservice/. Obsługuje uwierzytelnianie, parsowanie XML i zwraca kod HTTP w wyjątku:

require_once __DIR__ . '/PSWebServiceLibrary.php';
try {
    $ws = new PrestaShopWebservice('https://twojsklep.pl', 'TWOJ_KLUCZ', false);
    $xml = $ws->get(['resource' => 'products', 'limit' => '0,10', 'display' => '[id,name,price]']);
} catch (PrestaShopWebserviceException $e) {
    // kod HTTP: 401 zły klucz, 403 brak uprawnień, 404 zły zasób, 500 błąd serwera
    error_log('API ' . $e->getCode() . ': ' . $e->getMessage());
}

Kody 4xx oznaczają problem po Twojej stronie (klucz, uprawnienia, adres), 5xx — po stronie sklepu. Rozróżnienie pozwala od razu zdecydować, czy ponawiać zapytanie. Semantykę kodów opisuje dokumentacja HTTP w MDN. Przy szerszym projekcie warto zaplanować to razem z zakresem i kosztem wdrożenia PrestaShop, bo warstwa integracyjna bywa większa niż sam sklep.

Integracje: ERP, płatności, kurierzy, marketplace

Integracja z ERP działa w dwóch kierunkach i to ustalasz przed pierwszym zapytaniem. Stany magazynowe płyną z ERP do sklepu — w PrestaShop to zasób stock_availables, aktualizowany w pętli co 5–15 minut w godzinach pracy firmy. Zamówienia i dane do faktury płyną w drugą stronę: orders plus order_details z PrestaShop do systemu księgowego. Subiekt GT/nexo i Comarch Optima nie znają id_product — pracują na symbolu towaru. Bez tabeli mapowania SKU ↔ id_product (oraz ↔ id_product_attribute dla wariantów) pierwszy import rozjedzie stany na koszulce w rozmiarze L.

Kurierzy: InPost, DPD i DHL generują etykietę przez własne API, ale punktem startu jest zamówienie w PrestaShop. Typowy przepływ: nowe zamówienie → walidacja adresu i wagi → wywołanie API kuriera → zapis numeru przesyłki w order_carrier.tracking_number → wydruk PDF z panelu. Statusy przesyłki wracają webhookiem, jeśli kurier go udostępnia, albo pollem co 30–60 minut. Bez tego klient dowie się o doręczeniu szybciej niż Twój panel obsługi zamówień.

Idempotencja to warunek, o którym wszyscy pamiętają po pierwszym incydencie. Retry po timeoucie nie może drugi raz utworzyć faktury ani zamówienia. Klucz operacji: numer zamówienia plus typ operacji, np. ORDER-10458-INVOICE, zapisany w bazie po stronie integracji. Przy powtórzeniu system widzi istniejący klucz i kończy pracę bez duplikatu.

Typowe błędy 401/403/404/500 i jak je zdiagnozować

Zanim zaczniesz szukać w kodzie, spójrz na kod odpowiedzi HTTP — on wskazuje warstwę problemu. Kolejność diagnozy jest zawsze ta sama i zajmuje maksymalnie 5 minut.

• 401 — klucz zły albo go nie ma. Sprawdź, czy wysyłasz nagłówek Authorization: Basic ..., czy klucz jest zakodowany base64 w formacie klucz: (z dwukropkiem i pustym hasłem) i czy przy kopiowaniu nie został spacja na końcu.
• 403 — klucz istnieje, ale nie ma uprawnień do zasobu. W backoffice, w Zaawansowane parametry → Webservice, kolumny GET/POST/PUT/DELETE muszą mieć zaznaczone to, czego naprawdę używasz. Drugi powód to blokada IP: jeśli serwer ERP ma zmienne IP, whitelistę trzeba wpisać zakresem albo z niej zrezygnować.
• 404 — webservice wyłączony w backoffice, literówka w nazwie zasobu (/api/order zamiast /api/orders) albo przekierowanie HTTP → HTTPS, którego klient nie obsługuje. Adres bazowy i certyfikat sprawdzasz raz, na starcie.
• 500 — najczęściej niepoprawny XML, brak pola wymaganego przez walidację obiektu (np. id_lang przy opisie) lub wartość spoza dozwolonego zakresu.

Gdzie szukać szczegółów: Zaawansowane parametry → Logi, gdzie trafiają wywołania webservice; chwilowe włączenie _PS_MODE_DEV_ w config/defines.inc.php na kopii sklepu; Postman z zapisanym środowiskiem do pojedynczych testów. Same kody odpowiedzi i ich znaczenie opisuje dokumentacja HTTP.

Bezpieczeństwo, wydajność i utrzymanie integracji

PrestaShop webservice nie ma wbudowanego rate limitingu. Możesz wysłać tysiąc zapytań w minutę i nikt Cię nie zatrzyma — dopóki baza nie zacznie się dusić. Ograniczenie tempa musi więc siedzieć po Twojej stronie: kolejka zadań (np. tabela zadań z timeoutem) i backoff wykładniczy przy błędach, czyli pierwsza próba, potem 2 s, 4 s, 8 s, maksymalnie 3–4 próby. Bez tego jedna awaria po stronie ERP zamienia się w pętlę dobijającą sklep.

Ostrożnie z ?limit=0. Na katalogu 5 tys. produktów to jedno zapytanie zwracające całą tabelę — pamięć procesu PHP kończy się szybciej, niż myślisz. Pobieraj stronami po 100–200 rekordów (?limit=100&page=1) i filtruj po date_upd z ostatniej synchronizacji. Pola używane w filtrach, np. reference czy date_upd, powinny mieć indeks w bazie — inaczej każde zapytanie kończy się pełnym skanem tabeli.

Monitoring: loguj kod odpowiedzi, czas i endpoint każdego wywołania do pliku lub tabeli. Trzy metryki wystarczą na start: odsetek 5xx, średni czas odpowiedzi i liczba rekordów w kolejce. Alert ustaw na pierwszy 5xx, nie na dziesiąty — po dziesiątym problem trwa już godzinę.

Przed pierwszym dużym importem zrób mysqldump bazy i przećwicz cały przepływ na kopii sklepu. Kolejność: staging → jeden produkt → 100 produktów → całość. Tak wygląda organizacja projektu wdrożenia PrestaShop, którego nie trzeba potem ratować w nocy.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Decyzja: API czy moduł/hook — Przed włączeniem webservice ustal, czy zadania nie rozwiąże gotowy moduł. Dla pojedynczej zmiany statusu zamówienia API jest overkillem — wystarczy hook.
• Osobne konto pracownika dla integracji — Sprawdź w Zaawansowane parametry → Webservice, że klucz należy do konta integracyjnego, a nie do admina. Zweryfikuj, czy nie ma dostępu do backoffice.
• Zakres uprawnień per zasób i metoda — Przejrzyj listę uprawnień i porównaj ją z listą wywołań w kodzie integracji. Wszystko, czego nie ma w kodzie, powinno być odznaczone.
• Test „czy żyje” — Wejdź na /api/ z kluczem w nagłówku Authorization i sprawdź, czy dostajesz listing zasobów w XML. Brak odpowiedzi oznacza problem z .htaccess, mod_rewrite lub przyjaznymi URL.
• HTTPS wymuszony na całej domenie — Sprawdź przekierowanie z http:// na https:// dla adresu /api. Potwierdź, że certyfikat obejmuje właściwą domenę lub subdomenę integracyjną.
• Whitelist adresów IP integracji — Jeśli integracja wychodzi ze stałego adresu IP (ERP, serwer kuriera), ogranicz dostęp do /api w .htaccess. Sprawdź, czy nie blokujesz własnego środowiska testowego.
• Klucz poza repozytorium i poza frontem — Przeszukaj repozytorium i kod JS w poszukiwaniu klucza. Zweryfikuj, że zapytania do API nie są widoczne w narzędziach deweloperskich przeglądarki.
• Świadomość domyślnego limitu — Sprawdź, ile rekordów domyślnie zwraca Twoja instalacja i czy liczba zgadza się ze stanem faktycznym. Zapisz ustaloną wartość ?limit w dokumentacji integracji.
• Format odpowiedzi ustalony z góry — Zdecyduj, czy integracja pracuje na XML, czy na JSON (?output_format=JSON), i ustaw to w kodzie. Mieszanie formatów w jednym projekcie generuje błędy parsowania.
• Obsługa błędów i ponowień — Sprawdź, jak integracja reaguje na odpowiedź 401, 404 i 500. Brak logiki ponowień przy chwilowym błędzie serwera oznacza ciche dziury w danych.
• Procedura rotacji klucza opisana — Zapisz w dokumentacji: nowy klucz, równoległe działanie starego i nowego przez 24 h, wygaszenie starego, przegląd logów po zmianie.
• Monitoring po wdrożeniu — Ustal, kto i jak często sprawdza logi API oraz czy liczba zsynchronizowanych rekordów zgadza się z liczbą rekordów źródłowych.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – dane strukturalne
• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• MDN Web Docs – HTTP