Asistente de recuperación de carritos basado en inteligencia artificial para Magento 2

Módulo Magento 2 para recuperar carritos abandonados con funciones de:

• detección de carritos abandonados
• scoring del carrito mediante AI o heurística
• generación de mensajes de e-mail para recuperar el carrito
• generación opcional de cupones
• conversaciones con un asistente de compra AI
• panel de administración y analítica
• endpoints REST API y comandos CLI

Resumen

El módulo ayuda a recuperar carritos abandonados en Magento 2 detectando carritos inactivos, evaluando la intención de compra y enviando mensajes de e-mail con un enlace seguro para restaurar el carrito. En función de la configuración, puede funcionar en dos modos:

• modo heuristic, sin AI externa
• modo OpenAI, con análisis AI, generación de contenido de e-mails y conversaciones con el asistente

Flujo de funcionamiento habitual:

1. El cliente añade productos al carrito.
2. El cliente abandona la tienda sin realizar el pedido.
3. Una vez transcurrido el tiempo de inactividad configurado, el carrito se marca como abandonado.
4. El módulo asigna un scoring al carrito.
5. Si la puntuación es suficientemente alta, se envía un e-mail de recuperación.
6. El e-mail puede incluir un cupón de descuento y un enlace a la página del asistente AI.
7. Si el cliente vuelve y realiza el pedido, el carrito se marca como recuperado.

Requisitos

Antes de la instalación, asegúrate de que la tienda cumple los siguientes requisitos:

• Magento 2 con acceso a CLI
• cron de Magento funcionando correctamente
• envío de e-mails transaccionales configurado en Magento
• HTTPS activado en el storefront
• si se utiliza el modo AI: cuenta de OpenAI API con facturación activa y clave API

Recomendaciones operativas:

• modo de producción para la tienda live
• plantilla de e-mail probada y remitente correctamente configurado
• política de privacidad que contemple el uso de servicios AI, si el modo OpenAI está activado

Instalación

* = en producción utiliza la opción --keep-generated

Tipo: Composer

1. Añade el repositorio Composer a la configuración:

   

   Recibirás los datos de acceso al repositorio Composer, es decir, el e-mail del cliente y el token de licencia, por e-mail después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por el e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

   composer config repositories.kowal composer https://repo.kowal.store

2. Configura el acceso al repositorio Composer de Kowal:

   

   composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

3. Instala el módulo mediante Composer:

   

   composer require kowal/module-ai-abandoned-cart

A continuación, ejecuta:

bin/magento module:enable Kowal_AiAbandonedCartbin/magento setup:upgradebin/magento setup:di:compilebin/magento cache:flush

Checklist posterior a la instalación

Después de la instalación, comprueba:

• si el módulo está activado en Magento
• si el esquema de base de datos se ha instalado mediante setup:upgrade
• si el cron de Magento funciona correctamente
• si la tienda envía e-mails transaccionales
• si el storefront utiliza direcciones HTTPS correctas

Comandos de verificación útiles:

bin/magento module:status Kowal_AiAbandonedCartbin/magento cron:runbin/magento cache:flush

Configuración

Magento Admin:

Stores -> Configuration -> Kowal -> AI Abandoned Cart

Páginas administrativas:

Marketing -> AI Abandoned Cart

Campos de configuración

Ajustes más importantes:

• Enable Module Activa o desactiva todo el módulo.

• Cart Inactivity Threshold (minutes) Define después de cuántos minutos de inactividad un carrito activo debe considerarse abandonado.

• AI Provider Valores disponibles:

  • Heuristic Fallback
  • OpenAI

• OpenAI API Key Obligatorio solo cuando AI Provider está configurado como OpenAI.

• Minimum Intent Score Solo los carritos con una puntuación igual o superior a este valor cumplen los requisitos para el envío de un e-mail de recuperación.

• Enable Dynamic Coupons Activa la generación de cupones de un solo uso para carritos abandonados seleccionados.

• Maximum Coupon Discount Define el límite superior del descuento porcentual generado automáticamente.

• Maximum Failed Email Attempts Define cuántos intentos de envío fallidos se permiten antes de que el módulo deje de reintentar el envío.

• Email Address for Message Copies Destinatario BCC opcional para los mensajes de recuperación.

• Enable AI Assistant Link Si la opción está activada, el e-mail de recuperación incluirá un enlace seguro a la página del asistente AI.

