1. O que é este módulo

O módulo expande o Magento 2 com um sistema de afiliados completo que funciona diretamente dentro da loja. Isto significa que o proprietário da loja gere parceiros, comissões, liquidações e materiais promocionais a partir do seu próprio painel de administração, enquanto os parceiros utilizam o seu próprio dashboard na conta de cliente.

Na prática, o módulo permite implementar vários modelos de colaboração em simultâneo:

• programa de afiliados clássico baseado em links de tracking,
• programa de recomendações baseado em códigos individuais de parceiros,
• modelo híbrido: link de afiliado mais código de desconto,
• programa de parceiros para clientes da loja, agências, implementadores e criadores.

2. Principal valor de negócio

O maior valor do módulo é combinar vendas, atribuição, liquidações e gestão de parceiros num único lugar. A loja não precisa de manter um sistema de afiliados externo, exportar encomendas manualmente nem liquidar parceiros em folhas de cálculo.

O módulo oferece ao proprietário da loja:

• um novo canal de vendas,
• controlo sobre as regras de colaboração,
• gestão transparente de comissões e pagamentos,
• relatórios claros sobre a eficácia dos afiliados,
• possibilidade de lançar o programa em segurança também numa loja de média e grande escala.

O parceiro recebe:

• o seu próprio código de recomendação,
• o seu próprio link de afiliado,
• um painel pronto para monitorizar atividades,
• visibilidade sobre comissões e payouts,
• possibilidade de utilizar materiais promocionais e banners.

3. A quem se destina o módulo

O módulo é adequado para lojas que pretendem construir uma rede de parceiros de vendas sem recorrer a plataformas externas de afiliados ou que pretendem manter controlo total sobre os dados e o processo de liquidação.

Funciona especialmente bem em projetos em que o programa de afiliados deve ser gerido por:

• clientes que recomendam a loja a conhecidos,
• criadores digitais,
• bloggers e publishers,
• especialistas e consultores,
• parceiros de implementação,
• software houses e agências,
• revendedores e comerciais B2B,
• embaixadores da marca e comunidades.

4. Principais funcionalidades do módulo

4.1. Registo de afiliado

O módulo disponibiliza um formulário de candidatura ao programa de afiliados. O cliente pode candidatar-se autonomamente ao programa, fornecendo dados básicos de contacto, o endereço do website ou canal e uma breve informação sobre a promoção planeada.

Depois de enviar o formulário:

• é criada uma conta de afiliado,
• é gerado um referral_code único,
• o estado da candidatura é definido como Pending,
• o administrador pode receber uma notificação sobre a nova candidatura,
• o cliente pode receber a confirmação de receção da candidatura.

4.2. Aprovação do parceiro

O administrador pode aprovar o afiliado a partir do painel Magento. Após a aprovação:

• o estado do parceiro muda para Active,
• o parceiro pode utilizar plenamente o programa,
• é possível ativar o cupão de afiliado,
• o cliente pode receber uma mensagem sobre a aprovação da participação.

4.3. Link de afiliado

Cada afiliado recebe o seu próprio link de afiliado baseado em referral_code. O link funciona através de um controlador de tracking e regista a atribuição da visita. Depois do clique, o sistema pode:

• guardar a afiliação num cookie,
• criar um registo de visita,
• criar um registo de atribuição,
• associar uma encomenda posterior a um afiliado específico.

4.4. Código de afiliado e cupão de desconto

O módulo também suporta o modelo em que referral_code pode funcionar como código de desconto no carrinho.

O administrador pode definir na conta do afiliado o campo:

• Affiliate Coupon Discount (%)

Se o valor for superior a zero, o sistema:

• sincroniza a regra nativa Cart Price Rule do Magento,
• define o código do cupão igual a referral_code,
• aplica um desconto percentual no carrinho,
• trata a utilização deste código como a fonte de afiliação da encomenda.

Assim, o afiliado pode promover:

• um link de afiliado normal,
• apenas o código de desconto,
• a combinação de ambos os mecanismos em simultâneo.

Esta é uma das funcionalidades de vendas mais práticas do módulo, porque muitos proprietários de lojas esperam que o parceiro não só encaminhe tráfego, mas também ofereça ao cliente um benefício de preço concreto.

4.5. Atribuição de encomendas

O módulo consegue atribuir uma encomenda a um afiliado com base em:

• clique num link de afiliado,
• atribuição ativa guardada na sessão ou cookie,
• utilização de um código de afiliado no carrinho,
• cliente autenticado associado a uma atribuição ativa.

