# Módulo ChatGPT Checkout para PrestaShop (ACP) — Instalación & configuración

> Guía completa de instalación y configuración del módulo ChatGPT Checkout (ACP) para PrestaShop 8 y 9: clave API, firma, endpoints, pago delegado Stripe y webhooks.

- Página: <https://www.datafirefly.com/es/documentation/chatgpt-checkout-acp/>
- Idioma: es
- Actualizado el: 2026-06-17
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/chatgpt-checkout-acp/index.md), [en](https://www.datafirefly.com/en/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)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

Este módulo convierte tu tienda PrestaShop en un backend de comercio agéntico conforme al **Agentic Commerce Protocol (ACP)**, el estándar abierto mantenido por OpenAI y Stripe. Un agente de IA (ChatGPT, Claude, Perplexity) puede descubrir tus productos mediante un flujo autenticado, crear una sesión de pago y completar la compra, lo que crea un pedido real de PrestaShop en tu tienda.

## Requisitos

- PrestaShop 8.0 a 9.x (compatible con multitienda).
- Tienda servida en **HTTPS** (el protocolo lo exige; los endpoints fuerzan el SSL).
- **URL amigables** activadas (SEO & URLs → Reescritura de URL): las rutas REST dependen de ello.
- Una cuenta Stripe si deseas activar el pago delegado (opcional).

Sin URL amigables, las rutas como `/acp/checkout_sessions` no se resuelven. Se muestra un aviso en la configuración del módulo mientras la reescritura de URL no esté activa.

## Instalación

1. Back office → **Módulos** → _Subir un módulo_, luego selecciona el archivo `dfaiagent.zip`.
2. Activa las **URL amigables** si aún no lo has hecho.
3. Abre la configuración del módulo: copia la **URL base** y la **clave API** para el onboarding de la plataforma agéntica.

## Configuración

### Clave API (Bearer)

Se genera una clave API en la instalación. Los agentes se autentican con la cabecera `Authorization: Bearer TU_CLAVE_API`. Puedes regenerar la clave en cualquier momento desde el panel; la antigua deja de funcionar de inmediato.

### Slug de la URL base

Segmento de ruta de los endpoints (por defecto `acp`). La URL base queda como `https://tu-tienda.com/acp`.

### Verificación de firma

Si está activada, el módulo verifica la cabecera `Signature`: un HMAC-SHA256 del cuerpo bruto de la petición, codificado en base64, calculado con el secreto compartido facilitado por la plataforma agéntica.

### Webhooks de pedido

Indica la **URL de webhook** de la plataforma y un **secreto de firma**. Al crear el pedido se envía un evento `order_created`, firmado mediante la cabecera `DataFirefly-Signature`.

### Pago delegado Stripe (opcional)

Si «Cobrar con Stripe» está activado y se ha indicado una clave secreta de Stripe, el _shared payment token_ recibido al completar se cobra mediante un PaymentIntent de Stripe confirmado, antes de crear el pedido.

### Estados de pedido

Elige el estado inicial (pedido creado sin cobro por el módulo) y el estado «pagado» (cobro de Stripe correcto).

## Endpoints

Con el slug por defecto `acp`:

- `POST /acp/checkout_sessions` — crear una sesión
- `POST /acp/checkout_sessions/{id}` — actualizar (artículos, dirección, opción de envío)
- `GET /acp/checkout_sessions/{id}` — consultar el estado actual
- `POST /acp/checkout_sessions/{id}/complete` — completar y crear el pedido
- `POST /acp/checkout_sessions/{id}/cancel` — cancelar
- `GET /acp/feed?page=1&limit=200` — flujo de catálogo

### Crear una sesión

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

La respuesta devuelve el estado completo del carrito: `line_items`, `totals`, `fulfillment_options`, `currency` y `status`. Los importes están en **unidades menores** (céntimos).

### Actualizar (dirección, envío)

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

### Completar

```
curl -X POST "https://tu-tienda.com/acp/checkout_sessions/cs_XXXX/complete" -H "Authorization: Bearer TU_CLAVE_API" -H "Content-Type: application/json" -d '{ "buyer": { "name": "María García", "email": "maria@ejemplo.es" }, "payment_data": { "token": "spt_123", "provider": "stripe" } }'
```

Si tiene éxito, se crea un pedido de PrestaShop y la respuesta incluye un objeto `order` (id + enlace permanente).

## Autenticación y firma

Cada petición debe llevar la cabecera `Authorization: Bearer` con la clave API. Cuando la verificación de firma está activada, el módulo recalcula el HMAC-SHA256 del cuerpo y lo compara con la cabecera `Signature` mediante una comparación en tiempo constante. Las cabeceras `Idempotency-Key` y `Request-Id` se devuelven en la respuesta.

## Codificación de identificadores de artículo

El `item.id` de ACP sigue el formato `{id_producto}` o `{id_producto}-{id_combinacion}`. Ejemplo: `42` para un producto simple, `42-7` para la combinación 7 del producto 42. El mismo formato se usa en el flujo de catálogo.

## Flujo de catálogo

El endpoint `GET /acp/feed` (autenticado) expone tus productos activos y sus combinaciones, con `price`, `availability`, `inventory_quantity` y `enable_checkout`. Usa `page` y `limit` para la paginación.

## Pago delegado Stripe

Antes de pasar a producción, verifica los nombres de campo de Stripe «agentic payments» con la configuración de tu cuenta (método `chargeStripe` en `classes/DfAiAgentOrder`). El pago es opcional: sin cobro por el módulo, el pedido se crea en el estado inicial y lo captura tu PSP.

## Webhooks de pedido

Al crear el pedido, el módulo envía un evento `order_created` a la URL configurada, con un estado ACP derivado del estado de pedido de PrestaShop (`created`, `confirmed`, `shipped`, `fulfilled`, `canceled`). La carga útil se firma con HMAC.

## Conectar una plataforma agéntica

Facilita a la plataforma (por ejemplo, el onboarding de ChatGPT Instant Checkout): la **URL base**, la **clave API** y, si es necesario, el secreto de firma y la URL/secreto de webhook. Como el módulo sigue siendo el comerciante de referencia, mantienes el control sobre stock, precios, impuestos y pago.

## Resolución de problemas

### Los endpoints devuelven una página 404 / HTML

Activa las URL amigables y vacía la caché de PrestaShop. Comprueba que el slug base coincide con la URL facilitada a la plataforma.

### Respuesta 401

Falta la clave API o es incorrecta en la cabecera `Authorization`, o la firma no coincide con el secreto configurado.

### El pedido no se crea

Asegúrate de que se facilita una dirección de envío válida y una opción de envío, de que hay stock suficiente y —si el cobro de Stripe está activado— de que la clave secreta de Stripe es correcta.