Kowal_Affiliate - instrucciones de instalación y configuración

Este documento describe cómo instalar, activar y realizar la primera configuración del módulo Kowal_Affiliate para Magento 2. La guía incluye tanto los requisitos técnicos como los pasos prácticos necesarios para poner en marcha un programa de afiliados en la tienda.

1. Requisitos del sistema

El módulo está destinado a:

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

En el proyecto Magento deberían estar disponibles al menos los módulos:

• Magento_Store
• Magento_Cms
• Magento_Customer
• Magento_Email
• Magento_Quote
• Magento_Sales
• Magento_SalesRule
• Magento_Backend

2. Métodos de instalación

El módulo puede desplegarse de forma estándar como paquete Composer.

2.1. Instalación mediante Composer

El módulo se distribuye como paquete Composer; un proceso de ejemplo es el siguiente:

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, la dirección de e-mail del cliente y el token de licencia, 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 la dirección de 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.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-affiliatebin/magento module:enable Kowal_Affiliatebin/magento setup:upgradebin/magento setup:di:compilebin/magento cache:flush

2.3. Modo de producción

Si la tienda funciona en production mode, después de la instalación también conviene ejecutar:

bin/magento setup:static-content:deploy

3. Qué crea el módulo durante la instalación

Durante la instalación, el módulo:

• crea sus propias tablas de base de datos relacionadas con la afiliación,
• amplía quote y sales_order con campos de afiliación,
• añade atributos de cliente utilizados para gestionar al afiliado,
• crea una página CMS predeterminada del programa de afiliados,
• prepara la configuración del sistema y los cron jobs,
• registra plantillas de e-mail y recursos del panel de administración.

3.1. Página CMS predeterminada

Después de la instalación se crea una página de ejemplo del programa de afiliados:

identifier: affiliate-programtitle: Affiliate Partnership Program

La página tiene un carácter universal y puede usarse en producción tras una ligera personalización del contenido.

El patch es idempotente:

• si ya existe una página con este identifier, el módulo no la sobrescribirá.

4. Dónde encontrar la configuración del módulo

El panel de configuración se encuentra en:

Stores -> Configuration -> Affiliate Program

Las secciones más importantes:

• General
• Commission
• Payouts
• Affiliate Portal
• Notifications
• Fraud
• AI
• Reporting

5. Primera configuración después de la instalación

Tras activar el módulo, se recomienda seguir este orden de configuración:

1. activa el módulo globalmente,
2. configura el registro de afiliados,
3. configura la comisión y el hold period,
4. establece el umbral mínimo de pago,
5. completa los contenidos del portal del afiliado,
6. configura las notificaciones del administrador,
7. opcionalmente, configura AI,
8. realiza una prueba de registro, clic de afiliación y pedido.

6. Configuración detallada

6.1. General

Enable Module

Interruptor global del módulo.

Si el ajuste está desactivado:

• el tracking de afiliación no debería funcionar,
• el formulario de registro no debería funcionar,
• las comisiones y los payouts no se gestionarán.

Recomendación:

• Yes en el entorno de producción después de finalizar las pruebas,
• No solo durante la desactivación del programa.

Enable Affiliate Registration

Activa el formulario de solicitud del programa de afiliados en el frontend de la tienda.

Si la opción está desactivada:

• los nuevos partners no podrán registrarse por sí mismos,
• el administrador aún podrá marcar manualmente a un cliente como afiliado.

Tracking Cookie Lifetime (days)

Define la duración de la atribución basada en cookie después de hacer clic en un enlace de afiliado.

Ejemplos:

• 30 para un programa de afiliados estándar,
• 7 para campañas cortas,
• 60 o 90 solo cuando las normas del programa lo contemplen.

Default Redirect Path

Ruta de respaldo utilizada cuando el tracking link no contiene un target correcto.

Ejemplos:

• /
• promotions
• catalog/category/view/id/12

6.2. Commission

Enable Commissions

Activa el cálculo de comisiones para los pedidos de afiliación.

Si el campo está desactivado:

• la afiliación puede guardarse,
• pero no se creará ningún registro en la tabla de comisiones.

Default Commission Rate (%)

Tarifa predeterminada de comisión porcentual.

Ejemplo:

• 10 significa una comisión del 10% sobre la base de cálculo actual.

Commission Hold Period (days)

Número de días durante los cuales la comisión permanece en estado pendiente.

Transcurrido este periodo, cron puede aprobar automáticamente la comisión.

Recomendación:

• 14 como valor predeterminado seguro,
• 0 solo en un programa muy sencillo sin riesgo de devoluciones.

6.3. Payouts

Enable Payouts

Activa el workflow de pagos para afiliados.

Si la opción está desactivada:

• el partner no podrá enviar una solicitud de payout,
• el administrador aún podrá analizar las comisiones, pero no gestionará el pago en el módulo.

Minimum Payout Amount

Saldo mínimo requerido para solicitar un pago.

Ejemplos:

