# Module ChatGPT Checkout PrestaShop (ACP) — Installation & configuration

> Guide complet d'installation et de configuration du module ChatGPT Checkout (ACP) pour PrestaShop 8 et 9 : clé API, signature, endpoints, paiement délégué Stripe et webhooks.

- Page: <https://www.datafirefly.com/documentation/chatgpt-checkout-acp/>
- Langue: fr
- Mis à jour le: 2026-06-17
- Autres langues: [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), [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)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

Ce module transforme votre boutique PrestaShop en backend de commerce agentique conforme à l'**Agentic Commerce Protocol (ACP)**, le standard ouvert porté par OpenAI et Stripe. Un agent IA (ChatGPT, Claude, Perplexity) peut découvrir vos produits via un flux authentifié, créer une session de paiement, puis finaliser l'achat — ce qui crée une vraie commande PrestaShop dans votre boutique.

## Prérequis

- PrestaShop 8.0 à 9.x (compatible multiboutique).
- Boutique servie en **HTTPS** (le protocole l'impose, les endpoints forcent le SSL).
- **URLs simplifiées** activées (SEO & URLs → Réécriture d'URL) : les chemins REST en dépendent.
- Un compte Stripe si vous souhaitez activer le paiement délégué (optionnel).

Sans URLs simplifiées, les chemins comme `/acp/checkout_sessions` ne sont pas résolus. Un avertissement s'affiche dans la configuration du module tant que la réécriture d'URL n'est pas active.

## Installation

1. Back-office → **Modules** → _Téléverser un module_, puis sélectionnez l'archive `dfaiagent.zip`.
2. Activez les **URLs simplifiées** si ce n'est pas déjà fait.
3. Ouvrez la configuration du module : copiez l'**URL de base** et la **clé API** pour l'onboarding de la plateforme agentique.

## Configuration

### Clé API (Bearer)

Une clé API est générée à l'installation. Les agents s'authentifient avec l'en-tête `Authorization: Bearer VOTRE_CLE_API`. Vous pouvez régénérer la clé à tout moment depuis le panneau ; l'ancienne cesse immédiatement de fonctionner.

### Slug de l'URL de base

Segment de chemin des endpoints (par défaut `acp`). L'URL de base ressemble alors à `https://votre-boutique.com/acp`.

### Vérification de signature

Si activée, le module vérifie l'en-tête `Signature` : un HMAC-SHA256 du corps brut de la requête, encodé en base64, calculé avec le secret partagé fourni par la plateforme agentique.

### Webhooks de commande

Renseignez l'**URL de webhook** de la plateforme et un **secret de signature**. À la création de commande, un évènement `order_created` est poussé, signé via l'en-tête `DataFirefly-Signature`.

### Paiement délégué Stripe (optionnel)

Si « Débiter via Stripe » est activé et qu'une clé secrète Stripe est renseignée, le _shared payment token_ reçu à la complétion est débité via un PaymentIntent Stripe confirmé, avant la création de la commande.

### Statuts de commande

Choisissez le statut initial (commande créée sans débit par le module) et le statut « payé » (débit Stripe réussi).

## Points de terminaison (endpoints)

Avec le slug par défaut `acp` :

- `POST /acp/checkout_sessions` — créer une session
- `POST /acp/checkout_sessions/{id}` — mettre à jour (articles, adresse, option de livraison)
- `GET /acp/checkout_sessions/{id}` — consulter l'état courant
- `POST /acp/checkout_sessions/{id}/complete` — finaliser et créer la commande
- `POST /acp/checkout_sessions/{id}/cancel` — annuler
- `GET /acp/feed?page=1&limit=200` — flux catalogue

### Créer une session

```
curl -X POST "https://votre-boutique.com/acp/checkout_sessions" -H "Authorization: Bearer VOTRE_CLE_API" -H "Content-Type: application/json" -d '{ "items": [ { "id": "42", "quantity": 1 } ] }'
```

La réponse renvoie l'état complet du panier : `line_items`, `totals`, `fulfillment_options`, `currency` et `status`. Les montants sont en **unités mineures** (centimes).

### Mettre à jour (adresse, livraison)

```
curl -X POST "https://votre-boutique.com/acp/checkout_sessions/cs_XXXX" -H "Authorization: Bearer VOTRE_CLE_API" -H "Content-Type: application/json" -d '{ "fulfillment_option_id": "ship_2" }'
```

### Finaliser

```
curl -X POST "https://votre-boutique.com/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer VOTRE_CLE_API" -H "Content-Type: application/json" -d '{ "buyer": { "name": "Marie Martin", "email": "marie@exemple.fr" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'
```

En cas de succès, une commande PrestaShop est créée et la réponse contient un objet `order` (id + lien permanent).

## Authentification et signature

Chaque requête doit porter l'en-tête `Authorization: Bearer` avec la clé API. Si la vérification de signature est activée, le module recalcule le HMAC-SHA256 du corps et le compare à l'en-tête `Signature` avec une comparaison à temps constant. Les en-têtes `Idempotency-Key` et `Request-Id` sont renvoyés dans la réponse.

## Encodage des identifiants d'article

L'`item.id` ACP suit le format `{id_produit}` ou `{id_produit}-{id_declinaison}`. Exemple : `42` pour un produit simple, `42-7` pour la déclinaison 7 du produit 42. Le même encodage est utilisé dans le flux catalogue.

## Flux catalogue

L'endpoint `GET /acp/feed` (authentifié) expose vos produits actifs et leurs déclinaisons, avec `price`, `availability`, `inventory_quantity` et `enable_checkout`. Utilisez `page` et `limit` pour la pagination.

## Paiement délégué Stripe

Avant la mise en production, vérifiez les noms de champs Stripe « agentic payments » par rapport à la configuration de votre compte (méthode `chargeStripe` dans `classes/DfAiAgentOrder`). Le paiement reste optionnel : sans débit par le module, la commande est créée dans le statut initial et capturée par votre PSP.

## Webhooks de commande

À la création de commande, le module envoie un évènement `order_created` à l'URL configurée, avec un statut ACP dérivé de l'état de commande PrestaShop (`created`, `confirmed`, `shipped`, `fulfilled`, `canceled`). La charge utile est signée via HMAC.

## Connecter une plateforme agentique

Communiquez à la plateforme (par ex. l'onboarding ChatGPT Instant Checkout) : l'**URL de base**, la **clé API**, et si nécessaire le secret de signature et l'URL/secret de webhook. Le module restant le marchand de référence, vous gardez la main sur le stock, les prix, les taxes et le paiement.

## Dépannage

### Les endpoints renvoient une page 404 / HTML

Activez les URLs simplifiées et videz le cache PrestaShop. Vérifiez que le slug de base correspond bien à l'URL transmise à la plateforme.

### Réponse 401

La clé API est absente ou erronée dans l'en-tête `Authorization`, ou la signature ne correspond pas au secret configuré.

### La commande n'est pas créée

Vérifiez qu'une adresse de livraison valide et une option de livraison sont fournies, que le stock est suffisant, et — si le débit Stripe est activé — que la clé secrète Stripe est correcte.