10 rzeczy, które zautomatyzujesz dzięki API administracyjnemu PrestaShop 9

PrestaShop 9 wprowadził nowe API administracyjne oparte na API Platform 3, OAuth2 i architekturze CQRS PrestaShop.

Ma to znaczenie, ponieważ automatyzacja handlu internetowego działa najlepiej, gdy systemy zewnętrzne komunikują się ze sklepem za pomocą stabilnych operacji biznesowych, zamiast bezpośrednio zmieniać tabele bazy danych.

Nowoczesna instalacja PrestaShop może wymagać komunikacji z:

• dostawcami;
• ERP;
• PIM;
• CRM;
• systemami magazynowymi;
• oprogramowaniem księgowym;
• platformami handlowymi;
• platformami analitycznymi;
• aplikacjami SaaS.

Administracyjne API zapewnia programistom lepszą podstawę do takich integracji.

Ten artykuł przedstawia dziesięć praktycznych scenariuszy automatyzacji i wyjaśnia, jak bezpiecznie je projektować.

Uwaga dotycząca wersji: API administracyjne jest stale rozwijane. Zawsze sprawdzaj dokumentację OpenAPI wygenerowaną dla konkretnej wersji PrestaShop 9, z którą integrujesz system. Poniższe przykłady opisują wzorce architektury, a nie gwarantują istnienia każdej operacji biznesowej jako wbudowanego punktu końcowego we wszystkich wydaniach 9.x.

Dlaczego nowe API administracyjne jest ważne

Starsze API Webservice PrestaShop opiera się w dużej mierze na operacjach CRUD i starszym mechanizmie ObjectModel.

API administracyjne PrestaShop 9 zaprojektowano wokół:

• OAuth2;
• zakresów uprawnień;
• API Platform;
• poleceń i zapytań CQRS;
• rozszerzalności przez moduły.

Dzięki temu lepiej nadaje się do kontrolowanej automatyzacji.

Dobra automatyzacja powinna być:

• uwierzytelniona;
• autoryzowana;
• monitorowalna;
• idempotentna;
• odporna na ponowne próby;
• ograniczona pod względem obciążenia.

API zapewnia punkt dostępu, natomiast długotrwałe zadania mogą nadal być przetwarzane przez kolejki i procesy robocze CLI.

1. Automatyzacja synchronizacji informacji o produktach

System PIM może zarządzać:

• nazwami produktów;
• opisami;
• numerami referencyjnymi;
• markami;
• cechami;
• wymiarami;
• identyfikatorami.

Zamiast ręcznie kopiować dane do PrestaShop, usługa synchronizacji może przesyłać zatwierdzone zmiany.

Najważniejsze pytanie projektowe brzmi:

Który system jest źródłem prawdy dla każdego pola?

Na przykład:

PIM odpowiada za:
- tytuł
- opis
- cechy

ERP odpowiada za:
- koszt
- stany magazynowe

PrestaShop odpowiada za:
- tekst merchandisingowy
- lokalne przypisanie kategorii

Bez zasad własności danych systemy wzajemnie nadpisują swoje zmiany.

Stosuj aktualizacje przyrostowe

Nie zapisuj ponownie wszystkich produktów co godzinę.

Wykorzystaj:

• znaczników czasu modyfikacji;
• skrótów kontrolnych źródła;
• zdarzeń zmian.

Jeśli produkt się nie zmienił, pomiń go.

2. Automatyzacja synchronizacji stanów magazynowych

Stany magazynowe to jeden z najważniejszych obszarów automatyzacji.

Ręczna aktualizacja stanów magazynowych powoduje:

• sprzedaż ponad dostępny stan;
• anulowanie zamówień;
• niezadowolenie klientów.

System magazynowy lub ERP może synchronizować stany z PrestaShop.

Stosuj stałe identyfikatory dla:

• produktów;
• kombinacji;
• magazynów.

Nigdy nie polegaj wyłącznie na nazwach.

Obsługuj nieaktualne dane

Załóżmy, że migawka stanu magazynowego została wygenerowana o:

