Moduł ChatGPT Checkout PrestaShop (ACP): instalacja i konfiguracja

Ten moduł zamienia Twój sklep PrestaShop w backend handlu agentowego zgodny z Agentic Commerce Protocol (ACP), otwartym standardem rozwijanym przez OpenAI i Stripe. Agent AI (ChatGPT, Claude, Perplexity) może odkryć Twoje produkty przez uwierzytelniony feed, utworzyć sesję płatności, a następnie sfinalizować zakup, co tworzy prawdziwe zamówienie PrestaShop w Twoim sklepie.

Wymagania wstępne

• PrestaShop 8.0 do 9.x (zgodny z multisklepem).
• Sklep serwowany po HTTPS (wymaga tego protokół, endpointy wymuszają SSL).
• Włączone przyjazne adresy URL (SEO i adresy URL → Przepisywanie adresów URL): od nich zależą ścieżki REST.
• Konto Stripe, jeśli chcesz włączyć płatność delegowaną (opcjonalnie).

Instalacja

1. Panel administracyjny → Moduły → Wgraj moduł, następnie wybierz archiwum dfaiagent.zip.
2. Włącz przyjazne adresy URL, jeśli nie są jeszcze aktywne.
3. Otwórz konfigurację modułu: skopiuj adres bazowy i klucz API potrzebne do onboardingu platformy agentowej.

Konfiguracja

Klucz API (Bearer)

Klucz API jest generowany przy instalacji. Agenci uwierzytelniają się nagłówkiem Authorization: Bearer TWOJ_KLUCZ_API. Klucz możesz w każdej chwili wygenerować ponownie z panelu modułu, poprzedni przestaje wtedy działać natychmiast.

Slug adresu bazowego

Segment ścieżki endpointów (domyślnie acp). Adres bazowy wygląda wtedy tak: https://twoj-sklep.pl/acp.

Weryfikacja podpisu

Po włączeniu moduł weryfikuje nagłówek Signature: HMAC-SHA256 surowego ciała żądania, zakodowany w base64 i obliczony na współdzielonym sekrecie dostarczonym przez platformę agentową.

Webhooki zamówień

Uzupełnij adres URL webhooka platformy oraz sekret podpisu. Przy utworzeniu zamówienia wysyłane jest zdarzenie order_created, podpisane nagłówkiem DataFirefly-Signature.

Płatność delegowana Stripe (opcjonalnie)

Jeśli opcja obciążania przez Stripe jest włączona i podano tajny klucz Stripe, shared payment token otrzymany przy finalizacji jest obciążany potwierdzonym PaymentIntent Stripe, przed utworzeniem zamówienia.

Statusy zamówień

Wybierz status początkowy (zamówienie utworzone bez obciążenia przez moduł) oraz status opłacony (udane obciążenie Stripe).

Punkty końcowe (endpointy)

Przy domyślnym slugu acp:

• POST /acp/checkout_sessions: utworzenie sesji
• POST /acp/checkout_sessions/{id}: aktualizacja (pozycje, adres, opcja dostawy)
• GET /acp/checkout_sessions/{id}: odczyt bieżącego stanu
• POST /acp/checkout_sessions/{id}/complete: finalizacja i utworzenie zamówienia
• POST /acp/checkout_sessions/{id}/cancel: anulowanie
• GET /acp/feed?page=1&limit=200: feed katalogu

Utworzenie sesji

curl -X POST "https://twoj-sklep.pl/acp/checkout_sessions" -H "Authorization: Bearer TWOJ_KLUCZ_API" -H "Content-Type: application/json" -d '{ "items": [ { "id": "42", "quantity": 1 } ] }'

Odpowiedź zwraca pełny stan koszyka: line_items, totals, fulfillment_options, currency i status. Kwoty są podawane w jednostkach mniejszych (grosze).

Aktualizacja (adres, dostawa)

curl -X POST "https://twoj-sklep.pl/acp/checkout_sessions/cs_XXXX" -H "Authorization: Bearer TWOJ_KLUCZ_API" -H "Content-Type: application/json" -d '{ "fulfillment_option_id": "ship_2" }'

Finalizacja

curl -X POST "https://twoj-sklep.pl/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer TWOJ_KLUCZ_API" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Anna Kowalska", "email": "anna@przyklad.pl" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'

W razie powodzenia tworzone jest zamówienie PrestaShop, a odpowiedź zawiera obiekt order (identyfikator i link stały).

Uwierzytelnianie i podpis

Każde żądanie musi zawierać nagłówek Authorization: Bearer z kluczem API. Gdy weryfikacja podpisu jest włączona, moduł ponownie oblicza HMAC-SHA256 ciała żądania i porównuje go z nagłówkiem Signature porównaniem o stałym czasie. Nagłówki Idempotency-Key i Request-Id są zwracane w odpowiedzi.

Kodowanie identyfikatorów pozycji

Pole item.id w ACP ma format {id_produktu} lub {id_produktu}-{id_wariantu}. Przykład: 42 dla produktu prostego, 42-7 dla wariantu 7 produktu 42. To samo kodowanie jest stosowane w feedzie katalogu.

Feed katalogu

Uwierzytelniony endpoint GET /acp/feed udostępnia Twoje aktywne produkty i ich warianty wraz z polami price, availability, inventory_quantity i enable_checkout. Do stronicowania służą parametry page i limit.

Płatność delegowana Stripe

Webhooki zamówień

Przy utworzeniu zamówienia moduł wysyła zdarzenie order_created na skonfigurowany adres URL, ze statusem ACP wyprowadzonym ze stanu zamówienia PrestaShop (created, confirmed, shipped, fulfilled, canceled). Ładunek jest podpisany algorytmem HMAC.

Podłączenie platformy agentowej

Przekaż platformie (na przykład podczas onboardingu ChatGPT Instant Checkout): adres bazowy, klucz API, a w razie potrzeby sekret podpisu oraz adres URL i sekret webhooka. Ponieważ to Twój sklep pozostaje sprzedawcą referencyjnym, zachowujesz kontrolę nad stanem magazynowym, cenami, podatkami i płatnością.

Rozwiązywanie problemów

Endpointy zwracają stronę 404 lub HTML

Włącz przyjazne adresy URL i wyczyść pamięć podręczną PrestaShop. Sprawdź, czy slug bazowy odpowiada adresowi przekazanemu platformie.

Odpowiedź 401

Klucz API jest nieobecny lub błędny w nagłówku Authorization, albo podpis nie zgadza się ze skonfigurowanym sekretem.

Zamówienie nie jest tworzone

Sprawdź, czy podano prawidłowy adres dostawy i opcję dostawy, czy stan magazynowy jest wystarczający oraz, jeśli obciążanie Stripe jest włączone, czy tajny klucz Stripe jest poprawny.