DataFirefly Affiliate Program: programa de afiliados para PrestaShop

Instalación

Instala el módulo desde Módulos > Gestor de módulos > Subir un módulo enviando el archivo ZIP, o copia la carpeta dfaffiliate en el directorio /modules/ de tu tienda y haz clic en Instalar.

Al instalarse, el módulo crea sus tablas, guarda sus ajustes por defecto y añade un menú Afiliación en la sección Vender con cinco entradas: Afiliados, Comisiones, Extractos y pagos, Reglas de comisión y Ajustes. El botón Configurar del gestor de módulos abre la página de ajustes, que empieza con un resumen del programa.

Para pasar de la versión 1.0.0 a la 1.1.0, basta con subir el nuevo ZIP: el script de actualización añade los nuevos ajustes y hooks sin tocar los afiliados, comisiones ni extractos existentes.

Primeros ajustes

Revisa como mínimo estos puntos antes de invitar a tus primeros afiliados:

• Valor de comisión por defecto: 10 % de los productos sin IVA al instalar, o un importe fijo por pedido.
• Vida útil de la cookie: 30 días por defecto, plazo entre el clic y el pedido.
• Aprobar la comisión en y Rechazar la comisión en: los estados de pedido que confirman el pago y los que anulan (cancelado, reembolsado, error de pago).
• Periodo de retención: 30 días por defecto. Una comisión aprobada solo entra en un extracto tras este plazo, para cubrir las devoluciones.
• Pago mínimo: por debajo, el saldo se aplaza al mes siguiente.
• Razón social, IBAN y BIC de la empresa: imprescindibles para generar el fichero de transferencia SEPA.

Seguimiento y atribución

Los enlaces de seguimiento

Cada afiliado tiene un código. Dos tipos de enlaces lo transportan:

• el parámetro de seguimiento, añadido a cualquier dirección de la tienda: ?aff=CODE. El nombre del parámetro se cambia en los ajustes, por ejemplo ref;
• los enlaces cortos que el afiliado crea en su área a partir de la dirección de un producto, una categoría o cualquier página. Redirigen a la página elegida y cuentan clics y pedidos por enlace.

Con el clic, una cookie firmada (dfaff_ref) registra al afiliado. Su firma impide que un visitante la modifique. Los robots de indexación, los navegadores automatizados y los clics del propio afiliado no cuentan, y un mismo visitante solo se cuenta una vez cada 30 minutos. No se guarda ninguna dirección IP en claro.

Orden de atribución de un pedido

1. El código de descuento personal de un afiliado usado en el pedido, incluso sin clic.
2. El enlace o la cookie: el carrito se vincula al afiliado durante la visita, lo que cubre también los pagos que el banco confirma más tarde.
3. Un cliente ya captado por ese afiliado, si el ajuste Comisiones por clientes recurrentes es superior a 0 días.

El modelo de atribución decide qué ocurre cuando un visitante hace clic en los enlaces de dos afiliados: último clic (por defecto), gana el último afiliado visitado; primer clic, el primero conserva la venta hasta que caduca la cookie.

Protecciones

• Un afiliado no cobra comisión por sus propios pedidos, reconocidos por cuenta de cliente y por email.
• Solo clientes nuevos: solo el primer pedido de un cliente genera comisión.
• Importe mínimo de pedido: productos sin IVA tras descuentos, 0 para ningún mínimo.

Comisiones

Cálculo

La base es el importe de los productos sin IVA. Con Descontar los descuentos, los cupones del pedido se restan de la base; un cupón de envío gratis no la modifica. Los gastos de envío nunca se incluyen. El importe se convierte a la moneda por defecto de la tienda.

La tasa aplicada es, en este orden: la comisión específica del afiliado si la tiene; si no, la tasa del programa. En porcentaje, las reglas por producto y luego por categoría sustituyen la tasa línea a línea. En importe fijo se crea una sola comisión por pedido, y una sola cuando PrestaShop divide un carrito en varios pedidos por varios transportistas.

Reglas por categoría y por producto

La pestaña Reglas de comisión fija un porcentaje para una categoría o un producto, por ejemplo 3 % en electrónica y 15 % en accesorios. Una regla de producto prevalece sobre una de categoría. Para las categorías, el módulo mira primero la categoría por defecto del producto y luego la mejor de sus otras categorías. Una tasa de 0 excluye los productos de las comisiones. Las reglas solo se aplican a las comisiones en porcentaje.