10:00

ale dotarła po nowszej aktualizacji utworzonej o:

10:05

Integracja musi rozpoznawać, która migawka jest nowsza.

Przechowuj znaczniki czasu lub numery sekwencji.

Nie stosuj bezrefleksyjnie aktualizacji w kolejności ich przychodzenia.

3. Automatyzacja aktualizacji cen

Systemy dostawców lub ERP mogą określać:

• cenę podstawową;
• koszt;
• marże;
• reguły promocyjne.

Automatyzacja cen powinna umożliwiać audyt.

Zapisuj:

stara wartość
nowa wartość
źródło
znacznik czasu
powód

Pozwala to szybko wyjaśnić błędną cenę.

Unikaj ponownego zapisywania całego katalogu

Jeśli zmieniło się tylko 400 ze 100 000 cen, zaktualizuj wyłącznie te 400.

Ograniczenie operacji zapisu poprawia:

• wydajność;
• przejrzystość audytu;
• stabilność pamięci podręcznej.

4. Automatyzacja tworzenia nowych produktów

Wykrywanie nowych produktów różni się od aktualizacji istniejących.

Przydatna architektura wygląda tak:

Kanał danych dostawcy
→ wykrywanie
→ walidacja
→ kolejka tworzenia
→ PrestaShop

Przed utworzeniem produktu sprawdź:

• wymagane mapowanie kategorii;
• mapowanie marek;
• reguły podatkowe;
• atrybuty kombinacji;
• wymagane zdjęcia;
• unikalny numer referencyjny.

Jeśli dane są niekompletne, oznacz produkt jako zablokowany.

Nie pozwól, aby jeden nieprawidłowy produkt dostawcy zatrzymał cały katalog.

5. Automatyzacja eksportu zamówień

Zamówienia często muszą być przekazywane poza PrestaShop.

Możliwe systemy docelowe:

• ERP;
• magazyn;
• operator logistyczny;
• system księgowy.

Eksport powinien korzystać z jawnego stanu synchronizacji.

Na przykład:

nowe
w przetwarzaniu
wyeksportowane
ponowna próba
nieudane

Nie myl zewnętrznego statusu synchronizacji ze statusem zamówienia PrestaShop widocznym dla klienta.

Zapewnij idempotentność ponowień

Jeśli po utworzeniu zamówienia w ERP wystąpi przekroczenie czasu oczekiwania w sieci, ponowna próba nie może utworzyć drugiego zamówienia.

Użyj zewnętrznego klucza zamówienia, np.:

prestashop-shop2-order-54883

System odbiorcy powinien rozpoznawać duplikaty.

6. Automatyzacja synchronizacji z CRM

System CRM może odbierać:

• zdarzenia dotyczące kont klientów;
• podsumowania zamówień;
• dane o segmentach klientów.

Minimalizuj zakres danych.

Nie przesyłaj wszystkich pól bazy danych tylko dlatego, że istnieją.

Przesyłaj tylko dane potrzebne CRM do określonego celu biznesowego.

W przypadku działań marketingowych przestrzegaj zgód i obowiązujących wymogów ochrony prywatności.

7. Automatyzacja kontroli jakości katalogu

Automatyzacja nie zawsze musi modyfikować dane.

Może wykrywać problemy.

Przykłady:

• produkt bez zdjęcia;
• brak opisu;
• cena zerowa;
• nieprawidłowy EAN;
• nieprzypisana kategoria;
• zduplikowany numer referencyjny dostawcy;
• kombinacja z niekompletnymi atrybutami.

Usługa kontroli jakości może utworzyć raport lub kolejkę do weryfikacji.

Stosuj poziomy pewności

Niektóre problemy można naprawić automatycznie.

Na przykład:

usuń końcowe białe znaki

Inne wymagają weryfikacji przez człowieka.

Na przykład:

wybierz między dwiema sprzecznymi kategoriami dostawcy

Oddzielaj jednoznaczne poprawki od niejednoznacznych decyzji.

8. Automatyzacja raportowania i hurtowni danych

