Jak zintegrować ChatGPT z PrestaShop

Integracja ChatGPT z PrestaShop potrafi zautomatyzować tworzenie treści, odciążyć obsługę klienta i podnieść konwersję bez przepisywania całego sklepu. Poniżej znajdziesz praktyczną instrukcję: od planu architektury, przez budowę własnego modułu, po osadzenie funkcji na kartach produktów i w back office. Pokażę też, jak bezpiecznie przechowywać klucz API, radzić sobie z błędami i kosztami, dbać o prywatność oraz wydajność. Całość opiera się na natywnych mechanizmach PrestaShop i sprawdzonych wzorcach wdrożeń.

Przygotowanie środowiska i plan integracji

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

• Działający sklep PrestaShop w wersji 1.7.x lub 8.x (PHP 7.4+ / 8.x, MySQL/MariaDB).
• Dostęp SSH/FTP oraz do panelu administracyjnego (Back Office), możliwość instalacji modułów.
• Klucz do OpenAI — indywidualny token autoryzacyjny do wywołań.
• Możliwość wykonywania połączeń wychodzących HTTPS (serwer nie może blokować zapytań do zewnętrznych API).
• Opcjonalnie: system kolejkowy (np. Redis + supervisor) lub CRON do zadań wsadowych.

Wybór scenariuszy użycia

Najczęstsze wdrożenia obejmują:

• Generator opisów produktów i atrybutów (różne długości, ton, języki).
• Asystent pytań i odpowiedzi (Q&A) na karcie produktu – dynamiczne odpowiedzi na podstawie danych produktu.
• Tworzenie i aktualizowanie metadanych (tytuły, opisy, słowa kluczowe) pod kątem SEO.
• Wspomaganie obsługi zamówień (makra: odpowiadanie na powtarzalne pytania o status, zwroty, dopasowanie akcesoriów).
• Wsparcie tłumaczeń treści i internacjonalizacji (lokalizacja opisów, e-maili transakcyjnych).

Na początek wybierz 1–2 przypadki i wdrażaj inkrementalnie. Każdy przypadek to osobna usługa w module — łatwiej utrzymać i testować.

Architektura rozwiązania

Minimalna architektura obejmuje:

• Własny moduł PrestaShop (folder modules/nazwa_modułu), z plikiem głównym i kontrolerami.
• Panel konfiguracji (formularz w Back Office) do przechowywania klucza OpenAI i opcji.
• Serwis/kontroler obsługujący żądania HTTP do API i normalizację odpowiedzi.
• Kompresję, limity i mechanizmy pamięci podręcznej (cache) wyników, zwłaszcza przy generacji długich treści.
• Hooki PrestaShop – do wpinania funkcji w kartę produktu, zapis produktu, panel administracyjny.

Bezpieczeństwo, prywatność i zgodność

• Przechowuj klucz w bazie (Configuration) i nigdy nie wysyłaj go do frontendu/JS.
• Waliduj i filtruj dane wejściowe przekazywane do modelu (np. ID produktu, język, zakres długości).
• Loguj błędy po stronie serwera (pliki logów) z maskowaniem wrażliwych danych.
• Przeglądaj politykę RODO: nie wysyłaj do zewnętrznego dostawcy danych osobowych klientów, chyba że masz wyraźną podstawę prawną i spełniasz obowiązki informacyjne.
• Wprowadź przełącznik trybu testowego (sandbox) i opcje gaszenia funkcji (feature flags).

Tworzenie modułu PrestaShop do komunikacji z ChatGPT

Szkielet modułu

Utwórz folder modules/pschatgpt i w nim plik pschatgpt.php z minimalnym szkieletem. Przykład:

<?php
if (!defined(’BASEPATH’)) exit;
class Pschatgpt extends Module {
  public function __construct() {
    $this->name = 'pschatgpt’;
    $this->version = '1.0.0′;
    $this->author = 'TwojaFirma’;
    $this->tab = 'administration’;
    $this->need_instance = 0;
    parent::__construct();
    $this->displayName = $this->l(’Integracja z ChatGPT’);
    $this->description = $this->l(’Generowanie treści i asystent AI.’);
  }

