Download the PHP package montu/module-affiliate without Composer

Montu Affiliate — Extensión de Magento 2 (montu/module-affiliate)

Paquete Composer del módulo Montu_Affiliate: captura códigos de afiliados en el storefront y envía webhooks firmados con la información de las órdenes a la plataforma Montu.

Este directorio es el paquete Composer (raíz = raíz del módulo). No contiene una instalación de Magento ni entorno Docker — solo el código del módulo, instalable vía Composer en cualquier proyecto Magento 2.

✨ Características

• ✅ No Invasivo — no modifica tablas core de Magento (crea las suyas)
• ✅ Asíncrono — no bloquea el checkout; los webhooks se entregan por cron
• ✅ Fail-safe — los observers nunca dejan escapar excepciones
• ✅ Reintentos automáticos — 5 intentos con backoff exponencial (1/5/15/30/60 min)
• ✅ White-label — el storefront del afiliado adopta los colores y la tipografía de cualquier tema de la tienda (o se configuran a mano en el admin)

📦 Instalación vía Composer

El paquete está publicado en Packagist público, así que la instalación es directa, sin configurar repositorios:

Requisitos: Magento 2.4.x y PHP 8.1+.

El composer.json no fija version: Composer toma la versión de los tags git del repo publicado en Packagist (git tag v1.0.0), así que puedes fijar ^1.0 si lo necesitas.

Activar el módulo (después de composer require)

⚙️ Configuración

Stores → Configuration → Montu → Affiliate Tracking

Storefront del afiliado (sección Affiliate Storefront)

Idioma: Magento no hace fallback de es_CL → es_ES, por eso el módulo incluye traducciones propias para Chile (i18n/es_CL.csv). Para una tienda chilena, selecciona Spanish (Chile).

Apariencia / White-label (sección Appearance)

El storefront es white-label: adopta los colores y la tipografía de la tienda automáticamente. Todos los colores, bordes, radios de tarjeta y la fuente se controlan por variables CSS.

• Auto: sin configurar nada, el storefront muestrea el color del botón primario, el color de texto y la fuente del tema vivo de la tienda (Luma, custom o re-skin) y se adapta. Los valores de arriba sirven como semilla/fallback.
• Manual: fija exactamente los colores configurados, sin muestreo runtime. Los campos vacíos usan el default neutro.
• Off: estilo neutro por defecto (sin muestreo, ignora los colores).

🛍️ Tienda del Afiliado (/storefront/{code})

Un visitante puede entrar con un código de afiliado de dos formas, y en ambas se guarda la cookie con el código:

1. Query param — https://tienda.com/?_m_aff=ABC123 (capturado por JS).
2. Ruta storefront — https://tienda.com/storefront/ABC123, que además renderiza una página con los productos que ese afiliado recomienda.

La ruta la resuelve un router personalizado (Controller/Router.php) que toma el código del path y reenvía a Controller/Storefront/Index.php. El controlador valida el código (^[a-zA-Z0-9_\-]{1,100}$), escribe la cookie en el servidor (mismo nombre/duración que la captura por JS) y renderiza la página, declarada cacheable="false" para que el Full Page Cache / Fastly nunca la sirva cacheada.

Los productos se obtienen vía Service/RecommendationClient.php desde el endpoint de recomendaciones de Montu (GET /montu/api/v1/ecommerce/magento/recommendations/{store_id}/{code}), firmado con HMAC-SHA256 (igual que el webhook). Configura Recommendations Endpoint URL en admin con la URL terminada en el id de tienda. La forma esperada del JSON está documentada en RecommendationClient::parseResponse(). Si el endpoint falla o no responde, la página degrada con elegancia (datos de ejemplo) en vez de romperse.

Full Page Cache / Fastly: la ruta /storefront/{code} está declarada cacheable="false", así que el FPC/Fastly nunca la cachea (es por-afiliado y escribe la cookie). El JS de captura (tracking.js) lee el parámetro ?_m_aff= en el cliente, así que funciona aunque el resto de las páginas estén cacheadas.

Queue-it / Klevu / reglas de path: si la tienda tiene una sala de espera virtual o un proxy de búsqueda delante del storefront, agrega el prefijo de la ruta (/storefront/...) a la lista de paths permitidos para que no sea interceptado.

🔄 Cómo Funciona

1. Captura — view/frontend/web/js/tracking.js guarda ?_m_aff= en cookie.
2. Persistir al carrito — Observer/SaveAffiliateToQuote (checkout_cart_save_after).
3. Vincular a orden — Observer/CopyAffiliateToOrder (sales_model_service_quote_submit_success).
4. Encolar webhook — Observer/SendOrderWebhook (checkout_submit_all_after) si la orden tiene código de afiliado o cupón.
5. Entregar async — Cron/ProcessWebhooks → Service/WebhookService (Curl + HMAC + reintentos).

📊 Sistema de Reintentos

Tras el 5º intento el webhook se marca como max_retries.

📨 Formato del Webhook

Headers

Body (JSON)

El backend valida la firma y rechaza timestamps de más de 5 minutos (anti-replay). El receptor vive en el backend Django: back/montu/rest_api/v1/views/ecommerce/magento/. Cualquier cambio al payload aquí requiere el cambio correspondiente allá, en sincronía.

🧪 Testing Local

1. URL de prueba en webhook.site.
2. En admin → Webhook URL: https://webhook.site/tu-uuid, API Key: test-key-123.
3. Visitar https://tu-tienda.test/?_m_aff=TEST123, verificar cookie, crear una orden, y:

📁 Estructura del paquete

Tablas propias (nunca toca core)

• montu_affiliate_tracking — código de afiliado por quote/orden
• montu_affiliate_webhook_log — cola de webhooks con status + retry count

🗑️ Desinstalación

Requisitos

• Magento 2.4.x, PHP 8.1+ (ver composer.json para los módulos Magento requeridos)
• Cron de Magento funcionando (* * * * * php bin/magento cron:run)

Licencia

Open Software License 3.0 (OSL-3.0) — ver LICENSE.txt.

Soporte

[email protected]