Produkcyjna baza danych nie powinna pełnić funkcji hurtowni analitycznej.

Złożone raporty mogą analizować dane z wielu lat i konkurować o zasoby z obsługą zamówień.

Zamiast tego eksportuj przyrostowo dane operacyjne do:

• hurtowni danych;
• systemu BI;
• bazy raportowej.

Stosuj punkty kontrolne.

Na przykład:

identyfikator ostatniego wyeksportowanego zamówienia

lub:

znacznik czasu ostatniej modyfikacji

Następnie pobieraj tylko nowsze rekordy.

9. Automatyzacja prac konserwacyjnych

API administracyjne może uczestniczyć w orkiestracji wdrożeń i konserwacji.

Kontrolowany system wdrożeń może:

1. wstrzymywać importy;
2. sprawdzać stan sklepu;
3. wdrażać kod;
4. czyścić wybrane pamięci podręczne;
5. uruchamiać migracje bazy danych;
6. sprawdzać kondycję API;
7. ponownie uruchamiać zadania w tle.

Niebezpieczne operacje powinny mieć wąskie uprawnienia.

Nie twórz klienta API z nieograniczonym dostępem tylko dlatego, że automatyzacja jest wygodna.

10. Tworzenie integracji SaaS specyficznych dla modułów

Jedną z najciekawszych funkcji API administracyjnego jest jego rozszerzalność przez moduły.

Moduły mogą dodawać klasy zasobów API w:

src/ApiPlatform/Resources

Pozwala to komercyjnym modułom udostępniać własne uporządkowane API.

Przykłady:

• stan skanowania bezpieczeństwa;
• stan kolejki importu;
• stan licencji;
• raporty modułów;
• zaplanowane zadania.

Zamiast niestandardowych skryptów takich jak:

/modules/example/run.php?token=SECRET

możesz wykorzystać model OAuth2 i zakresy uprawnień platformy.

Przykład: architektura automatyzacji dostawców

Integracja z dostawcą może wykorzystywać:

API/XML dostawcy
      ↓
Moduł pobierania
      ↓
Parser strumieniowy
      ↓
Walidacja
      ↓
Kolejka
      ├── twórz produkty
      ├── aktualizuj ceny
      ├── aktualizuj stany
      └── przetwarzaj obrazy

API może udostępniać:

GET /supplier/jobs
POST /supplier/jobs
GET /supplier/jobs/{id}
POST /supplier/jobs/{id}/retry

Długotrwałe operacje pozostają w systemie procesów roboczych.

API pozostaje szybkie.

API nie zastępuje crona

API administracyjne jest interfejsem.

Cron określa, kiedy uruchamiane są zadania cykliczne.

Na przykład:

cron co 5 minut
→ proces roboczy wywołuje dostawcę
→ proces roboczy aktualizuje PrestaShop

lub:

zewnętrzny harmonogram
→ API administracyjne
→ tworzy zadanie
→ kolejka przetwarza zadanie

Oba rozwiązania mogą być poprawne.

Używaj OAuth2 Client Credentials

Dla integracji między systemami PrestaShop opisuje przepływ Client Credentials.

Klient żąda tokenu, używając:

• identyfikatora klienta;
• sekretu klienta;
• typu przyznania uprawnień;
• zakresów uprawnień.

Następnie wywołuje API za pomocą:

Authorization: Bearer ACCESS_TOKEN

Ograniczaj zakresy uprawnień

Jeśli system raportowy tylko odczytuje produkty, nie powinien otrzymywać uprawnień do zapisu.

Twórz osobnych klientów dla:

• ERP;
• PIM;
• analityki;
• magazyn.

Ułatwia to zarządzanie uprawnieniami i rotację danych dostępowych.

Wykorzystuj OpenAPI jako kontrakt

PrestaShop może generować dokumentację API.

Wykorzystaj specyfikację OpenAPI do:

• generowania klientów;
• tworzenia testów;
• porównywania wersji;
• sprawdzania zmian punktów końcowych.

W przypadku komercyjnej integracji przechowuj specyfikacje API dla każdej obsługiwanej wersji PrestaShop.

