# Moduł ChatGPT Checkout PrestaShop (ACP): instalacja i konfiguracja
> Kompletny przewodnik instalacji i konfiguracji modułu ChatGPT Checkout (ACP) dla PrestaShop 8 i 9: klucz API, podpis, endpointy, płatność delegowana Stripe i webhooki.
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/chatgpt-checkout-acp/index.md), [en](https://www.datafirefly.com/en/documentation/chatgpt-checkout-acp/index.md), [es](https://www.datafirefly.com/es/documentation/chatgpt-checkout-acp/index.md), [de](https://www.datafirefly.com/de/documentation/chatgpt-checkout-acp/index.md), [it](https://www.datafirefly.com/it/documentation/chatgpt-checkout-acp/index.md), [pt](https://www.datafirefly.com/pt/documentation/chatgpt-checkout-acp/index.md), [nl](https://www.datafirefly.com/nl/documentation/chatgpt-checkout-acp/index.md)
- Indeks:
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).
Bez przyjaznych adresów URL ścieżki takie jak `/acp/checkout_sessions` nie są rozwiązywane. Dopóki przepisywanie adresów nie jest aktywne, w konfiguracji modułu wyświetla się ostrzeżenie.
## 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
Przed wdrożeniem produkcyjnym sprawdź nazwy pól Stripe dla płatności agentowych względem konfiguracji swojego konta (metoda `chargeStripe` w `classes/DfAiAgentOrder`). Płatność pozostaje opcjonalna: bez obciążenia przez moduł zamówienie jest tworzone w statusie początkowym i rozliczane przez Twojego operatora płatności.
## 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.