  public function install() {
    return parent::install()
      && $this->registerHook(’displayAdminProductsExtra’)
      && $this->registerHook(’actionProductSave’)
      && $this->registerHook(’displayProductAdditionalInfo’);
  }

  public function uninstall() {
    Configuration::deleteByName(’PSCHATGPT_API_KEY’);
    return parent::uninstall();
  }
}
?>

Hooki można dopasować do własnych potrzeb (np. displayFooter do widżetu czatu, actionValidateOrder do automatyzacji zamówień).

Panel konfiguracji i przechowywanie klucza

Dodaj formularz w Back Office (getContent) i zapisz klucz:

public function getContent() {
  $output = ”;
  if (Tools::isSubmit(’submit_pschatgpt’)) {
    $key = Tools::getValue(’PSCHATGPT_API_KEY’);
    Configuration::updateValue(’PSCHATGPT_API_KEY’, pSQL($key));
    $output .= $this->displayConfirmation($this->l(’Zapisano.’));
  }
  $form = '<form method=”post”>’
    .’.<label>OpenAI API Key</label>
    .’.<input type=”password” name=”PSCHATGPT_API_KEY” value=”” />’
    .’.<button class=”btn btn-primary” name=”submit_pschatgpt”>Zapisz</button>’;
  $form .= '</form>’;
  return $output.$form;
}

Warto dodać więcej opcji: wybór modelu, maksymalna długość odpowiedzi, język domyślny, limity kosztów.

Klient HTTP i wywołania OpenAI

Najprościej użyć wbudowanego cURL. W środowiskach PS 1.7/8 można też wstrzyknąć klienta Symfony (HttpClient) lub Guzzle. Minimalny klient cURL:

private function callOpenAI($messages, $temperature = 0.7, $maxTokens = 800) {
  $apiKey = Configuration::get(’PSCHATGPT_API_KEY’);
  $payload = array(
    'model’ => 'gpt-4o-mini’,
    'messages’ => $messages,
    'temperature’ => (float)$temperature,
    'max_tokens’ => (int)$maxTokens,
  );
  $ch = curl_init(’https://api.openai.com/v1/chat/completions’);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ’.$apiKey,
    'Content-Type: application/json’
  ));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  $res = curl_exec($ch);
  if ($res === false) {
    throw new Exception(’cURL error: ’.curl_error($ch));
  }
  $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);
  if ($status < 200 || $status >= 300) {
    throw new Exception(’OpenAI HTTP ’.$status.’: ’.$res);
  }
  $data = json_decode($res, true);
  return $data[’choices’][0][’message’][’content’] ?? ”;
}

Funkcja przyjmuje tablicę messages w formacie: role: system|user|assistant oraz content. Do sklepu warto zbudować cienką warstwę usług (np. Services/ChatService.php) i trzymać tam formaty promptów dla różnych przypadków użycia.

Obsługa błędów, limity i odporność

• Ustal timeout połączenia (curl_setopt: CURLOPT_TIMEOUT 20–30 s).
• Retry z wykładniczym backoffem przy błędach 429/5xx, ale z licznikami, aby nie dublować kosztów.
• Sanity-check na długość wejścia (np. 4–8 tys. znaków), wstępna kondensacja danych produktu.
• Soft-fail: jeśli API nie odpowie, pokaż domyślne treści lub komunikat nieblokujący konwersji.

Wbudowanie funkcji AI w sklepie

Generator opisów produktów

Wpięcie w zakładkę edycji produktu w Back Office (hook displayAdminProductsExtra) pozwoli dodać przycisk „Wygeneruj opis”. Po kliknięciu kontroler AJAX tworzy kontekst i wysyła żądanie do API:

