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

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

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

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.