AI Returns Predictor — Guía completa
Instalar, configurar y explotar el scoring del riesgo de devolución antes del envío para PrestaShop 8 y 9.
AI Returns Predictor analiza cada pedido en el momento de su validación y le asigna una puntuación de riesgo de devolución de 0 a 100, clasificada en tres niveles (Bajo, Medio, Alto). La puntuación aparece directamente en la ficha del pedido, con el desglose de factores, y tu equipo de logística recibe un aviso por email antes del envío cuando un pedido supera el umbral de riesgo alto. Esta guía cubre la instalación, la configuración, el funcionamiento del motor de scoring y la capa de IA opcional.
Instalación
- Descarga el archivo
dfreturnspredictor.zipdesde tu cuenta DataFirefly. - Back office de PrestaShop → Módulos → Subir un módulo → envía el ZIP.
- Al instalarse, el módulo crea su tabla
df_return_risk, registra sus hooks y añade la pestaña Envío → Returns Predictor.
Compatible con PrestaShop 8.0 a 9.x, en PHP 7.4 a 8.3. Sin override de plantilla, sin dependencia de Composer. Compatible con multitienda y multidioma.
Configuración general
Ve a Módulos → AI Returns Predictor → Configurar.
Umbrales de riesgo
Dos umbrales determinan el nivel asignado a cada pedido a partir de su puntuación:
- Umbral Medio (por defecto 40): puntuación a partir de la cual un pedido pasa a riesgo Medio.
- Umbral Alto (por defecto 70): puntuación a partir de la cual un pedido pasa a riesgo Alto y dispara el aviso logístico.
Por debajo del umbral Medio, el pedido se clasifica como Bajo. Los umbrales deben cumplir 1 ≤ Medio < Alto ≤ 100.
Categorías de alta devolución
Indica la lista de identificadores de categorías conocidas por sus devoluciones frecuentes (moda, textil, calzado…), separados por comas. Los productos que pertenecen a estas categorías aumentan la puntuación del pedido.
Aviso logístico
- Email de aviso logístico: dirección notificada cuando un pedido supera el umbral de riesgo alto. Deja el campo vacío para desactivar los avisos por email.
El aviso se envía una sola vez por pedido, en la primera detección de riesgo alto. Los recálculos posteriores no envían un nuevo email.
Capa de IA (opcional)
El módulo funciona sin IA gracias a su motor heurístico. Puedes activar una capa de IA opcional para afinar la puntuación y generar una explicación breve.
- Activar el afinado por IA: si está desactivado, no se realiza ninguna llamada externa.
- Clave API de Mistral: almacenada en el servidor, nunca expuesta al front office.
- Modelo de Mistral: por ejemplo
mistral-small-latest.
Ante cualquier error de red, caída de la API o timeout (8 s), el módulo recurre automáticamente a la puntuación heurística. El scoring nunca bloquea la preparación de los pedidos.
Cómo se calcula la puntuación
El motor heurístico combina seis factores explicables, cada uno aportando un número de puntos limitado. El total está acotado entre 0 y 100.
- Historial de devoluciones del cliente (0–30): relación entre el número de devoluciones pasadas y los pedidos válidos del cliente.
- Bracketing de tallas / variantes (0–25): mismo producto pedido en varias variaciones (tallas, colores), señal de intención de prueba.
- Valor del carrito (0–15): importe del pedido respecto al carrito medio de la tienda.
- Categorías de alta devolución (0–20): presencia de productos en las categorías que has declarado.
- Cliente nuevo (0–8): sin historial de compra utilizable.
- Tamaño del carrito (0–10): número de artículos distintos en el pedido.
Cada factor muestra su contribución en puntos en la ficha del pedido, lo que hace la puntuación totalmente transparente — sin caja negra.
El panel de riesgo en el pedido
En cada ficha de pedido (hook displayAdminOrderSide), un panel «Riesgo de devolución» muestra:
- la puntuación sobre 100 y el nivel con código de color (Bajo / Medio / Alto);
- el desglose de los factores contribuyentes con sus puntos;
- la explicación de la IA, cuando corresponda;
- un botón Recalcular que relanza el scoring vía AJAX sin recargar la página.
La puntuación se calcula automáticamente al validar el pedido (hook actionValidateOrder) y se actualiza en los cambios de estado (hook actionOrderStatusPostUpdate).
El panel de logística
La pestaña Envío → Returns Predictor lista todos los pedidos puntuados, ordenados por puntuación descendente. Encontrarás la referencia, el cliente, el estado, la puntuación, el nivel y el indicador de aviso. Filtra por nivel para aislar los pedidos de riesgo alto antes de preparar los paquetes. La acción «Ver» abre directamente la ficha del pedido correspondiente.
El aviso por email
Cuando un pedido supera el umbral de riesgo alto en su creación, se envía un email resumen a la dirección logística configurada: referencia del pedido, puntuación, nivel, cliente, factores contribuyentes y posible nota de la IA. Las plantillas de email se proporcionan en francés e inglés, y el envío tiene en cuenta el idioma del cliente y la tienda de origen del pedido.
El módulo informa y avisa, pero nunca cambia el estado del pedido ni impide el envío. La decisión final sigue siendo humana.
Compatibilidad y notas técnicas
- PrestaShop 8.0 a 9.x, multitienda y multidioma.
- Controlador de administración legacy (sin controlador Symfony) para la compatibilidad PS8/PS9.
- Endpoint AJAX de back office mediante el 4.º argumento de
getAdminLink(); JSON renderizado por un método dedicado. - Tabla
df_return_risk: un registro por pedido, con puntuación, nivel, factores (JSON) e indicador de aviso. - Capa de IA opcional: solo se envían a Mistral los datos necesarios para el cálculo; repliegue automático a la heurística.
FAQ y resolución de problemas
El panel de riesgo no aparece en la ficha del pedido. Comprueba que el módulo está enganchado al hook displayAdminOrderSide y que el pedido se creó después de la instalación. Usa el botón «Recalcular» para forzar el scoring.
No se recibe ningún aviso por email. Comprueba que la dirección de aviso está rellenada y es válida, y que el pedido supera realmente el umbral Alto. El aviso se envía una sola vez por pedido.
La IA no devuelve ninguna explicación. Comprueba la clave API y el nombre del modelo de Mistral. El módulo recurre de todos modos a la puntuación heurística; no se pierde ninguna puntuación.
¿Se consideran de riesgo todos los clientes nuevos? No. La falta de historial solo añade un pequeño incremento; la puntuación depende sobre todo de los demás factores (bracketing, categorías, valor del carrito).