# DF Samples: pedido de muestras de producto (PrestaShop 8 y 9)
> Presentación DF Samples añade un botón «Pedir una muestra» en sus fichas de producto. La muestra puede ser gratuita o costar unos euros, para el producto o para la combinación…
- Página:
- Idioma: es
- Actualizado el: 2026-10-13
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dfsamples/index.md), [en](https://www.datafirefly.com/en/documentation/dfsamples/index.md), [de](https://www.datafirefly.com/de/documentation/dfsamples/index.md), [it](https://www.datafirefly.com/it/documentation/dfsamples/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsamples/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsamples/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsamples/index.md)
- Índice:
## Presentación
DF Samples añade un botón «Pedir una muestra» en sus fichas de producto. La muestra puede ser gratuita o costar unos euros, para el producto o para la combinación elegida por el cliente. El módulo crea un producto muestra oculto para cada producto inscrito, bloquea la cantidad en 1, aplica límites por cliente sobre el contenido del carrito, mide la conversión de muestra a compra y envía un email de seguimiento con un vale de descuento opcional.
El módulo es compatible con PrestaShop 8.0 a 9.x, multitienda y multiidioma, y no usa ningún override del núcleo. Esta documentación corresponde a la versión 1.1.0.
## Instalación
1. En el back-office, vaya a **Módulos > Gestor de módulos**.
2. Haga clic en **Subir un módulo** y suelte el archivo `dfsamples.zip`.
3. Abra **Catálogo > Muestras (DF)**: en esta página están la lista de productos, el panel y los ajustes.
Durante la instalación, el módulo crea:
- tres tablas: `dfsamples_product`, `dfsamples_order` y `dfsamples_cart`;
- una categoría **Muestras** desactivada, bajo Inicio, accesible a todos los grupos de clientes, que recibirá los productos muestra;
- sus ajustes por defecto y un token de seguridad para la tarea cron;
- la pestaña de administración **Catálogo > Muestras (DF)**;
- una copia de la plantilla de email inglesa para cada idioma instalado que no tenga una.
Se registra en 12 hooks, entre ellos displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder y actionOrderStatusPostUpdate.
## Actualizar desde la versión 1.0.0
Suba el nuevo ZIP sobre el anterior desde el gestor de módulos. El script de actualización:
- añade la tabla `dfsamples_cart` y las nuevas columnas;
- registra los nuevos hooks;
- crea la categoría Muestras y mueve a ella sus productos muestra existentes;
- les cambia el nombre al nuevo formato y añade las imágenes que faltan (en PrestaShop 9, la versión 1.0.0 no copiaba la imagen);
- conserva sus productos inscritos, sus estadísticas y su historial de seguimientos.
Si un paso falla, el botón **Resincronizar las muestras**, en la parte superior de la página del módulo, vuelve a sincronizar todos los productos muestra.
## Añadir un producto al programa de muestras
1. Abra **Catálogo > Muestras (DF)** y haga clic en **Añadir un producto**.
2. Busque el producto por nombre o referencia y selecciónelo. Los productos ya inscritos y los productos muestra quedan excluidos de los resultados.
3. Introduzca el **Precio de la muestra (IVA incl.)**. Introduzca 0,00 para una muestra gratuita.
4. Defina el **Máximo por cliente** de este producto en la ventana deslizante (0 = ilimitado).
5. Active **Muestra por variante** si el producto tiene combinaciones y el cliente debe elegir la suya (ver más abajo).
6. Guarde.
### Qué hace el módulo al guardar
El módulo crea un producto muestra oculto, o actualiza el existente:
- nombre traducido con el formato «Muestra: Nombre del producto» (Échantillon, Sample, Muster, Campione en los demás idiomas);
- referencia con el formato SMPL seguido del ID del producto de origen;
- precio sin IVA calculado a partir del precio introducido y de la regla de impuestos del producto de origen;
- imagen de portada del producto de origen copiada en todos los formatos de imagen;
- categoría por defecto: la categoría Muestras;
- visibilidad «en ninguna parte»: el producto no aparece ni en los listados ni en la búsqueda;
- pedidos permitidos sin stock, para no bloquear nunca una solicitud;
- peso tomado del ajuste global, usado por los transportistas.
Si después cambia el precio, la opción de variante, el peso global o el estado activo, el producto muestra se vuelve a sincronizar. Si se eliminó manualmente del catálogo, se vuelve a crear al guardar de nuevo.
## Muestra por variante
Con la opción **Muestra por variante**, el cliente elige su combinación en la ficha de producto como en una compra normal y luego hace clic en el botón, que pasa a ser «Pedir una muestra de esta variante».
- La combinación se guarda en la línea de muestra, por ejemplo «Formato: A4, Papel: Estucado 300 g». Se muestra en un campo «Variante» del carrito, el pedido, la factura y el email de seguimiento.
- Cada combinación ocupa su propia línea. La misma combinación no puede añadirse dos veces.
- El máximo por cliente del producto se cuenta por combinación.
- El precio de la muestra es el mismo para todas las combinaciones del producto.
El producto muestra sigue siendo un producto simple, sin combinaciones ni stock propio. La combinación es un texto de personalización añadido por el módulo, de modo que sus combinaciones no se duplican.
## Ajustes
Los ajustes están debajo de la lista de productos, en la página **Catálogo > Muestras (DF)**.
### Ajustes generales
- **Posición del botón**: debajo del botón de añadir al carrito (displayProductActions), en el bloque de información adicional (displayProductAdditionalInfo), o solo ubicación personalizada (displayDfSamplesButton, ver la sección siguiente).
- **Precio de muestra por defecto (IVA incl.)**: valor propuesto al añadir una muestra.
- **Peso de la muestra**: en kilogramos, aplicado a todos los productos muestra, usado para los gastos de envío.
- **Cuenta de cliente obligatoria**: activado por defecto. Los límites por cliente solo pueden aplicarse de forma fiable a clientes identificados.
- **Descuentos de grupo de clientes en las muestras**: aplicar (comportamiento por defecto de PrestaShop) o no aplicar. Ver «Precios y descuentos de grupo».
- **Categoría de las muestras**: categoría por defecto de todos los productos muestra. Manténgala desactivada. Si elige otra, las muestras existentes se mueven a ella.
- **Redirigir las páginas de muestra**: activado por defecto. Un visitante que llega a la página de un producto muestra es redirigido con un 301 al producto de origen.
- **Conversión contabilizada en**: la compra del producto de la muestra únicamente, o cualquier compra posterior.
### Límites
- **Máximo de muestras por carrito**: 0 = ilimitado.
- **Máximo de muestras por cliente y ventana**: todos los productos muestra juntos, 0 = ilimitado.
- **Ventana deslizante**: en días, 30 por defecto. Con 0, los límites por cliente se aplican a todos los pedidos anteriores, sin límite de tiempo.
### Seguimiento automático
- **Activar los emails de seguimiento**.
- **Plazo tras el pedido de muestra**: en días, 14 por defecto.
- **Solo clientes suscritos al boletín**: actívelo si su base legal para los emails comerciales es el consentimiento.
- **Incluir un vale de descuento**: se genera un vale nominativo de un solo uso para cada seguimiento.
- **Importe del vale**: porcentaje, 10 por defecto.
- **Validez del vale**: en días, 30 por defecto.
La URL de la tarea cron se muestra en esta sección y en el panel.
## Mostrar el botón con Creative Elements o un tema personalizado
Cuando la ficha de producto está construida con un page builder, los hooks nativos no siempre se muestran, o no donde usted quiere. El módulo ofrece un hook propio, `displayDfSamplesButton`.
1. En los ajustes, elija **Posición del botón: Solo ubicación personalizada (displayDfSamplesButton)**. El botón deja entonces de añadirse a los hooks nativos, lo que evita que aparezca dos veces.
2. Con **Creative Elements**: en la plantilla de la ficha de producto, añada el widget **Module** donde quiera el botón y elija el módulo DF Samples y el hook `displayDfSamplesButton`.
3. En un **tema personalizado**: añada `{hook h='displayDfSamplesButton'}` a la plantilla de la ficha de producto, por ejemplo `templates/catalog/product.tpl`.
Esté donde esté, el botón sigue la combinación seleccionada y se actualiza cuando el cliente la cambia.
## Precios y descuentos de grupo
El precio de la muestra es independiente del producto de origen: los precios por cantidad, los precios específicos y la cantidad mínima del producto de origen no se aplican. Solo una regla de precios de catálogo dirigida a todos los productos sin distinción se aplicaría también a las muestras.
El descuento de un grupo de clientes (**Clientes > Grupos**, por ejemplo -15 % para distribuidores) se aplica por defecto a todos los productos, muestras incluidas. Con **No aplicar: las muestras mantienen su precio**, el módulo excluye los productos muestra del descuento de cada grupo: sus distribuidores pagan el precio fijado para la muestra y el descuento sigue aplicándose al resto del catálogo. Los grupos creados más adelante se tienen en cuenta automáticamente.
El botón muestra el precio que pagará el cliente conectado, con descuento de grupo e IVA incluidos.
## Límites y control del carrito
Las reglas se comprueban cada vez que se guarda el carrito, no solo al hacer clic en el botón. Añadir con los botones + y - de la página del carrito, con una URL directa, con «Volver a pedir» o mediante la fusión de carritos al iniciar sesión pasa por los mismos controles:
1. se eliminan las líneas de muestras desactivadas;
2. se eliminan los duplicados (misma muestra, o misma combinación en modo variante);
3. la cantidad de cada línea vuelve a 1;
4. se aplica el máximo por carrito;
5. se aplican el máximo por producto y el máximo global por cliente en la ventana deslizante.
Cuando hay que quitar una línea, se quita la más reciente. El cliente ve un mensaje en la página del carrito o del pedido. Los pedidos cancelados, reembolsados o con error de pago no cuentan para los límites. Los carritos creados por un empleado en el back-office no están sujetos a los límites.
## Configurar la tarea cron
Los seguimientos se envían mediante una tarea cron. Programe cada hora la URL que aparece en los ajustes. Ejemplo de crontab:
```
0 * * * * wget -q -O /dev/null "https://su-tienda.com/module/dfsamples/cron?token=SU_TOKEN"
```
Cada ejecución procesa hasta 50 pedidos y devuelve un resumen JSON: `processed`, `sent`, `skipped`, `waiting` y `retry`.
### Reglas que aplica la tarea cron
- Un solo email por pedido, aunque contenga varias muestras. Enumera los productos probados e incluye como máximo un vale.
- Solo se tienen en cuenta las muestras no convertidas y sin seguimiento, una vez transcurrido el plazo.
- El pedido de muestra debe haber alcanzado un estado pagado, enviado o entregado. Un pedido aún pendiente de pago se revisa más tarde y se descarta si sigue sin pagarse 60 días después de la fecha prevista del seguimiento.
- Los pedidos cancelados, reembolsados o con error de pago se ignoran.
- Una muestra cuyo producto se compró en el mismo pedido no recibe seguimiento.
- Con la opción de boletín activa, los clientes no suscritos no reciben seguimiento.
- Si el envío falla, el módulo lo reintenta en las ejecuciones siguientes, hasta tres veces y con al menos seis horas de intervalo. El vale generado para un email que no salió se elimina.
- Dos ejecuciones simultáneas no pueden enviar el mismo email: cada pedido se reserva antes de procesarlo.
## Seguimiento de conversión
Al validar un pedido que contiene una muestra, el módulo registra el cliente, su email, el producto de origen, la combinación, el idioma y la tienda.
Cuando ese cliente hace un pedido posterior, las muestras correspondientes se marcan como convertidas:
- en modo **producto** (por defecto): si el pedido contiene el producto del que recibió la muestra;
- en modo **cualquier compra**: en cuanto el pedido contiene un producto real.
La conversión solo se cuenta cuando el pedido de compra alcanza un estado validado (pago aceptado, por ejemplo). Un pedido pagado por transferencia se cuenta, por tanto, al recibir el pago. Una compra en el mismo pedido que la muestra no es una conversión.
## Panel
El panel situado sobre la lista de productos muestra:
- **Muestras pedidas**: número de líneas de muestra registradas;
- **Conversiones**: número de muestras seguidas de una compra, y tasa de conversión;
- **Facturación de las conversiones**: importe total con IVA de los pedidos de conversión, convertido a la moneda por defecto;
- **Seguimientos pendientes**.
La lista de productos muestra también, por producto, el número de muestras pedidas, el número de conversiones y si el modo variante está activo.
## Emails de seguimiento
Las plantillas están en la carpeta `mails` del módulo, en francés, inglés, español, alemán e italiano, en versión HTML y texto (`dfsamples_followup`). Para los demás idiomas instalados, la plantilla inglesa se copia durante la instalación: tradúzcala en la carpeta `mails/` seguida del código del idioma, por ejemplo `mails/pt/`.
Variables disponibles:
- `{firstname}` y `{lastname}`;
- `{product_name}`: el producto o productos probados, separados por comas;
- `{product_link}`: enlace a la ficha del primer producto;
- `{voucher_block}`: vale con formato para la versión HTML, vacío si el vale está desactivado;
- `{voucher_text}`: el mismo contenido para la versión texto;
- `{shop_name}`.
## Vales de descuento
Con la opción activa, cada seguimiento crea una regla de carrito de PrestaShop:
- código con el formato SMPL seguido de ocho caracteres aleatorios;
- reservado al destinatario, de un solo uso;
- descuento en porcentaje, validez configurable.
Los vales aparecen en **Catálogo > Descuentos > Reglas del carrito**.
## Catálogo, sitemap y feeds de productos
Los productos muestra tienen la visibilidad «en ninguna parte» y están en la categoría Muestras desactivada. No aparecen en los listados, la búsqueda ni los bloques destacados, y su página redirige al producto de origen. La mayoría de los módulos de sitemap y de feeds ignoran estos productos. Si el suyo los incluye, excluya la categoría Muestras o las referencias que empiezan por SMPL en sus ajustes.
## Compatibilidad con el proceso de compra
El módulo no interviene en el proceso de compra: una muestra es una línea de producto normal. Funciona con el checkout nativo y con los checkouts en una página que reutilizan los pasos nativos de PrestaShop. El mensaje de retirada de una muestra se muestra en las páginas del carrito y del pedido.
## Desinstalación
La desinstalación elimina las tablas, los ajustes y la pestaña del módulo. Los productos muestra se **desactivan, no se eliminan**, y la categoría Muestras se conserva, para que el historial de pedidos siga siendo coherente. Una reinstalación reutiliza esta categoría. Puede eliminar estos productos y la categoría manualmente si ya no los necesita.
## Solución de problemas
### El botón no aparece en la ficha de producto
Compruebe que el producto está inscrito y activo en **Catálogo > Muestras (DF)**. Después cambie la posición del botón: algunos temas no muestran displayProductActions. Con un page builder, use el hook displayDfSamplesButton.
### Aparece un mensaje en lugar del botón
«Ha alcanzado el límite de muestras para este producto»: el cliente alcanzó su máximo en la ventana deslizante. «Su carrito ya contiene el máximo de N muestras por pedido»: se alcanzó el máximo por carrito. Ajuste los límites si es necesario.
### Los productos muestra no tienen imagen
Ocurría con las muestras creadas por la versión 1.0.0 en PrestaShop 9. Haga clic en **Resincronizar las muestras**: se añaden las imágenes que faltan.
### El precio mostrado no es el esperado
El precio se introduce con IVA y se convierte según la regla de impuestos del producto de origen. Para un cliente de un grupo con descuento, revise el ajuste «Descuentos de grupo de clientes en las muestras». Una regla de precios de catálogo global también se aplica a las muestras.
### Los seguimientos no se envían
Abra la URL de la tarea cron en un navegador y lea el resumen JSON. `enabled: false` significa que los seguimientos están desactivados. `waiting` cuenta los pedidos de muestra aún no pagados. Revise también el plazo, la opción de boletín y la configuración de email de la tienda (**Parámetros avanzados > Email**).
### Una muestra desaparece del carrito
Es el control del carrito: duplicado, máximo por carrito o límite del cliente alcanzado. El cliente ve un mensaje en la página del carrito.