1. Che cos’è questo modulo

Il modulo estende Magento 2 con un sistema di affiliazione completo che opera direttamente all’interno dello store. Ciò significa che il proprietario del negozio gestisce partner, commissioni, liquidazioni e materiali promozionali dal proprio pannello di amministrazione, mentre i partner utilizzano una dashboard dedicata nel proprio account cliente.

In pratica, il modulo consente di implementare contemporaneamente diversi modelli di collaborazione:

• un classico programma di affiliazione basato su link di tracciamento,
• un programma referral basato su codici partner individuali,
• un modello ibrido: link di affiliazione più codice sconto,
• un programma partner per clienti dello store, agenzie, implementatori e creator.

2. Principale valore di business

Il valore più importante del modulo è l’unione di vendite, attribuzione, liquidazioni e gestione dei partner in un unico punto. Lo store non deve mantenere un sistema di affiliazione esterno, esportare manualmente gli ordini né liquidare i partner in fogli di calcolo.

Il modulo offre al proprietario dello store:

• un nuovo canale di vendita,
• controllo sulle regole di collaborazione,
• gestione trasparente di commissioni e pagamenti,
• report chiari sull’efficacia degli affiliati,
• possibilità di avviare in sicurezza il programma anche in store di medie e grandi dimensioni.

Il partner riceve:

• un proprio codice referral,
• un proprio link di affiliazione,
• un pannello pronto per monitorare le attività,
• visibilità su commissioni e payout,
• possibilità di utilizzare materiali promozionali e banner.

3. A chi è destinato il modulo

Il modulo è adatto agli store che desiderano costruire una rete di partner commerciali senza utilizzare piattaforme di affiliazione esterne oppure che vogliono mantenere il pieno controllo sui dati e sul processo di liquidazione.

È particolarmente indicato per progetti in cui il programma di affiliazione deve essere gestito da:

• clienti che consigliano lo store ad amici e conoscenti,
• creator online,
• blogger ed editori,
• specialisti e consulenti,
• partner di implementazione,
• software house e agenzie,
• reseller e commerciali B2B,
• ambassador del brand e community.

4. Funzionalità principali del modulo

4.1. Registrazione dell’affiliato

Il modulo mette a disposizione un modulo di candidatura al programma di affiliazione. Il cliente può inviare autonomamente la richiesta di partecipazione, indicando i dati di contatto di base, l’indirizzo del sito o del canale e una breve informazione sulla promozione pianificata.

Dopo l’invio del modulo:

• viene creato un account affiliato,
• viene generato un referral_code univoco,
• lo stato della richiesta viene impostato su Pending,
• l’amministratore può ricevere una notifica sulla nuova richiesta,
• il cliente può ricevere una conferma di ricezione della richiesta.

4.2. Approvazione del partner

L’amministratore può approvare l’affiliato dal pannello Magento. Dopo l’approvazione:

• lo stato del partner passa a Active,
• il partner può utilizzare pienamente il programma,
• è possibile attivare il coupon di affiliazione,
• il cliente può ricevere un messaggio di approvazione della partecipazione.

4.3. Link di affiliazione

Ogni affiliato riceve un proprio link di affiliazione basato su referral_code. Il link funziona tramite un controller di tracciamento e registra l’attribuzione della visita. Dopo il clic, il sistema può:

• salvare l’affiliazione in un cookie,
• creare una voce di visita,
• creare una voce di attribuzione,
• collegare un ordine successivo a uno specifico affiliato.

4.4. Codice di affiliazione e coupon sconto

Il modulo supporta anche un modello in cui referral_code può funzionare come codice sconto nel carrello.

L’amministratore può impostare nell’account dell’affiliato il campo:

• Affiliate Coupon Discount (%)

Se il valore è maggiore di zero, il sistema:

• sincronizza la regola nativa Cart Price Rule di Magento,
• imposta un codice coupon uguale a referral_code,
• applica uno sconto percentuale nel carrello,
• tratta l’utilizzo di questo codice come fonte di affiliazione dell’ordine.

Grazie a questo, l’affiliato può promuovere:

• un normale link di affiliazione,
• il solo codice sconto,
• la combinazione di entrambi i meccanismi contemporaneamente.

È una delle funzionalità commerciali più pratiche del modulo, perché molti proprietari di store si aspettano che il partner non solo porti traffico, ma offra anche al cliente un vantaggio di prezzo concreto.

4.5. Attribuzione degli ordini

Il modulo può attribuire un ordine a un affiliato in base a:

• clic su un link di affiliazione,
• attribuzione attiva salvata in sessione o cookie,
• utilizzo del codice di affiliazione nel carrello,
• cliente autenticato collegato a un’attribuzione attiva.

A livello di ordine vengono salvati i dati:

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