• Conversation Expiration Time (minutes) Define durante cuánto tiempo sigue siendo válido el enlace al asistente AI.

• Batch Size Define cuántos carritos se procesan en una sola ejecución de detección, scoring y envío de e-mails.

• Cart Analysis Prompt Se utiliza cuando el scoring AI está activo.

• Email Generation Prompt Se utiliza para generar el contenido de los e-mails en modo AI.

• Conversation Prompt Lo utiliza el asistente AI durante la conversación con el cliente.

Configuración inicial recomendada

Para empezar, un conjunto seguro de ajustes es:

• Enable Module: Yes
• Cart Inactivity Threshold (minutes): 30
• AI Provider: Heuristic Fallback o OpenAI
• Minimum Intent Score: 0.45
• Enable Dynamic Coupons: Yes
• Maximum Coupon Discount: 5
• Maximum Failed Email Attempts: 3
• Enable AI Assistant Link: Yes
• Conversation Expiration Time (minutes): 1440
• Batch Size: 100

Modo Heuristic vs modo OpenAI

Modo Heuristic

Utiliza este modo si quieres empezar sin integración con una AI externa.

En este modo, el módulo:

• detecta carritos abandonados
• calcula el intent score en función de reglas de negocio integradas
• envía e-mails de recuperación
• puede generar cupones
• puede seguir proporcionando la página del asistente, pero las respuestas se basarán en la lógica integrada en lugar de en OpenAI

Modo OpenAI

Utiliza este modo si buscas una mayor personalización.

En este modo, el módulo también puede:

• analizar el contexto del carrito utilizando OpenAI
• generar contenido de e-mails más personalizado
• gestionar conversaciones con el asistente AI sobre los productos del carrito
• utilizar descripciones de productos, productos relacionados, up-sell y cross-sell en las respuestas

Configuración de OpenAI

Para activar el modo OpenAI:

1. Crea una clave API en la cuenta de OpenAI Platform.
2. En Magento Admin, ve a Stores -> Configuration -> Kowal -> AI Abandoned Cart.
3. Configura AI Provider como OpenAI.
4. Pega la clave en el campo OpenAI API Key.
5. Guarda la configuración.
6. Limpia la cache de Magento.

Información importante:

• las suscripciones de ChatGPT y la facturación de API son elementos separados
• el uso de API se factura de forma independiente por OpenAI
• en modo AI, el prompt y el contexto del carrito se envían a OpenAI

Tareas cron

El módulo utiliza los crons de Magento para el procesamiento automático.

Tareas cron configuradas:

• kowal_ai_abandoned_cart_detect
• kowal_ai_abandoned_cart_score
• kowal_ai_abandoned_cart_email

Su funcionamiento:

• detect: busca carritos inactivos que cumplen los requisitos para considerarse abandonados
• score: calcula el intent score y el reason code
• email: envía e-mails de recuperación y guarda logs

Si el cron de Magento no funciona, el módulo no procesará los carritos automáticamente.

Primera prueba después de la configuración

Tras la instalación y la configuración, realiza una prueba end-to-end completa:

1. Abre el storefront como cliente no registrado.
2. Añade uno o varios productos al carrito.
3. Inicia el checkout e introduce el e-mail.
4. Abandona el checkout sin realizar el pedido.
5. Espera a que transcurra el umbral de inactividad configurado.
6. Ejecuta el cron o los comandos CLI manualmente.
7. Confirma que el carrito aparece en el panel de administración.
8. Confirma que el e-mail de recuperación se ha enviado.
9. Abre el enlace de restauración del carrito desde el mensaje.
10. Si la opción está activada, abre el enlace al asistente AI y envía un mensaje de prueba.

Secuencia CLI manual:

bin/magento kowal:ai:cart:detectbin/magento kowal:ai:cart:scorebin/magento kowal:ai:cart:send-emails

Páginas administrativas

El módulo añade páginas administrativas dedicadas en:

Marketing -> AI Abandoned Cart

Secciones disponibles:

• Dashboard Resumen de carritos detectados y recuperados.

• Recovery Analytics Estadísticas de eficacia de recuperación y métricas operativas.

• Conversations Historial de conversaciones con el asistente AI vinculadas a carritos abandonados.

• Email Logs Registro de mensajes de recuperación enviados y fallidos.

Estas páginas son especialmente útiles durante la implementación, ya que permiten comprobar si la detección, el scoring, el envío de e-mails y el seguimiento de carritos recuperados funcionan correctamente.