• 100
• 250
• 500

6.4. Affiliate Portal

Esta sección controla los contenidos que se muestran en el dashboard del afiliado.

Dashboard Intro

Breve descripción en la parte superior del dashboard del afiliado.

Debe explicar al partner:

• dónde encontrará el enlace de afiliado,
• dónde verá las comisiones,
• cómo funciona el panel.

Program Rules

Normas de colaboración visibles para el afiliado.

Lo más recomendable es introducir:

• una norma por línea,
• mensajes concisos e inequívocos.

Banner Title

Título predeterminado del material promocional de ejemplo.

Banner Subtitle

Breve descripción bajo el título del banner.

Banner Target Path

Ruta de target predeterminada para enlaces de afiliado y banners.

Ejemplos:

• /
• promotions/spring
• catalog/category/view/id/24

6.5. Notifications

Enable Notifications

Activa el sistema interno de notificaciones y la cola de notificaciones.

Admin Notification Email

Dirección de e-mail del administrador que debe recibir los comunicados operativos más importantes.

Si el campo se deja vacío:

• el módulo puede usar la dirección predeterminada general de Magento como fallback en determinados flows.

Notification Log Retention (days)

Define durante cuánto tiempo deben conservarse las entradas del log de notificaciones antes del cleanup.

6.6. Fraud

Enable Fraud Checks

Activa los controles antifraude básicos.

Block Self Referral

Bloquea la comisión cuando el cliente que realiza el pedido es al mismo tiempo el afiliado asociado a ese pedido.

6.7. AI

La sección AI es opcional y no es necesaria para el funcionamiento básico del programa de afiliados.

Enable AI

Interruptor principal de las funciones AI.

OpenAI API Key

Clave API para la comunicación con OpenAI.

El campo se almacena en configuración cifrada.

AI Model Name

Modelo utilizado para las funciones AI.

La lista de modelos puede obtenerse de OpenAI después de guardar correctamente la clave API.

OpenAI Request Timeout (seconds)

Tiempo máximo de espera de respuesta de OpenAI.

Recomendación práctica:

• 60 segundos para un funcionamiento más estable en producción.

Enable AI Diagnostic Logging

Activa el registro diagnóstico de requests y respuestas AI.

Útil en:

• integración,
• pruebas,
• análisis de timeouts y errores de respuesta.

AI Diagnostic Max Chars

Longitud máxima del preview del payload registrado.

Enable Affiliate Assistant

Activa el asistente de afiliado si la tienda quiere utilizar esta función.

Enable Weekly AI Reports

Permite generar resúmenes AI periódicos.

Enable Product Knowledge Retrieval

Permite utilizar conocimiento de producto desde Vector Store.

Enable Program Knowledge Retrieval

Permite utilizar conocimiento sobre el programa de afiliados, FAQ y documentación.

Product Vector Store Scope

Define cómo se resuelve product_vector_store_id.

Product Vector Store ID

Identificador de Vector Store si la tienda utiliza retrieval.

Redact Personal Data

Elimina o enmascara los datos personales antes de enviar el prompt a la capa AI.

6.8. Reporting

Enable Reporting

Activa la generación de informes y exportaciones CSV.

Export Directory

Ruta del directorio en el que deben guardarse las exportaciones generadas.

Ejemplo:

var/export/affiliate

7. Configuración de un cliente como afiliado

Después de la instalación, el módulo amplía la edición de cliente de Magento con campos de afiliación.

En la edición del cliente se pueden gestionar, entre otros:

• Affiliate Participant
• Affiliate Status
• Affiliate Referral Code
• Affiliate Website URL
• Affiliate Notes
• Affiliate Balance
• Affiliate Coupon Discount (%)

7.1. Affiliate Participant

Indica si el cliente pertenece al programa de afiliados.

7.2. Affiliate Status

Estados más importantes:

• Pending
• Active
• Suspended
• Rejected
• Blocked

7.3. Affiliate Balance

El saldo se calcula automáticamente a partir de las comisiones aprobadas y listas para el pago.

El campo:

• es visible en la edición del cliente,
• no debería editarse manualmente,
• se actualiza automáticamente después de cambios en las comisiones.

7.4. Affiliate Coupon Discount (%)

Este campo permite asignar al afiliado un porcentaje de descuento que funcionará sobre su referral_code.

Si introduces un valor superior a 0, el módulo:

• creará o actualizará una regla de carrito de Magento,
• establecerá un cupón igual al código del afiliado,
• permitirá a los clientes utilizar ese código como cupón en el carrito,
• asignará el pedido al afiliado en función de coupon_code.

Ejemplo:

• el afiliado tiene el código FMX1FBXXY3
• el administrador introduce 5
• el cliente introduce FMX1FBXXY3 como cupón de descuento
• Magento aplica un 5% de descuento
• el módulo asigna el pedido al afiliado.

8. Cron jobs del módulo

El módulo utiliza crons en el grupo default.

8.1. Auto approve commissions