Ao nível da encomenda são guardados os dados:

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

Isto permite reportar a origem da venda diretamente em quote e sales_order.

4.6. Cálculo de comissões

A comissão é criada automaticamente para a encomenda afiliada. No modelo atual:

• a comissão é calculada percentualmente sobre o subtotal da encomenda,
• a taxa predefinida provém da configuração do módulo,
• o sistema evita a duplicação de comissões para a mesma encomenda e afiliado,
• o resultado é guardado na tabela de comissões e na encomenda.

Os estados de comissão suportados incluem, entre outros:

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

4.7. Hold period e aprovação automática

O módulo suporta um período de retenção da comissão. Isto significa que a comissão não tem de ficar imediatamente pronta para pagamento. Pode permanecer em estado pendente durante um período definido e só depois do fim desse período ser aprovada automaticamente pelo cron.

Esta solução é especialmente importante em caso de:

• risco de devoluções,
• verificação manual de encomendas,
• modelos de venda com finalização diferida,
• necessidade de proteger o programa contra abusos.

4.8. Pagamentos para afiliados

O parceiro pode apresentar um pedido de pagamento se o limite mínimo tiver sido cumprido e tiver saldo aprovado suficiente.

O workflow de payouts inclui:

• submissão de payout request,
• atribuição de comissões ao payout,
• alteração do estado da comissão para ready_for_payout,
• marcação do pagamento como pago,
• alteração dos estados das comissões para paid.

Assim, o proprietário da loja pode gerir pagamentos de forma organizada e auditável.

4.9. Fraud prevention

O módulo possui uma camada antifraude básica que ajuda a eliminar os abusos mais óbvios.

Isto inclui, entre outros:

• bloqueio de self-referral,
• marcação de comissões como rejeitadas quando é detetado abuso,
• gestão de casos de fraude,
• registo dos motivos de rejeição,
• vista separada de fraud cases no lado do administrador.

Além disso, o módulo suporta:

• cancelamentos de encomendas,
• chargebacks,
• reembolsos através de creditmemo,
• alteração dos estados das comissões após devoluções.

4.10. Notificações

O módulo tem o seu próprio sistema de enfileiramento e processamento de notificações. Pode guardar eventos operacionais e enviar mensagens de e-mail.

Os casos suportados incluem, entre outros:

• nova candidatura de afiliado,
• confirmação de receção da candidatura,
• aprovação de afiliado,
• eventos de comissão,
• payouts,
• fraud alerts.

4.11. Painel do afiliado

O parceiro utiliza um dashboard avançado na conta de cliente Magento. O dashboard não é apenas uma lista de comissões, mas um painel operacional completo.

No painel do afiliado estão disponíveis:

• estado de participação no programa,
• código de recomendação,
• link de afiliado completo,
• caminho de destino predefinido,
• resumo de comissões,
• histórico de comissões,
• acesso a payouts,
• conteúdos das regras de colaboração,
• snippets promocionais prontos,
• pré-visualização de banner,
• gerador de banner AI.

4.12. Gerador de banner AI

O módulo inclui uma funcionalidade assistida por AI que permite ao afiliado preparar um banner promocional pronto com base num briefing.

O utilizador pode fornecer:

• briefing textual,
• direção visual,
• cores,
• estilo,
• URL opcional de imagem,
• target link opcional.

O sistema envia para a camada AI:

• briefing do utilizador,
• referral link,
• target path,
• requisitos técnicos relativos ao formato da resposta.

O HTML do banner gerado pode ser guardado na conta do afiliado e utilizado pelo parceiro como material promocional pronto.

4.13. Relatórios

O módulo suporta relatórios e exportações CSV para áreas-chave do programa:

• comissões,
• payouts,
• fraud cases,
• insights AI.

Isto facilita tanto a gestão diária do programa como a análise da eficácia dos parceiros.

5. Painel de administração

O módulo expande o painel de administração Magento com a configuração e gestão do programa de afiliados.

O administrador tem acesso a:

• definições globais do programa,
• definições de comissão,
• definições de payouts,
• definições do portal do afiliado,
• definições de notificações,
• definições de fraude,
• definições de AI,
• definições de relatórios.

Além disso, no painel estão disponíveis secções operacionais:

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

Na lista de clientes e na edição do cliente são visíveis dados de afiliação, tais como:

• participação no programa,
• estado do afiliado,
• saldo do afiliado,
• código de recomendação,
• percentagem de desconto do cupão de afiliado.

