Modulo ChatGPT Checkout per PrestaShop (ACP) — Installazione & configurazione

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).

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

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.