• Pobierz: nazwę, krótkie i techniczne parametry, atrybuty, grupę docelową, język.
• Zbuduj wiadomości: system (zasady stylu), user (dane produktu, ton, długość), opcjonalnie przykłady.
• Wyświetl podgląd + przycisk „Zastąp opis” albo „Wstaw jako szkic”.

Przykładowy kontekst:

$messages = array(
  array(’role’ => 'system’, 'content’ => 'Jesteś asystentem e-commerce. Styl: klarowny, korzyści, język polski, unikaj przesady.’),
  array(’role’ => 'user’, 'content’ => 'Stwórz opis 100–150 słów, nagłówki, lista korzyści. Produkt: Klawiatura mechaniczna XYZ, przełączniki czerwone, podświetlenie RGB, 2 lata gwarancji, dla graczy.’),
);
$desc = $this->callOpenAI($messages, 0.6, 400);

Zapamiętaj wynik w bazie i pozwól edytorowi dopracować. Dodaj pełnotekstową walidację (zakazane frazy, linki, zgodność z brand bookiem).

Q&A na karcie produktu (asystent kontekstowy)

Hook displayProductAdditionalInfo lub displayFooter może osadzić widżet pytanie-odpowiedź. Przepływ:

• Użytkownik wpisuje pytanie (np. „Czy ta mysz działa z MacOS?”).
• Frontend odsyła AJAX do kontrolera modułu (brak ekspozycji klucza).
• Kontroler buduje kontekst: dane techniczne, dostępne warianty, FAQ, polityka zwrotów.
• Odpowiedź zwraca JSON i renderuje się w komponencie.

Warto włączyć filtr bezpieczeństwa: usuwanie PII, ograniczenia długości, transliterację. Odpowiedź powinna mieć ostrzeżenia, gdy pewność jest niska, oraz linki do źródeł w sklepie (np. karta produktu, regulamin).

Automatyczne metadane i struktura pod SEO

Przy zapisie/aktualizacji produktu (hook actionProductSave) uruchom generację meta title/description i ewentualnie fragmentów opisów kategorii. Zapewnij szablony z ograniczeniami długości (np. title ≤ 60 znaków, description ≤ 160 znaków) i kontrolą fraz kluczowych. Używaj pamięci podręcznej i nie przeliczaj treści przy każdym drobnym zapisie, aby niepotrzebnie nie wywoływać API. Dobrą praktyką jest dodatkowa walidacja lingwistyczna i antyduplikacyjna dla efektu SEO.

Wsparcie obsługi zamówień i e-maili

• Generowanie szkiców odpowiedzi na najczęstsze pytania („gdzie paczka?”, „jak zwrócić?”) na podstawie szablonów i danych zamówienia.
• Automatyczne podpowiedzi upsell/cross-sell w panelu konsultanta lub w e-mailach transakcyjnych.
• Kanał wewnętrzny: podsumowania długich wątków, klasyfikacja ticketów.

W tych przypadkach szczególnie uważaj na dane osobowe. Nie przekazuj imion, adresów ani numerów przesyłek, jeżeli nie masz jasnej podstawy prawnej i umów powierzenia.

Optymalizacja, wdrożenie i utrzymanie

Wydajność i pamięć podręczna

• Cache na poziomie modułu: wyniki generatora opisów i metadanych zapisuj np. w własnej tabeli z kluczem produkt+język+szablon oraz TTL. W pamięci lokalnej możesz używać APCu/Redis.
• Cache HTTP: dla Q&A stosuj krótkie TTL (10–60 s) dla pytań powtarzalnych, pamiętając o anonimizacji.
• Batch processing: masowa generacja dla kategorii przez CRON i limity na zadanie (np. 50 produktów/run), aby nie blokować zasobów.
• Streaming: gdy obsługujesz długie odpowiedzi, rozważ streaming odpowiedzi i progressive rendering frontendu.

W operacjach wsadowych zminimalizujesz liczbę wywołań poprzez łączenie kontekstu (np. wspólne cechy produktów) i reużycie promptów. Warto także dbać o wewnętrzne cache obrazów, jeżeli generujesz alternatywne teksty alt.

Monitoring, logowanie i alerty

• Loguj: ID żądania, czas odpowiedzi, rozmiar payloadu, koszt jednostkowy, status HTTP, skrót treści.
• Wysyłaj alerty (mail/Slack) przy wzroście błędów 5xx/429, braku odpowiedzi lub nagłej zmianie czasu odpowiedzi.
• Dzienniki dostępów do panelu konfiguracyjnego — audyt edycji klucza i opcji.

W PrestaShop 8 skorzystasz z integracji z Symfony i Monolog. W starszych wersjach utrzymaj spójne pliki logów w var/logs lub modules/pschatgpt/logs.

Testy A/B, treść i UX

• Eksperymentuj z wariantami promptów: ton, długość, kolejność informacji, liczba wypunktowań.
• Porównuj metryki: CTR na listingu, dwell time na karcie produktu, współczynnik konwersji.
• Dbaj o czytelność: rozbijaj ściany tekstu nagłówkami i listami, wstawiaj mikrocopy o pochodzeniu treści AI.

Zapewnij możliwość łatwego przywrócenia treści ręcznych i oznaczaj, które fragmenty powstały z pomocą AI (transparentność dla zespołu i zgodność z wytycznymi marketplace’ów).

Koszty, limity i rozliczenia

• Ustal budżety dzienne/miesięczne w module i gaśnice (feature flags) przy zbliżaniu się do limitów.
• Kompresuj kontekst: skracanie danych produktu, usuwanie zbędnych atrybutów, ponowne użycie wygenerowanych streszczeń.
• Wstępna walidacja wejścia po stronie frontu (limit znaków, dozwolone pola), aby zmniejszać liczbę wywołań.

Rozważ rozdzielenie środowisk: development (klucz deweloperski, mniejsze modele), staging (test danych), produkcja (pełne modele, monitoring). Dzięki temu zmiany w promptach i UI nie zaskoczą klientów.

Bezpieczeństwo i prywatność danych

• Tokenizacja i maskowanie: zanim wyślesz dane, maskuj osobowe identyfikatory (np. zamień #ZAM12345 na wzorzec ogólny). To ogranicza ryzyko wycieku.
• Kontrola dostępu: tylko administratorzy mogą przeglądać i edytować klucz; loguj każde odczytanie.
• Data minimization: wysyłaj tylko informacje konieczne do odpowiedzi; nie przekazuj danych klientów w modułach Q&A.
• Regulaminy i polityka prywatności: zaktualizuj zapisy o korzystaniu z dostawców zewnętrznych i celach przetwarzania; uwzględnij sprzeciw/zgodę, jeżeli to właściwe.

Pamiętaj o testach penetracyjnych podstawowych ścieżek: XSS w widżecie Q&A, CSRF w panelu konfiguracji, SSRF przy składaniu żądań do API. Wymuś HTTPS w całym sklepie.

Aktualizacje, migracje i zgodność wersji

• Przechowywanie konfiguracji w Configuration ułatwia eksport/import między środowiskami.
• Dodając nowe funkcje, inkrementuj wersję modułu i przygotuj skrypty upgrade (install-*.php lub metody upgradeModule).
• Śledź zmiany API dostawcy — parametry modeli, endpointy; trzymaj warstwę kliencką oddzielnie, by łatwo podmieniać szczegóły implementacji.

Przykładowe osadzenie funkcji: od UI do hooków

Back Office: karta produktu z przyciskiem AI

W hooku displayAdminProductsExtra wyrenderuj panel:

<div class=”panel”>
  <h3>Asystent treści AI</h3>
  <p>Wygeneruj opis, skrót i metadane na podstawie danych produktu.</p>
  <button id=”btn-generate” class=”btn btn-primary”>Wygeneruj opis</button>
  <div id=”preview”></div>
</div>

Przycisk wywołuje kontroler AdminAjax (module/pschatgpt/generate?product_id=…). Ten zbiera dane produktu (Product::getProductProperties), buduje wiadomości i wywołuje callOpenAI. Odpowiedź podaje w HTML z możliwością edycji i akceptacji.

Front Office: widżet Q&A na karcie produktu

W hooku displayProductAdditionalInfo dołącz komponent:

<div id=”qa-ai” data-product=”{$product.id}”>
  <label>Masz pytanie o ten produkt?</label>
  <textarea id=”qa-input” maxlength=”300″></textarea>
  <button id=”qa-send” class=”btn”>Zapytaj</button>
  <div id=”qa-thread”></div>
</div>

Po stronie serwera kontroler waliduje pytania (długość, zakazane frazy), buduje kontekst z danych produktu i kieruje zapytanie do API. Wynik jest moderowany (np. proste reguły treści), a następnie renderowany jako odpowiedź z linkami do polityk. Warto dodać limit pytań na sesję i mechanizm antyspamowy.

Automatyczne meta title i description

W hooku actionProductSave, gdy flaga „Auto SEO” jest włączona, skompiluj meta wg szablonów. Przykładowy prompt systemowy: „Jesteś specjalistą e-commerce. Tworzysz zwięzłe, dokładne meta tytuły i opisy w języku docelowym, zgodne z dobrymi praktykami”. Użytkownik (user) przekazuje: nazwę, markę, 2–3 cechy, słowo kluczowe, limity znaków. Odpowiedź utnij do długości, usuń znaki specjalne i zapisz w polach produktu dla danego języka.

Webhooks i automatyzacja

Jeśli chcesz automatyzować po stronie zewnętrznej, rozważ prosty endpoint webhook w module (FrontController z autoryzacją kluczem modułu). Może uruchamiać generację dla wskazanego produktu/kategorii, synchronizować wyniki i raportować statusy do narzędzi no-code. Dbaj o zabezpieczenia: podpis HMAC, lista dozwolonych IP, rate limit.

Kontrola jakości treści

• Reguły stylistyczne: listy wypunktowane, unikanie CAPS, wstawianie CTA.
• Filtry: czarna lista fraz, linków, niezgodnych obietnic (np. „dożywotnia gwarancja”).
• Human-in-the-loop: tryb „Szkic” zamiast natychmiastowej publikacji, workflow akceptacji.

Integruj proste klasyfikatory (np. ton wypowiedzi) przed publikacją. Przechowuj historię wersji treści, aby łatwo cofnąć zmiany.

Lista kontrolna wdrożenia i dobre praktyki

Techniczne checklisty

• Kod modułu w repozytorium (git), CI do testów podstawowych (lint, statyczna analiza).
• Konfiguracja środowisk i kluczy oddzielna dla dev/stage/prod.
• Obsługa błędów: komunikaty przyjazne, ale nieskrywające faktów (bez ujawniania sekretów).
• Limity zasobów: concurrency, timeouty, pamięć; ochrona przed burzą żądań.
• Dokumentacja: jak używać, jak wyłączać, jak aktualizować szablony promptów.

UX i dostępność

• Widżet Q&A responsywny, fokusowalny, z obsługą klawiatury i screen readerów.
• Wyraźne etykiety i opisy, informacja o pochodzeniu treści (AI wspiera, człowiek nadzoruje).
• Fallback: gdy AI niedostępne, użytkownik nadal widzi najważniejsze informacje.

Przykładowe polityki promptów

Dla spójności treści zdefiniuj standardowe szablony:

• Opis produktu: „Korzyści + cechy + zastosowania, bez haseł marketingowych bez pokrycia, prosty język, 120–160 słów, 1 nagłówek, 1 lista”.
• Meta SEO: „Tytuł ≤ 60 znaków, opis ≤ 160 znaków, naturalne frazy, brak powtórzeń brandu”.
• Q&A: „Zwięzłe, precyzyjne odpowiedzi; gdy brak pewności, wskaż ograniczenia i poproś o doprecyzowanie”.

Traktuj prompt jak konfigurację — trzymaj w plikach YAML/JSON lub w bazie z wersjonowaniem i testami A/B.

Asynchroniczność i zadania wsadowe

• CRON endpoint modułu: /module/pschatgpt/cron/generate?batch=… wyzwala partię produktów.
• Kolejki: gdy dostępne, wrzucaj zadania do kolejki (Redis) i przetwarzaj przez workers z limitem RPS.
• Idempotencja: identyfikuj zadania po kluczu (produkt+język+typ), aby uniknąć duplikatów.

Przy masowych generacjach loguj postęp (np. 50/200), zapisuj błędy per rekord i pozwól wznowić pracę od ostatniego poprawnego punktu.

Minimalny front-kontroler do AJAX

Aby nie mieszać logiki z plikiem modułu, dodaj kontroler modules/pschatgpt/controllers/front/Generate.php:

class PschatgptGenerateModuleFrontController extends ModuleFrontController {
  public function initContent() {
    parent::initContent();
    $idProduct = (int)Tools::getValue(’id_product’);
    $lang = (int)Context::getContext()->language->id;
    if (!$idProduct) { die(json_encode(array(’error’=>’Brak ID produktu’))); }
    // Zbuduj kontekst i wywołaj serwis
    $messages = …;
    try {
      $content = $this->module->callOpenAI($messages, 0.6, 500);
      die(json_encode(array(’ok’=>true, 'content’=>$content)));
    } catch (Exception $e) {
      http_response_code(502);
      die(json_encode(array(’error’=>’Błąd generacji’)));
    }
  }
}

Pamiętaj o nagłówkach JSON i tokenie CSRF albo podpisie żądania, jeśli endpoint ma być publiczny.

Najczęstsze problemy i rozwiązania

• Czas odpowiedzi zbyt długi — skróć kontekst, zmniejsz max_tokens, włącz caching wyników.
• Błędy 429 (rate limit) — wprowadź kolejkę i backoff, rozłóż zadania na CRON-y.
• Jakość treści nierówna — dopracuj systemowy prompt i podaj przykłady, dodaj walidację po generacji.
• Niechciane halucynacje — ogranicz kontekst do faktów z bazy sklepu, dodaj regułę: „jeśli brak danych, powiedz, że nie wiesz”.
• Przechodzenie klucza do frontu — nigdy; wszystkie wywołania tylko serwer-serwer.

Dobrą praktyką jest również wydzielenie klasy kontekstu produktu: ekstrakcja najważniejszych cech (nazwa, marka, kategoria, 5–7 kluczowych parametrów), normalizacja jednostek i języka. Dzięki temu generacje są powtarzalne, a koszty niższe. Dla zamówień ogranicz metadane do nieidentyfikujących pól (np. status, typ płatności) i testuj na danych sztucznych. Gdy integrujesz wiele punktów funkcjonalnych, udokumentuj przepływy i określ priorytety żądań, aby zapobiegać blokadom. Wreszcie, jeśli planujesz marketingowe eksperymenty, trzymaj warianty w konfiguracji i pozwól szybko przełączać strategie treści.

Na koniec warto dodać drobne usprawnienia operacyjne: migawki bazy przed masową generacją, licznik dziennych wywołań w panelu modułu, przycisk „tryb konserwacji” dla Q&A, a także listę ostatnich 20 wygenerowanych elementów z możliwością cofnięcia. Dzięki temu zespół będzie miał kontrolę, a ryzyko niepożądanych zmian spadnie do minimum. Jeśli planujesz integracje z innymi systemami (ERP, PIM), trzymaj moduł jako cienką warstwę i buduj adaptery w osobnych klasach. Pozwoli to przełączać źródła danych bez naruszania logiki generacji i zwiększy odporność rozwiązania na zmiany w ekosystemie sklepu.