Ciclo de vida

• Al hacerse el pedido, la comisión se crea Pendiente.
• Cuando el pedido alcanza un estado de aprobación, pasa a Aprobada y la fecha de aprobación inicia el periodo de retención.
• Cuando el pedido pasa a un estado de cancelación, queda Rechazada.
• Una factura rectificativa parcial reduce la comisión en proporción al importe de productos reembolsado.
• Si la comisión ya figura en un extracto o está pagada, el módulo ya no la modifica: crea un ajuste negativo que se descuenta del siguiente extracto, sin periodo de retención. Un segundo estado de cancelación en el mismo pedido no crea otra deducción.

Comisiones manuales

En la pestaña Comisiones, Añadir una comisión manual abona o carga a un afiliado (importe negativo para una deducción), con una nota visible en su área. Estas líneas siguen el mismo ciclo de extracto que las comisiones de pedido.

Afiliados

Solicitudes

La página pública del programa presenta tus condiciones (tasa, duración de la cookie, pago mínimo), tres pasos y unas preguntas frecuentes generadas a partir de tus ajustes. El texto de presentación se edita en los ajustes, en cada idioma. Si eliges una página CMS con las condiciones del programa, el candidato debe aceptarla.

El candidato debe haber iniciado sesión con una cuenta de cliente. Indica dónde publica, describe su audiencia y, opcionalmente, su empresa. Por defecto, cada solicitud espera tu aprobación y el email de notificación recibe un mensaje. Con Aprobar solicitudes automáticamente, la cuenta queda activa al instante.

Ficha del afiliado

La ficha muestra arriba un resumen (clics, pedidos, comisiones pendientes, adeudadas y pagadas) y el enlace de seguimiento para copiar, y después tres bloques:

• Identidad y canal: nombre, email, web, audiencia, estado y nota interna. Pasar el estado a Aprobado envía el email «Tu cuenta de afiliado está activa».
• Seguimiento y comisión: código de afiliado, comisión específica, duración propia de la cookie, código de descuento personal. Si el código aún no existe e indicas un porcentaje de descuento, la regla de carrito se crea automáticamente, limitada a un uso por cliente.
• Datos de pago: transferencia SEPA o PayPal, titular, IBAN, BIC, email de PayPal.

Puedes crear un afiliado sin cuenta de cliente: recibe sus extractos por email pero no tiene área en línea. Si una cuenta de cliente usa el mismo email, se vincula automáticamente.

Un afiliado con comisiones abiertas o un extracto sin pagar no se puede eliminar: suspéndelo o liquida antes su saldo.

Lo que ve el afiliado

• Mi cuenta: un bloque «Área de afiliado», o «Hazte afiliado» para un cliente que aún no lo es.
• Resumen: generador de enlaces, franja de cifras (clics, pedidos, conversión, pendiente, aprobado, pagado), gráfico de 30 días, condiciones y enlaces recientes.
• Mis enlaces: todos los enlaces cortos con clics, pedidos, copiar y eliminar.
• Comisiones: fecha, referencia de pedido enmascarada, origen, base, comisión, estado, filtro por estado y mes de pago previsto. No se muestra ningún dato de clientes.
• Extractos: un extracto por mes, consultable e imprimible en PDF.
• Datos de pago: elección de transferencia o PayPal, IBAN verificado con sus dígitos de control y mostrado enmascarado. Un punto y un aviso señalan los datos que faltan.
• Ficha de producto: un recuadro «Tu enlace de afiliado», visible solo para el afiliado conectado, da el enlace del producto y la tasa que gana con él.

Extractos y pagos

Creación de los extractos

Un extracto agrupa, para un afiliado y un mes, las comisiones aprobadas creadas antes del fin de mes cuyo periodo de retención ha terminado, además de los ajustes negativos. Si el total es inferior al pago mínimo, no se crea nada y el saldo se aplaza.

Dos formas de crear los extractos:

• Extractos y pagos > Crear los extractos mensuales: elige el mes, revisa los importes por afiliado y crea los extractos enviando los emails.
• La URL cron, visible en el resumen de los ajustes. Llámala una vez al día: entre el 1 y el 5 del mes crea los extractos del mes anterior. Añade &period=AAAA-MM para forzar un mes concreto. Está protegida por un token.

