1. Qué es este módulo

El módulo amplía Magento 2 con un sistema de afiliación completo que funciona directamente dentro de la tienda. Esto significa que el propietario de la tienda gestiona partners, comisiones, liquidaciones y materiales promocionales desde su propio panel de administración, mientras que los partners utilizan su propio dashboard en la cuenta de cliente.

En la práctica, el módulo permite implementar varios modelos de colaboración al mismo tiempo:

• programa de afiliación clásico basado en enlaces de seguimiento,
• programa de recomendación basado en códigos individuales de partners,
• modelo híbrido: enlace de afiliación más código descuento,
• programa de partners para clientes de la tienda, agencias, implementadores y creadores.

2. Principal valor de negocio

El mayor valor del módulo es la combinación de ventas, atribución, liquidaciones y gestión de partners en un único lugar. La tienda no necesita mantener un sistema de afiliación externo, exportar pedidos manualmente ni liquidar a los partners en hojas de cálculo.

El módulo proporciona al propietario de la tienda:

• un nuevo canal de ventas,
• control sobre las reglas de colaboración,
• gestión clara de comisiones y pagos,
• informes legibles sobre el rendimiento de los afiliados,
• posibilidad de lanzar el programa de forma segura también en tiendas de escala media y grande.

El partner recibe:

• su propio código de recomendación,
• su propio enlace de afiliación,
• un panel listo para monitorizar acciones,
• visibilidad de comisiones y payouts,
• posibilidad de utilizar materiales promocionales y banners.

3. A quién va dirigido el módulo

El módulo es adecuado para tiendas que quieren crear una red de partners de ventas sin recurrir a plataformas de afiliación externas o que desean conservar el control total sobre los datos y el proceso de liquidación.

Funciona especialmente bien en proyectos en los que el programa de afiliación debe ser gestionado por:

• clientes que recomiendan la tienda a conocidos,
• creadores digitales,
• blogueros y editores,
• especialistas y consultores,
• partners de implementación,
• software houses y agencias,
• resellers y comerciales B2B,
• embajadores de marca y comunidades.

4. Funciones principales del módulo

4.1. Registro de afiliado

El módulo ofrece un formulario de solicitud para el programa de afiliación. El cliente puede solicitar por sí mismo participar en el programa indicando datos básicos de contacto, la dirección de su sitio o canal y una breve información sobre la promoción prevista.

Tras enviar el formulario:

• se crea una cuenta de afiliado,
• se genera un referral_code único,
• el estado de la solicitud se establece como Pending,
• el administrador puede recibir una notificación sobre una nueva solicitud,
• el cliente puede recibir una confirmación de recepción de la solicitud.

4.2. Aprobación del partner

El administrador puede aprobar al afiliado desde el panel de Magento. Tras la aceptación:

• el estado del partner cambia a Active,
• el partner puede utilizar el programa por completo,
• es posible activar el cupón de afiliación,
• el cliente puede recibir un mensaje sobre la aprobación de su participación.

4.3. Enlace de afiliación

Cada afiliado recibe su propio enlace de afiliación basado en referral_code. El enlace funciona mediante un controlador de seguimiento y registra la atribución de la visita. Tras hacer clic, el sistema puede:

• guardar la afiliación en una cookie,
• crear un registro de visita,
• crear un registro de atribución,
• vincular un pedido posterior con un afiliado concreto.

4.4. Código de afiliación y cupón descuento

El módulo también admite un modelo en el que referral_code puede funcionar como código descuento en el carrito.

El administrador puede configurar en la cuenta del afiliado el campo:

• Affiliate Coupon Discount (%)

Si el valor es superior a cero, el sistema:

• sincroniza la regla nativa Cart Price Rule de Magento,
• establece el código del cupón igual a referral_code,
• aplica un descuento porcentual en el carrito,
• trata el uso de este código como fuente de afiliación del pedido.

Gracias a ello, el afiliado puede promocionar:

• un enlace de afiliación estándar,
• solo el código descuento,
• la combinación de ambos mecanismos al mismo tiempo.

Esta es una de las funciones comerciales más prácticas del módulo, ya que muchos propietarios de tiendas esperan que el partner no solo dirija tráfico, sino que también ofrezca al cliente una ventaja de precio concreta.

4.5. Atribución de pedidos

El módulo puede asignar un pedido a un afiliado en función de:

• un clic en el enlace de afiliación,
• una atribución activa guardada en la sesión o en una cookie,
• el uso del código de afiliación en el carrito,
• un cliente conectado vinculado a una atribución activa.

A nivel de pedido se guardan los datos:

• affiliate_id,
• affiliate_attribution_id,
• affiliate_referral_code,
• is_affiliate_order,
• affiliate_commission_amount,
• affiliate_commission_status.