job: kowal_affiliate_auto_approve_commissionsschedule: */15 * * * *

La tarea:

• comprueba las comisiones pending,
• tras finalizar el hold period las cambia a approved.

8.2. Process notifications

job: kowal_affiliate_process_notificationsschedule: */10 * * * *

La tarea:

• procesa la cola de notificaciones,
• marca las entradas como enviadas,
• en el caso del canal e-mail, envía mensajes transaccionales.

8.3. Cleanup notification log

job: kowal_affiliate_cleanup_notification_logschedule: 30 2 * * *

La tarea:

• elimina entradas antiguas del log de notificaciones según la retención.

8.4. Weekly AI insights

job: kowal_affiliate_generate_weekly_ai_insightsschedule: 0 6 * * 1

La tarea:

• genera insights AI semanales si la función está activa.

9. Comandos CLI

El módulo proporciona comandos de servicio:

bin/magento kowal:affiliate:auto-approvebin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:cleanup-notificationsbin/magento kowal:affiliate:generate-ai-insightsbin/magento kowal:affiliate:export-report

Los más útiles durante la primera puesta en marcha son:

bin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:auto-approve

10. Primera prueba después de la instalación

Después de configurar el módulo, se recomienda realizar una prueba end-to-end sencilla.

10.1. Prueba de registro de afiliado

1. Accede al formulario de registro de afiliado.
2. Envía la solicitud.
3. Comprueba si se ha creado la cuenta de afiliado.
4. Comprueba si el cliente tiene el estado Pending.
5. Comprueba si se han creado entradas de notificación.

10.2. Prueba de activación

1. Abre la edición del cliente en el panel de administración.
2. Establece el estado del afiliado en Active o utiliza la acción de aprobación.
3. Comprueba si el cliente ve el dashboard de afiliado.

10.3. Prueba del enlace de afiliado

1. Copia el enlace de afiliado desde el dashboard.
2. Accede a la tienda a través de ese enlace.
3. Añade un producto al carrito.
4. Realiza un pedido.
5. Comprueba si el pedido tiene:
   • affiliate_id
   • affiliate_referral_code
   • is_affiliate_order = 1

10.4. Prueba del cupón de afiliado

1. Establece al afiliado Affiliate Coupon Discount (%), p. ej., 5.
2. Guarda el cliente.
3. Asegúrate de que el afiliado tenga el estado Active.
4. En el carrito, introduce su Referral Code como cupón.
5. Realiza un pedido.
6. Comprueba:
   • si se ha aplicado el descuento,
   • si el pedido se ha asignado al afiliado,
   • si se ha creado la comisión.

10.5. Prueba de payouts

1. Aprueba la comisión o espera al auto-approve.
2. Comprueba el saldo del afiliado.
3. Envía una solicitud de pago.
4. Marca el payout como pagado en el panel de administración.

11. Problemas más frecuentes después de la instalación

11.1. No hay comisión después del pedido

Comprueba:

• si el pedido tiene affiliate_id,
• si las comisiones están activadas,
• si el módulo funciona tras la corrección de creación de comisiones después de guardar los datos de afiliación en el pedido,
• si aparece un registro en la tabla kowal_affiliate_commission.

11.2. El grid de clientes no muestra el saldo actual del afiliado

Comprueba:

• si se ha actualizado el índice customer_grid,
• si reindexRow funciona después de guardar,
• si el valor en la edición del cliente coincide con el valor en el grid.

Si es necesario, ejecuta:

bin/magento indexer:reindex customer_grid

11.3. AI no responde

Comprueba:

• si Enable AI está activado,
• si se ha guardado una OpenAI API Key correcta,
• si se ha seleccionado un modelo,
• si el timeout no es demasiado bajo,
• si var/log no muestra errores de request a OpenAI.

11.4. Las notificaciones no se envían

Comprueba:

• si los crons de Magento funcionan,
• si Enable Notifications está activo,
• si las entradas se guardan en kowal_affiliate_notification_log,
• si puedes ejecutar manualmente:

bin/magento kowal:affiliate:process-notifications

12. Configuración inicial recomendada

Para la primera implantación en producción se recomienda este conjunto:

• Enable Module = Yes
• Enable Affiliate Registration = Yes
• Tracking Cookie Lifetime = 30
• Enable Commissions = Yes
• Default Commission Rate = 10
• Commission Hold Period = 14
• Enable Payouts = Yes
• Minimum Payout Amount = 100
• Enable Notifications = Yes
• Block Self Referral = Yes
• Enable AI = No al inicio, si la tienda no necesita AI desde el primer día

13. Resumen

Después de una instalación y configuración correctas, Kowal_Affiliate permite poner en marcha en Magento 2 un programa de afiliados completo que incluye:

• afiliados,
• enlaces de referido,
• códigos de afiliado,
• cupones de descuento de afiliados,
• comisiones,
• payouts,
• notificaciones,
• dashboard del partner,
• seguridad básica y automatización.