Pagar a los afiliados

En la lista de extractos, selecciona los que vas a pagar y usa la acción masiva que necesites:

• Exportar fichero de transferencia SEPA (XML): fichero pain.001.001.03 para importar en tu banco, para los afiliados pagados por transferencia. Requiere EUR como moneda por defecto y el IBAN de la empresa.
• Exportar fichero PayPal Payouts (CSV): para el envío masivo de PayPal, afiliados pagados por PayPal.
• Exportar para contabilidad (CSV): todos los extractos seleccionados, separados por punto y coma.

Las exportaciones de pago se rechazan, con un mensaje que nombra el extracto afectado, si un extracto seleccionado ya está pagado o si falta un IBAN o no es válido: un fichero incompleto dejaría a un afiliado sin cobrar, y un extracto pagado podría pagarse dos veces.

Una vez hecha la transferencia, marca los extractos como pagados, en bloque o desde el detalle de un extracto con la referencia y la fecha del pago. Las comisiones correspondientes pasan a Pagada.

Emails

El módulo envía cuatro emails, traducidos a 8 idiomas y enviados en el idioma del destinatario, importes incluidos:

• Nueva solicitud de afiliado, a la dirección de notificación.
• Tu cuenta de afiliado está activa, con el enlace al área de afiliado.
• Nueva venta, con la comisión, la base y la tasa, nunca los datos del cliente. Desactivable en los ajustes y por cada afiliado en sus datos de pago.
• Extracto disponible, con el importe y el enlace al extracto.

Las plantillas están en la carpeta mails/ del módulo y se personalizan como cualquier email de PrestaShop.

Back office

• Resumen (página de ajustes): afiliados activos, solicitudes por revisar, clics, pedidos y ventas de 30 días, comisiones pendientes, adeudadas y pagadas, mejores afiliados.
• Página de pedido: un recuadro indica el afiliado, la comisión, su estado y su origen.
• Exportaciones CSV de las listas de afiliados y comisiones, con importes en bruto listos para una hoja de cálculo.

RGPD y eliminación de cuentas

El módulo se registra en el módulo RGPD oficial de PrestaShop. La exportación de datos de un cliente incluye su perfil de afiliado y sus comisiones. El borrado anonimiza al afiliado (nombre, email, IBAN, web y audiencia vaciados, enlaces y clics eliminados) y conserva las comisiones y extractos para la contabilidad.

Cuando un empleado elimina una cuenta de cliente, el afiliado vinculado se conserva sin cuenta en línea y sus datos de pago permanecen.

Solución de problemas

No se cuenta ningún clic

Prueba en una ventana de navegación privada, sin haber iniciado sesión con la cuenta del afiliado: sus propios clics se ignoran. Los navegadores automatizados se filtran como robots. Si tu tienda usa una caché de página completa, una página servida desde la caché no ejecuta PHP y el parámetro ?aff= no se ve: usa los enlaces cortos, que siempre pasan por PrestaShop, o excluye el parámetro de la caché.

Una comisión sigue pendiente

Comprueba que el estado actual del pedido está marcado en Aprobar la comisión en. Si el estado lo cambió un empleado cuyo perfil no tiene el permiso Ver sobre el módulo (Parámetros avanzados > Equipo > Permisos), PrestaShop no ejecutó el módulo: vuelve a poner el pedido en ese estado con una cuenta de administrador.

El generador de enlaces rechaza una dirección

El generador solo acepta direcciones de tu tienda. Pega la dirección completa tal como aparece en el navegador, en el dominio de la tienda.

La exportación SEPA se rechaza

Lee el mensaje mostrado: indica el extracto ya pagado o el afiliado al que le falta el IBAN. Deselecciónalo o completa sus datos. Comprueba también que la razón social y el IBAN de la empresa están rellenados.

Compatibilidad

• PrestaShop 8.0 a 9.x, el mismo ZIP cubre ambas ramas.
• Multiidioma y multimoneda, comisiones calculadas en la moneda por defecto.
• Arquitectura ModuleAdminController, sin dependencias de Composer.
• Módulo y emails traducidos a inglés, francés, español, alemán, italiano, neerlandés, polaco y portugués.