Zaprojektuj stronicowanie

Nigdy nie żądaj od API zwrócenia całego katalogu w jednej odpowiedzi.

Stosuj:

page
limit
cursor
filters

W dużych sklepach stronicowanie chroni zarówno API, jak i bazę danych.

Stosuj zadania asynchroniczne dla ciężkich operacji

Żądanie nie powinno pozostawać otwarte podczas importowania 100 000 produktów.

Stosuj:

POST /jobs
→ identyfikator zadania

GET /jobs/{id}
→ postęp

Proces roboczy przetwarza zadanie osobno.

Zapisuj postęp

Długotrwałe procesy powinny udostępniać:

łącznie
przetworzone
zmienione
pominięte
nieudane
pozostałe

Dzięki temu operacje są widoczne.

Status zawierający tylko:

w toku

nie wystarcza przy trzygodzinnym imporcie.

Oddzielaj ponowienia od trwałych błędów

Problemy tymczasowe:

• przekroczenie czasu;
• HTTP 503;
• zakleszczenie bazy danych.

Można je ponowić.

Błędy trwałe:

• nieprawidłowy identyfikator;
• nieprzypisana kategoria;
• zduplikowana definicja kombinacji.

Należy je zablokować do weryfikacji.

Używaj identyfikatorów korelacji

Przypisz unikalny identyfikator uruchomienia.

Przykład:

IMPORT-20260922-00152

Uwzględnij go w:

• logach API;
• logach procesów roboczych;
• rejestrach błędów.

Znacznie przyspiesza to diagnozowanie problemów.

Monitoruj stan automatyzacji

Monitoruj:

• ostatnie udane uruchomienie;
• czas trwania;
• przetworzone rekordy;
• błędy;
• ponowienia;
• wiek kolejki.

Uruchom alarm, gdy:

• oczekiwane zadanie nie zostało uruchomione;
• kolejka przestaje się opróżniać;
• wskaźnik błędów gwałtownie rośnie;
• czas wykonania się podwaja.

Lista kontrolna bezpieczeństwa

• HTTPS
• jeden klient na integrację
• minimalne uprawnienia
• sekrety poza kodem źródłowym
• nigdy nie logować tokenów
• ograniczone ponowienia
• walidować dane wejściowe
• uwierzytelniać punkty końcowe zadań
• przechowywać logi audytowe

Lista kontrolna projektowania automatyzacji

• określone źródło prawdy
• stabilne identyfikatory zewnętrzne
• idempotentne zapisy
• aktualizacje przyrostowe
• stronicowanie
• zadania asynchroniczne dla ciężkich operacji
• trwale zapisany postęp
• jawne ponowienia
• monitorowanie
• plan wycofania lub uzgodnienia

Najczęściej zadawane pytania

Czy API administracyjne może zastąpić zadania cron?

Nie. API zapewnia dostęp do operacji. Cron lub inny harmonogram nadal określa, kiedy uruchamiane są zadania cykliczne.

Czy mogę zaimportować 100 000 produktów w jednym żądaniu API?

To złe rozwiązanie. Utwórz zadanie i przetwarzaj je asynchronicznie w partiach.

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

Tak. API administracyjne PrestaShop 9 zaprojektowano specjalnie z myślą o rozszerzaniu przez moduły.

Czy OAuth2 jest wymagany?

Nowe API administracyjne używa OAuth2 do uwierzytelniania i autoryzacji.

Czy wszystkie integracje powinny korzystać z jednego klienta API?

Nie. Oddzielni klienci ułatwiają bezpieczne zarządzanie uprawnieniami, unieważnianiem dostępu i audytem.

Jaka jest najważniejsza zasada automatyzacji?

Zapewnij idempotentność operacji. Ponowienie nie powinno powodować podwójnych skutków biznesowych.

Powiązane poradniki i zasoby PrestaShop 9

• Poradnik API administracyjnego PrestaShop 9
• tworzenie modułu PrestaShop 9
• dokumentacja PrestaSuite