Questo consente di riportare la fonte della vendita direttamente su quote e sales_order.

4.6. Calcolo delle commissioni

La commissione viene creata automaticamente per un ordine affiliato. Nel modello attuale:

• la commissione viene calcolata in percentuale sul subtotale dell’ordine,
• la tariffa predefinita proviene dalla configurazione del modulo,
• il sistema evita la duplicazione delle commissioni per lo stesso ordine e affiliato,
• il risultato viene salvato nella tabella delle commissioni e sull’ordine.

Gli stati di commissione supportati includono, tra gli altri:

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

4.7. Hold period e approvazione automatica

Il modulo supporta un periodo di sospensione della commissione. Ciò significa che la commissione non deve essere subito pronta per il pagamento. Può rimanere per un determinato periodo nello stato in attesa e solo dopo la scadenza del periodo impostato essere approvata automaticamente tramite cron.

Questa soluzione è particolarmente importante in caso di:

• rischio di resi,
• verifica manuale degli ordini,
• modelli di vendita con finalizzazione ritardata,
• necessità di proteggere il programma dagli abusi.

4.8. Pagamenti per gli affiliati

Il partner può presentare una richiesta di pagamento se è stata raggiunta la soglia minima e dispone di un saldo approvato sufficiente.

Il workflow dei payout comprende:

• invio di una payout request,
• assegnazione delle commissioni al payout,
• modifica dello stato della commissione in ready_for_payout,
• contrassegno del pagamento come pagato,
• modifica degli stati delle commissioni in paid.

In questo modo il proprietario dello store può gestire i pagamenti in modo ordinato e verificabile.

4.9. Fraud prevention

Il modulo dispone di un livello antifrode di base che aiuta a eliminare gli abusi più evidenti.

Include tra l’altro:

• blocco del self-referral,
• contrassegno delle commissioni come rifiutate quando viene rilevato un abuso,
• gestione dei casi di frode,
• registro dei motivi di rifiuto,
• vista separata dei fraud case lato amministratore.

Inoltre, il modulo gestisce:

• annullamenti degli ordini,
• chargeback,
• rimborsi tramite creditmemo,
• modifica degli stati delle commissioni dopo i resi.

4.10. Notifiche

Il modulo dispone di un proprio sistema di accodamento ed elaborazione delle notifiche. Può registrare eventi operativi e inviare messaggi e-mail.

I casi supportati includono tra l’altro:

• nuova richiesta di affiliato,
• conferma di ricezione della richiesta,
• approvazione dell’affiliato,
• eventi relativi alle commissioni,
• payout,
• fraud alerts.

4.11. Pannello dell’affiliato

Il partner utilizza una dashboard avanzata nell’account cliente Magento. La dashboard non è solo un elenco di commissioni, ma un pannello operativo completo.

Nel pannello dell’affiliato sono disponibili:

• stato di partecipazione al programma,
• codice referral,
• link di affiliazione completo,
• percorso target predefinito,
• riepilogo delle commissioni,
• storico delle commissioni,
• accesso ai payout,
• contenuti delle regole di collaborazione,
• snippet promozionali pronti,
• anteprima del banner,
• generatore di banner AI.

4.12. Generatore di banner AI

Il modulo include una funzione assistita da AI che consente all’affiliato di preparare un banner promozionale pronto sulla base di un brief.

L’utente può fornire:

• brief testuale,
• direzione visiva,
• colori,
• stile,
• URL opzionale di un’immagine,
• target link opzionale.

Il sistema trasmette al livello AI:

• brief dell’utente,
• referral link,
• target path,
• requisiti tecnici relativi al formato della risposta.

L’HTML del banner generato può essere salvato nell’account dell’affiliato e utilizzato dal partner come materiale promozionale pronto.

4.13. Reporting

Il modulo supporta report ed esportazioni CSV per le aree chiave del programma:

• commissioni,
• payout,
• fraud case,
• insight AI.

Questo facilita sia la gestione quotidiana del programma sia l’analisi dell’efficacia dei partner.

5. Pannello di amministrazione

Il modulo estende il pannello di amministrazione Magento con la configurazione e la gestione del programma di affiliazione.

L’amministratore ha accesso a:

• impostazioni globali del programma,
• impostazioni delle commissioni,
• impostazioni dei payout,
• impostazioni del portale affiliato,
• impostazioni delle notifiche,
• impostazioni antifrode,
• impostazioni AI,
• impostazioni di reporting.

Inoltre, nel pannello sono disponibili sezioni operative:

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

Nell’elenco clienti e nella modifica del cliente sono visibili i dati di affiliazione, come:

• partecipazione al programma,
• stato dell’affiliato,
• saldo dell’affiliato,
• codice referral,
• percentuale di sconto del coupon affiliato.