Esto permite informar sobre la fuente de venta directamente en quote y sales_order.

4.6. Cálculo de comisiones

La comisión se crea automáticamente para un pedido de afiliación. En el modelo actual:

• la comisión se calcula porcentualmente sobre el subtotal del pedido,
• la tarifa predeterminada procede de la configuración del módulo,
• el sistema evita duplicar comisiones para el mismo pedido y afiliado,
• el resultado se guarda en la tabla de comisiones y en el pedido.

Los estados de comisión admitidos incluyen, entre otros:

• pending,
• approved,
• ready_for_payout,
• paid,
• rejected,
• cancelled,
• charged_back.

4.7. Periodo de retención y aprobación automática

El módulo admite un periodo de retención de comisiones. Esto significa que la comisión no tiene que estar lista para el pago de inmediato. Puede permanecer en estado pendiente durante un tiempo determinado y, solo una vez transcurrido el periodo establecido, ser aprobada automáticamente por cron.

Esta solución es especialmente importante en casos de:

• riesgo de devoluciones,
• verificación manual de pedidos,
• modelos de venta con finalización diferida,
• necesidad de proteger el programa frente a abusos.

4.8. Pagos para afiliados

El partner puede presentar una solicitud de pago si se ha alcanzado el umbral mínimo y dispone de saldo aprobado suficiente.

El workflow de payouts incluye:

• envío de un payout request,
• asignación de comisiones al payout,
• cambio del estado de la comisión a ready_for_payout,
• marcado del pago como abonado,
• cambio de los estados de comisión a paid.

Gracias a ello, el propietario de la tienda puede gestionar los pagos de forma ordenada y auditable.

4.9. Fraud prevention

El módulo dispone de una capa antifraude básica que ayuda a eliminar los abusos más evidentes.

Incluye, entre otros:

• bloqueo de self-referral,
• marcado de comisiones como rechazadas cuando se detecta un abuso,
• gestión de casos de fraude,
• registro de motivos de rechazo,
• vista independiente de fraud cases para el administrador.

Además, el módulo admite:

• cancelaciones de pedidos,
• chargebacks,
• reembolsos mediante creditmemo,
• cambio de estados de comisión tras devoluciones.

4.10. Notificaciones

El módulo cuenta con su propio sistema de encolado y procesamiento de notificaciones. Puede registrar eventos operativos y enviar mensajes de correo electrónico.

Los casos admitidos incluyen, entre otros:

• nueva solicitud de afiliado,
• confirmación de recepción de la solicitud,
• aceptación del afiliado,
• eventos de comisión,
• payouts,
• fraud alerts.

4.11. Panel del afiliado

El partner utiliza un dashboard avanzado en la cuenta de cliente de Magento. El dashboard no es solo una lista de comisiones, sino un panel operativo completo.

En el panel del afiliado están disponibles:

• estado de participación en el programa,
• código de recomendación,
• enlace de afiliación completo,
• ruta de destino predeterminada,
• resumen de comisiones,
• historial de comisiones,
• acceso a payouts,
• contenidos con las reglas de colaboración,
• snippets promocionales listos,
• vista previa del banner,
• generador de banners AI.

4.12. Generador de banners AI

El módulo incluye una función asistida por AI que permite al afiliado preparar un banner promocional listo a partir de un brief.

El usuario puede indicar:

• brief textual,
• dirección visual,
• colores,
• estilo,
• URL opcional de la imagen,
• target link opcional.

El sistema envía a la capa AI:

• brief del usuario,
• referral link,
• target path,
• requisitos técnicos sobre el formato de respuesta.

El HTML generado del banner puede guardarse en la cuenta del afiliado y ser utilizado por el partner como material promocional listo.

4.13. Informes

El módulo admite informes y exportaciones CSV para las áreas clave del programa:

• comisiones,
• payouts,
• fraud cases,
• insights AI.

Esto facilita tanto la gestión diaria del programa como el análisis del rendimiento de los partners.

5. Panel de administración

El módulo amplía el panel de administración de Magento con configuración y gestión del programa de afiliación.

El administrador tiene acceso a:

• ajustes globales del programa,
• ajustes de comisiones,
• ajustes de payouts,
• ajustes del portal del afiliado,
• ajustes de notificaciones,
• ajustes de fraude,
• ajustes de AI,
• ajustes de reporting.

Además, en el panel están disponibles las secciones operativas:

• Affiliate Commissions,
• Affiliate Payouts,
• Affiliate Fraud Cases,
• Affiliate Reports.

En la lista de clientes y en la edición de cliente se muestran datos de afiliación como:

• participación en el programa,
• estado del afiliado,
• saldo del afiliado,
• código de recomendación,
• porcentaje de descuento del cupón de afiliación.

6. Cómo funciona la afiliación en la práctica

