# Modulo ChatGPT Checkout per PrestaShop (ACP) — Installazione & configurazione
> Guida completa all'installazione e configurazione del modulo ChatGPT Checkout (ACP) per PrestaShop 8 e 9: chiave API, firma, endpoint, pagamento delegato Stripe e webhook.
- Pagina:
- Lingua: it
- Aggiornato il: 2026-06-17
- Altre lingue: [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), [pl](https://www.datafirefly.com/pl/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)
- Indice:
Questo modulo trasforma il tuo negozio PrestaShop in un backend di commercio agentico conforme all'**Agentic Commerce Protocol (ACP)**, lo standard aperto mantenuto da OpenAI e Stripe. Un agente IA (ChatGPT, Claude, Perplexity) può scoprire i tuoi prodotti tramite un feed autenticato, creare una sessione di checkout e completare l'acquisto — generando un ordine PrestaShop reale nel tuo negozio.
## Requisiti
- PrestaShop 8.0 a 9.x (compatibile con multinegozio).
- Negozio servito in **HTTPS** (il protocollo lo richiede; gli endpoint forzano l'SSL).
- **URL semplificati** attivati (SEO & URL → Riscrittura degli URL): i percorsi REST ne dipendono.
- Un account Stripe se desideri attivare il pagamento delegato (opzionale).
Senza URL semplificati, i percorsi come `/acp/checkout_sessions` non vengono risolti. Nella configurazione del modulo viene mostrato un avviso finché la riscrittura degli URL non è attiva.
## Installazione
1. Back office → **Moduli** → _Carica un modulo_, poi seleziona l'archivio `dfaiagent.zip`.
2. Attiva gli **URL semplificati** se non l'hai già fatto.
3. Apri la configurazione del modulo: copia l'**URL di base** e la **chiave API** per l'onboarding della piattaforma agentica.
## Configurazione
### Chiave API (Bearer)
Una chiave API viene generata all'installazione. Gli agenti si autenticano con l'header `Authorization: Bearer LA_TUA_CHIAVE_API`. Puoi rigenerare la chiave in qualsiasi momento dal pannello; quella vecchia smette di funzionare immediatamente.
### Slug dell'URL di base
Segmento di percorso degli endpoint (predefinito `acp`). L'URL di base diventa `https://il-tuo-negozio.com/acp`.
### Verifica della firma
Se attivata, il modulo verifica l'header `Signature`: un HMAC-SHA256 del corpo grezzo della richiesta, codificato in base64, calcolato con il segreto condiviso fornito dalla piattaforma agentica.
### Webhook d'ordine
Inserisci l'**URL di webhook** della piattaforma e un **segreto di firma**. Alla creazione dell'ordine viene inviato un evento `order_created`, firmato tramite l'header `DataFirefly-Signature`.
### Pagamento delegato Stripe (opzionale)
Se «Addebita tramite Stripe» è attivo ed è stata inserita una chiave segreta Stripe, lo _shared payment token_ ricevuto al completamento viene addebitato tramite un PaymentIntent Stripe confermato, prima della creazione dell'ordine.
### Stati dell'ordine
Scegli lo stato iniziale (ordine creato senza addebito da parte del modulo) e lo stato «pagato» (addebito Stripe riuscito).
## Endpoint
Con lo slug predefinito `acp`:
- `POST /acp/checkout_sessions` — creare una sessione
- `POST /acp/checkout_sessions/{id}` — aggiornare (articoli, indirizzo, opzione di spedizione)
- `GET /acp/checkout_sessions/{id}` — consultare lo stato attuale
- `POST /acp/checkout_sessions/{id}/complete` — completare e creare l'ordine
- `POST /acp/checkout_sessions/{id}/cancel` — annullare
- `GET /acp/feed?page=1&limit=200` — feed di catalogo
### Creare una sessione
```
curl -X POST "https://il-tuo-negozio.com/acp/checkout_sessions" -H "Authorization: Bearer LA_TUA_CHIAVE_API" -H "Content-Type: application/json" -d '{ "items": [ { "id": "42", "quantity": 1 } ] }'
```
La risposta restituisce lo stato completo del carrello: `line_items`, `totals`, `fulfillment_options`, `currency` e `status`. Gli importi sono in **unità minori** (centesimi).
### Aggiornare (indirizzo, spedizione)
```
curl -X POST "https://il-tuo-negozio.com/acp/checkout_sessions/cs_XXXX" -H "Authorization: Bearer LA_TUA_CHIAVE_API" -H "Content-Type: application/json" -d '{ "fulfillment_option_id": "ship_2" }'
```
### Completare
```
curl -X POST "https://il-tuo-negozio.com/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer LA_TUA_CHIAVE_API" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Maria Rossi", "email": "maria@esempio.it" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'
```
In caso di successo, viene creato un ordine PrestaShop e la risposta include un oggetto `order` (id + link permanente).
## Autenticazione e firma
Ogni richiesta deve includere l'header `Authorization: Bearer` con la chiave API. Quando la verifica della firma è attiva, il modulo ricalcola l'HMAC-SHA256 del corpo e lo confronta con l'header `Signature` tramite un confronto a tempo costante. Gli header `Idempotency-Key` e `Request-Id` vengono restituiti nella risposta.
## Codifica degli identificativi articolo
L'`item.id` ACP segue il formato `{id_prodotto}` o `{id_prodotto}-{id_combinazione}`. Esempio: `42` per un prodotto semplice, `42-7` per la combinazione 7 del prodotto 42. La stessa codifica è usata nel feed di catalogo.
## Feed di catalogo
L'endpoint `GET /acp/feed` (autenticato) espone i tuoi prodotti attivi e le loro combinazioni, con `price`, `availability`, `inventory_quantity` ed `enable_checkout`. Usa `page` e `limit` per la paginazione.
## Pagamento delegato Stripe
Prima della messa in produzione, verifica i nomi dei campi Stripe «agentic payments» rispetto alla configurazione del tuo account (metodo `chargeStripe` in `classes/DfAiAgentOrder`). Il pagamento resta opzionale: senza addebito da parte del modulo, l'ordine viene creato nello stato iniziale e incassato dal tuo PSP.
## Webhook d'ordine
Alla creazione dell'ordine, il modulo invia un evento `order_created` all'URL configurato, con uno stato ACP derivato dallo stato dell'ordine PrestaShop (`created`, `confirmed`, `shipped`, `fulfilled`, `canceled`). Il payload è firmato con HMAC.
## Collegare una piattaforma agentica
Fornisci alla piattaforma (ad es. l'onboarding di ChatGPT Instant Checkout): l'**URL di base**, la **chiave API** e, se necessario, il segreto di firma e l'URL/segreto del webhook. Poiché il modulo resta il commerciante di riferimento, mantieni il controllo su stock, prezzi, tasse e pagamento.
## Risoluzione dei problemi
### Gli endpoint restituiscono una pagina 404 / HTML
Attiva gli URL semplificati e svuota la cache di PrestaShop. Verifica che lo slug di base corrisponda all'URL fornito alla piattaforma.
### Risposta 401
La chiave API è assente o errata nell'header `Authorization`, oppure la firma non corrisponde al segreto configurato.
### L'ordine non viene creato
Assicurati che siano forniti un indirizzo di spedizione valido e un'opzione di spedizione, che lo stock sia sufficiente e — se l'addebito Stripe è attivo — che la chiave segreta Stripe sia corretta.