6. Come funziona l’affiliazione nella pratica

6.1. Scenario del link di affiliazione

1. Il partner riceve il proprio link.
2. Il cliente clicca sul link e arriva allo store.
3. Il sistema registra la visita e l’attribuzione.
4. Il cliente effettua un ordine.
5. L’ordine viene attribuito all’affiliato.
6. Viene creata una commissione.
7. Dopo la scadenza dell’hold period, la commissione può essere approvata.
8. Una volta soddisfatte le condizioni, il partner può presentare una richiesta di pagamento.

6.2. Scenario del codice di affiliazione nel carrello

1. Il partner pubblica il proprio codice di affiliazione.
2. Il cliente inserisce il codice nel carrello.
3. Magento applica lo sconto dalla regola carrello.
4. Il modulo riconosce il codice come codice dell’affiliato.
5. L’ordine viene attribuito all’affiliato.
6. Viene creata una commissione secondo le regole del programma.

6.3. Scenario ibrido

Il cliente può prima entrare nello store tramite un link di affiliazione e poi utilizzare il codice sconto dell’affiliato. Questo modello consente di combinare il tracking classico con benefici per il cliente finale.

7. Aree di sicurezza

Il modulo è stato preparato pensando a un’implementazione in produzione, quindi include:

• registri di audit,
• gestione di resi e annullamenti,
• blocco del self-referral,
• coda delle notifiche,
• meccanismi che limitano la duplicazione delle commissioni,
• conservazione sicura della configurazione AI,
• limitazione dei dati inviati al livello AI,
• possibilità di diagnosticare errori di integrazione.

8. Integrazione con AI

Il livello AI nel modulo è opzionale e non blocca il funzionamento del programma di affiliazione di base. Può essere utilizzato per:

• assistente dell’affiliato,
• generazione di insight,
• generazione di banner,
• retrieval della conoscenza prodotto tramite vector_store_id.

Il modulo non deve mantenere un proprio database prodotti per AI se lo store utilizza già un modulo esterno per la gestione della conoscenza prodotto e Vector Store.

9. Applicazioni commerciali

Il modulo può essere venduto come soluzione per diversi tipi di progetti:

• store B2C con programma referral,
• store premium che desiderano costruire una rete di ambassador del brand,
• business B2B con programma per partner commerciali,
• store digitali e software,
• implementazioni di agenzia in cui il cliente necessita di un programma partner completo senza SaaS esterno.

Argomenti di vendita particolarmente forti sono:

• pieno controllo sui dati,
• assenza di abbonamento a una piattaforma di affiliazione esterna,
• integrazione con Magento 2 senza intermediari,
• supporto di link e coupon di affiliazione,
• pannello partner pronto,
• possibilità di ulteriore sviluppo con AI.

10. Principali vantaggi del modulo

I principali vantaggi di questa soluzione sono:

• funziona direttamente in Magento 2,
• supporta sia link sia codici di affiliazione,
• gestisce coupon sconto collegati all’affiliato,
• consente di gestire i partner dal livello del cliente Magento,
• dispone di un workflow reale per commissioni e payout,
• include sicurezza e audit di base,
• offre una dashboard moderna per l’affiliato,
• è pronto per essere sviluppato con ulteriori funzionalità enterprise.

11. Requisiti di sistema

Il modulo è destinato a:

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

Richiede moduli Magento compatibili relativi a:

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

12. Ambito di implementazione

Il modulo può essere implementato per fasi:

• partenza da link di affiliazione e commissioni,
• estensione con payout,
• estensione con coupon di affiliazione,
• estensione con AI e content per affiliati,
• ulteriore sviluppo con regole commissionali più avanzate e fraud scoring.

Ciò significa che è adatto sia a implementazioni MVP sia allo sviluppo a lungo termine di un programma partner.

13. Riepilogo

Kowal_Affiliate è un modulo di affiliazione maturo per Magento 2 che consente di vendere e avviare un programma partner completo all’interno del proprio store. Combina link di affiliazione classici, codici referral, coupon sconto, commissioni, payout, fraud prevention di base, reporting e un pannello partner moderno.

Dal punto di vista commerciale, non è solo un componente aggiuntivo per link referral, ma un livello partner completo per Magento 2, che può essere offerto come:

• modulo standalone,
• elemento dell’implementazione dello store,
• parte di un pacchetto growth / performance,
• base per un programma più avanzato di partner e ambassador del brand.

In pratica è una soluzione che risponde alle esigenze reali degli store che chiedono:

• programma di affiliazione in Magento 2,
• codici sconto per partner,
• liquidazione delle commissioni,
• pannello partner,
• prontezza per la vendita e l’utilizzo in produzione.