6. Como funciona a afiliação na prática

6.1. Cenário do link de afiliado

1. O parceiro recebe o seu link.
2. O cliente clica no link e chega à loja.
3. O sistema guarda a visita e a atribuição.
4. O cliente faz uma encomenda.
5. A encomenda é atribuída ao afiliado.
6. É criada uma comissão.
7. Depois do hold period, a comissão pode ser aprovada.
8. Após cumprir as condições, o parceiro pode apresentar um pedido de pagamento.

6.2. Cenário do código de afiliado no carrinho

1. O parceiro publica o seu código de afiliado.
2. O cliente introduz o código no carrinho.
3. O Magento aplica o desconto da regra de carrinho.
4. O módulo reconhece o código como código do afiliado.
5. A encomenda é atribuída ao afiliado.
6. É criada uma comissão de acordo com as regras do programa.

6.3. Cenário híbrido

O cliente pode primeiro entrar na loja através de um link de afiliado e depois utilizar o código de desconto do afiliado. Este modelo permite combinar tracking clássico com benefícios para o cliente final.

7. Áreas de segurança

O módulo foi preparado a pensar na implementação em produção, por isso inclui:

• registos de auditoria,
• gestão de devoluções e cancelamentos,
• bloqueio de self-referral,
• fila de notificações,
• mecanismos que limitam a duplicação de comissões,
• armazenamento seguro da configuração AI,
• limitação dos dados enviados para a camada AI,
• possibilidade de diagnóstico de erros de integração.

8. Integração com AI

A camada AI no módulo é opcional e não bloqueia o funcionamento do programa de afiliados básico. Pode ser utilizada para:

• assistente do afiliado,
• geração de insights,
• geração de banners,
• retrieval de conhecimento de produto através de vector_store_id.

O módulo não precisa de manter a sua própria base de produtos para AI se a loja já utilizar um módulo externo de gestão de conhecimento de produto e Vector Store.

9. Aplicações de vendas

O módulo pode ser vendido como solução para vários tipos de projetos:

• lojas B2C com programa de recomendações,
• lojas premium que pretendem construir uma rede de embaixadores da marca,
• negócios B2B com programa para parceiros comerciais,
• lojas digitais e de software,
• implementações de agência em que o cliente precisa de um programa de parceiros completo sem SaaS externo.

Argumentos de venda especialmente fortes são:

• controlo total sobre os dados,
• ausência de subscrição de uma plataforma externa de afiliados,
• integração com Magento 2 sem intermediários,
• suporte para links e cupões de afiliado,
• painel de parceiro pronto,
• possibilidade de expansão futura com AI.

10. Principais vantagens do módulo

As principais vantagens desta solução são:

• funciona diretamente no Magento 2,
• suporta tanto links como códigos de afiliado,
• gere cupões de desconto associados ao afiliado,
• permite gerir parceiros a partir do cliente Magento,
• tem um workflow real de comissões e payouts,
• inclui segurança básica e auditoria,
• possui um dashboard de afiliado moderno,
• está pronto para evoluir com novas funcionalidades enterprise.

11. Requisitos de sistema

O módulo destina-se a:

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

Requer módulos Magento compatíveis relacionados com:

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

12. Âmbito de implementação

O módulo pode ser implementado por etapas:

• início com links de afiliado e comissões,
• expansão com payouts,
• expansão com cupões de afiliado,
• expansão com AI e content para afiliados,
• desenvolvimento adicional com regras de comissão mais avançadas e fraud scoring.

Isto significa que é adequado tanto para implementações MVP como para o desenvolvimento a longo prazo de um programa de parceiros.

13. Resumo

Kowal_Affiliate é um módulo de afiliados maduro para Magento 2 que permite vender e lançar um programa de parceiros completo dentro da própria loja. Combina links de afiliado clássicos, códigos de recomendação, cupões de desconto, comissões, payouts, fraud prevention básico, relatórios e um painel de parceiro moderno.

Do ponto de vista comercial, não é apenas um complemento para links de recomendação, mas uma camada completa de parceiros para Magento 2, que pode ser oferecida como:

• módulo standalone,
• elemento de implementação da loja,
• parte de um pacote growth / performance,
• base para um programa mais avançado de parceiros e embaixadores da marca.

Na prática, é uma solução que responde às necessidades reais de lojas que procuram:

• programa de afiliados em Magento 2,
• códigos de desconto para parceiros,
• liquidação de comissões,
• painel de parceiro,
• prontidão para venda e operação em produção.