Contenido de los e-mails y experiencia del cliente

Cada e-mail de recuperación puede incluir:

• asunto personalizado
• contenido propio del mensaje
• resumen de los productos del carrito
• valor del carrito
• enlace seguro para restaurar el carrito
• cupón de descuento de un solo uso opcional
• enlace opcional al asistente AI

Recorrido del cliente:

1. El cliente recibe un e-mail.
2. El cliente hace clic en el enlace de restauración y vuelve al carrito guardado.
3. El cliente puede abrir opcionalmente la página del asistente desde el mensaje.
4. El asistente puede responder preguntas sobre productos, comparar opciones y dirigir al cliente de vuelta al checkout.

Cómo funcionan los cupones

Si los cupones dinámicos están activados, el módulo puede generar un cupón cuando:

• el valor del carrito es suficientemente alto
• el intent score sugiere que un descuento puede ayudar
• el descuento calculado no supera el máximo configurado

Reglas integradas actuales:

• los carritos por debajo de 100 unidades de la moneda de la tienda no reciben cupón
• los carritos con un intent score alto no reciben cupón
• los carritos con una intención más baja pueden recibir un descuento, normalmente del 3% o 5%, limitado por la configuración

Los cupones generados son:

• de un solo uso
• limitados por cliente
• vinculados a una regla de carrito compartida de Magento para el nivel de descuento y la tienda correspondientes

CLI

Puedes ejecutar el módulo manualmente desde CLI, especialmente durante pruebas y diagnóstico.

bin/magento kowal:ai:cart:detectbin/magento kowal:ai:cart:scorebin/magento kowal:ai:cart:send-emails

Significado de los comandos:

• kowal:ai:cart:detect Detecta carritos abandonados.

• kowal:ai:cart:score Asigna scoring y reason code a los carritos.

• kowal:ai:cart:send-emails Envía mensajes de recuperación para los carritos que cumplen los requisitos.

Seguridad

Los enlaces para restaurar el carrito y acceder al asistente utilizan tokens firmados.

El payload del token contiene:

• quote_id
• email
• store_id
• expires_at

El token se valida mediante:

1. verificación de la firma
2. comprobación de la fecha de expiración
3. verificación de la propiedad del carrito

Gracias a ello, el cliente recibe un enlace seguro asociado a un carrito concreto y limitado en el tiempo.

Resolución de problemas

Los carritos no se detectan

Comprueba:

• si el quote sigue activo
• si el carrito contiene productos
• si el quote no tiene un pedido finalizado asociado
• si se ha capturado el e-mail del cliente
• si ha transcurrido el umbral de inactividad
• si el cron de Magento funciona

Los carritos se detectan, pero los e-mails no se envían

Comprueba:

• si Enable Module está activado
• si Minimum Intent Score no está configurado demasiado alto
• si el envío de e-mails funciona en Magento
• si no se ha alcanzado el límite de Maximum Failed Email Attempts
• si el e-mail asignado al carrito es correcto

El modo OpenAI está activado, pero no se utiliza la puntuación AI

Comprueba:

• si AI Provider está configurado como OpenAI
• si OpenAI API Key está correctamente completado
• si el servidor permite conexiones salientes a la API de OpenAI
• si la cuenta de OpenAI tiene facturación activa

Si la llamada a OpenAI falla, el módulo cambiará al comportamiento heurístico integrado.

El enlace al asistente AI se abre, pero las respuestas son generales

Comprueba:

• si el modo OpenAI está activo
• si el prompt de conversación está correctamente configurado
• si el enlace sigue siendo válido y no ha expirado

Notas para el uso en producción

Antes de ponerlo en marcha en producción, conviene:

• revisar el contenido de los e-mails y el branding
• probar la política de cupones con reglas de negocio reales
• verificar los requisitos de privacidad y compliance
• probar los prompts AI con el catálogo y el tono de comunicación de la tienda
• monitorizar los primeros días de funcionamiento en Dashboard, Conversations y Email Logs

Información necesaria al enviar una solicitud de soporte

Al informar de un problema, prepara:

• versión de Magento
• versión de PHP
• modo de la tienda: developer o production
• información sobre si el cron funciona
• información sobre si el problema se produce en modo heuristic o OpenAI
• quote ID de ejemplo o e-mail del cliente afectado por el problema
• entradas correspondientes de los logs de excepciones o logs del sistema de Magento