6.1. Escenario del enlace de afiliación

1. El partner recibe su enlace.
2. El cliente hace clic en el enlace y llega a la tienda.
3. El sistema registra la visita y la atribución.
4. El cliente realiza un pedido.
5. El pedido se asigna al afiliado.
6. Se crea una comisión.
7. Tras finalizar el periodo de retención, la comisión puede ser aprobada.
8. Cuando se cumplen las condiciones, el partner puede solicitar el pago.

6.2. Escenario del código de afiliación en el carrito

1. El partner publica su código de afiliación.
2. El cliente introduce el código en el carrito.
3. Magento aplica el descuento de la regla de carrito.
4. El módulo reconoce el código como código del afiliado.
5. El pedido se asigna al afiliado.
6. Se crea una comisión de acuerdo con las reglas del programa.

6.3. Escenario híbrido

El cliente puede entrar primero en la tienda mediante un enlace de afiliación y después utilizar el código descuento del afiliado. Este modelo permite combinar el tracking clásico con beneficios para el cliente final.

7. Áreas de seguridad

El módulo se ha preparado pensando en una implementación en producción, por lo que contempla:

• registros de auditoría,
• gestión de devoluciones y cancelaciones,
• bloqueo de self-referral,
• cola de notificaciones,
• mecanismos que limitan la duplicación de comisiones,
• almacenamiento seguro de la configuración AI,
• limitación de los datos enviados a la capa AI,
• posibilidad de diagnosticar errores de integración.

8. Integración con AI

La capa AI del módulo es opcional y no bloquea el funcionamiento del programa de afiliación básico. Puede utilizarse para:

• asistente del afiliado,
• generación de insights,
• generación de banners,
• retrieval de conocimiento de producto mediante vector_store_id.

El módulo no necesita mantener su propia base de productos para AI si la tienda ya utiliza un módulo externo que gestiona el conocimiento de producto y Vector Store.

9. Aplicaciones comerciales

El módulo puede venderse como solución para varios tipos de proyectos:

• tiendas B2C con programa de recomendación,
• tiendas premium que quieren construir una red de embajadores de marca,
• negocios B2B con programa para partners comerciales,
• tiendas digitales y de software,
• implementaciones de agencia en las que el cliente necesita un programa de partners completo sin un SaaS externo.

Argumentos comerciales especialmente sólidos son:

• control total sobre los datos,
• ausencia de suscripción a una plataforma de afiliación externa,
• integración con Magento 2 sin intermediarios,
• soporte para enlaces y cupones de afiliación,
• panel de partner listo,
• posibilidad de ampliación futura con AI.

10. Principales ventajas del módulo

Las principales ventajas de esta solución son:

• funciona directamente en Magento 2,
• admite tanto enlaces como códigos de afiliación,
• gestiona cupones descuento vinculados al afiliado,
• permite gestionar partners desde el nivel de cliente de Magento,
• cuenta con un workflow real de comisiones y payouts,
• incluye seguridad básica y auditoría,
• dispone de un dashboard de afiliado moderno,
• está preparado para evolucionar con nuevas funciones enterprise.

11. Requisitos del sistema

El módulo está destinado a:

• Magento Open Source / Adobe Commerce 2.4.7+
• PHP 8.2 / 8.3

Requiere módulos Magento compatibles relacionados con:

• Customer,
• Quote,
• Sales,
• SalesRule,
• Cms,
• Email,
• Backend,
• Store.

12. Alcance de implementación

El módulo puede implementarse por fases:

• inicio con enlaces de afiliación y comisiones,
• ampliación con payouts,
• ampliación con cupones de afiliación,
• ampliación con AI y contenido para afiliados,
• desarrollo posterior con reglas de comisión más avanzadas y fraud scoring.

Esto significa que es adecuado tanto para implementaciones MVP como para el desarrollo a largo plazo de un programa de partners.

13. Resumen

Kowal_Affiliate es un módulo de afiliación maduro para Magento 2 que permite vender y lanzar un programa de partners completo dentro de la propia tienda. Combina enlaces de afiliación clásicos, códigos de recomendación, cupones descuento, comisiones, payouts, fraud prevention básico, informes y un panel de partner moderno.

Desde una perspectiva comercial, no es solo un complemento para enlaces de recomendación, sino una capa completa de partners para Magento 2 que puede ofrecerse como:

• módulo standalone,
• elemento de implementación de la tienda,
• parte de un paquete growth / performance,
• base para un programa de partners y embajadores de marca más avanzado.

En la práctica, es una solución que responde a necesidades reales de tiendas que preguntan por:

• programa de afiliación en Magento 2,
• códigos descuento para partners,
• liquidación de comisiones,
• panel de partner,
• preparación para ventas y funcionamiento en producción.