DataFirefly Affiliate Program: programa de afiliados para PrestaShop

Instalação

Instale o módulo em Módulos > Gestor de módulos > Carregar um módulo enviando o ficheiro ZIP, ou copie a pasta dfaffiliate para o diretório /modules/ da sua loja e clique em Instalar.

Na instalação, o módulo cria as suas tabelas, guarda as definições predefinidas e acrescenta na secção Vender um menu Afiliação com cinco entradas: Afiliados, Comissões, Extratos e pagamentos, Regras de comissão e Definições. O botão Configurar do gestor de módulos abre a página de definições, que começa por um resumo do programa.

Para passar da versão 1.0.0 para a 1.1.0, basta carregar o novo ZIP: o script de atualização acrescenta as novas definições e hooks sem alterar afiliados, comissões ou extratos existentes.

Primeiras definições

Verifique pelo menos estes pontos antes de convidar os primeiros afiliados:

• Valor de comissão predefinido: 10 % dos produtos sem IVA na instalação, ou um montante fixo por encomenda.
• Validade do cookie: 30 dias por predefinição, prazo entre o clique e a encomenda.
• Aprovar a comissão em e Rejeitar a comissão em: os estados de encomenda que confirmam o pagamento e os que anulam (cancelada, reembolsada, erro de pagamento).
• Período de retenção: 30 dias por predefinição. Uma comissão aprovada só entra num extrato depois deste prazo, para cobrir devoluções.
• Pagamento mínimo: abaixo dele, o saldo passa para o mês seguinte.
• Denominação social, IBAN e BIC da empresa: indispensáveis para gerar o ficheiro de transferência SEPA.

Rastreamento e atribuição

Os links de rastreamento

Cada afiliado tem um código. Dois tipos de links transportam-no:

• o parâmetro de rastreamento, acrescentado a qualquer endereço da loja: ?aff=CODE. O nome do parâmetro muda-se nas definições, por exemplo para ref;
• os links curtos que o afiliado cria na sua área a partir do endereço de um produto, de uma categoria ou de qualquer página. Redirecionam para a página escolhida e contam cliques e encomendas por link.

No clique, um cookie assinado (dfaff_ref) regista o afiliado. A assinatura impede que um visitante o altere. Os robôs de pesquisa, os navegadores automatizados e os cliques do próprio afiliado não contam, e o mesmo visitante só é contado uma vez a cada 30 minutos. Nenhum endereço IP é guardado em claro.

Ordem de atribuição de uma encomenda

1. O código de desconto pessoal de um afiliado usado na encomenda, mesmo sem clique.
2. O link ou o cookie: o carrinho é ligado ao afiliado durante a visita, o que cobre também os pagamentos confirmados mais tarde pelo banco.
3. Um cliente já trazido por esse afiliado, se a definição Comissões de clientes recorrentes for superior a 0 dias.

O modelo de atribuição decide o que acontece quando um visitante clica nos links de dois afiliados: último clique (predefinido), ganha o último afiliado visitado; primeiro clique, o primeiro mantém a venda até o cookie expirar.

Proteções

• Um afiliado não recebe comissão pelas suas próprias encomendas, reconhecidas pela conta de cliente e pelo endereço de e-mail.
• Apenas novos clientes: só a primeira encomenda de um cliente gera comissão.
• Montante mínimo de encomenda: produtos sem IVA após descontos, 0 para nenhum mínimo.

Comissões

Cálculo

A base é o montante dos produtos sem IVA. Com Deduzir os descontos, os vales da encomenda são retirados da base; um vale de portes grátis não a altera. Os portes nunca são incluídos. O montante é convertido para a moeda predefinida da loja.

A taxa aplicada é, por esta ordem: a comissão específica do afiliado, se existir; caso contrário, a taxa do programa. Em percentagem, as regras por produto e depois por categoria substituem a taxa linha a linha. Em montante fixo é criada uma única comissão por encomenda, e uma única quando o PrestaShop divide um carrinho em várias encomendas para várias transportadoras.

Regras por categoria e por produto

O separador Regras de comissão fixa uma percentagem para uma categoria ou um produto, por exemplo 3 % em eletrónica e 15 % em acessórios. Uma regra de produto prevalece sobre uma regra de categoria. Para as categorias, o módulo verifica primeiro a categoria predefinida do produto e depois a melhor das restantes. Uma taxa de 0 exclui os produtos das comissões. As regras aplicam-se apenas às comissões em percentagem.

Ciclo de vida

• Na encomenda, a comissão é criada como Pendente.
• Quando a encomenda atinge um estado de aprovação, passa a Aprovada e a data de aprovação inicia o período de retenção.
• Quando a encomenda passa a um estado de cancelamento, fica Rejeitada.
• Uma nota de crédito parcial reduz a comissão na proporção do montante de produtos reembolsado.
• Se a comissão já constar de um extrato ou tiver sido paga, o módulo já não a altera: cria um ajuste negativo deduzido do extrato seguinte, sem período de retenção. Um segundo estado de cancelamento na mesma encomenda não cria nova dedução.

Comissões manuais

No separador Comissões, Adicionar uma comissão manual credita ou debita um afiliado (montante negativo para uma dedução), com uma nota visível na sua área. Estas linhas seguem o mesmo ciclo de extrato que as comissões de encomenda.

Afiliados

Candidaturas

A página pública do programa apresenta as suas condições (taxa, duração do cookie, pagamento mínimo), três etapas e perguntas frequentes geradas a partir das definições. O texto de apresentação edita-se nas definições, em cada idioma. Se escolher uma página CMS com as condições do programa, o candidato tem de a aceitar.

O candidato tem de ter sessão iniciada numa conta de cliente. Indica onde publica, descreve o seu público e, opcionalmente, a sua empresa. Por predefinição, cada candidatura aguarda a sua aprovação e o e-mail de notificação recebe uma mensagem. Com Aprovar candidaturas automaticamente, a conta fica ativa de imediato.

Ficha do afiliado

A ficha começa por um resumo (cliques, encomendas, comissões pendentes, devidas e pagas) e pelo link de rastreamento para copiar, seguidos de três blocos:

• Identidade e canal: nome, e-mail, site, público, estado e nota interna. Passar o estado a Aprovado envia o e-mail «A sua conta de afiliado está ativa».
• Rastreamento e comissão: código de afiliado, comissão específica, duração própria do cookie, código de desconto pessoal. Se o código ainda não existir e indicar uma percentagem de desconto, a regra de carrinho é criada automaticamente, limitada a uma utilização por cliente.
• Dados de pagamento: transferência SEPA ou PayPal, titular, IBAN, BIC, e-mail PayPal.

Pode criar um afiliado sem conta de cliente: recebe os extratos por e-mail mas não tem área online. Se uma conta de cliente usar o mesmo e-mail, fica ligada automaticamente.

Um afiliado com comissões em aberto ou um extrato por pagar não pode ser eliminado: suspenda-o ou regularize primeiro o saldo.

O que o afiliado vê

• A minha conta: um bloco «Área de afiliado», ou «Torne-se afiliado» para um cliente que ainda não o é.
• Resumo: gerador de links, faixa de números (cliques, encomendas, conversão, pendente, aprovado, pago), gráfico dos últimos 30 dias, condições e links recentes.
• Os meus links: todos os links curtos com cliques, encomendas, copiar e eliminar.
• Comissões: data, referência de encomenda mascarada, origem, base, comissão, estado, filtro por estado e mês de pagamento previsto. Nenhum dado de cliente é mostrado.
• Extratos: um extrato por mês, para consultar e imprimir em PDF.
• Dados de pagamento: escolha entre transferência e PayPal, IBAN verificado pelos dígitos de controlo e mostrado mascarado. Um ponto e um aviso assinalam dados em falta.
• Página de produto: uma caixa «O seu link de afiliado», visível apenas para o afiliado com sessão iniciada, dá o link do produto e a taxa ganha.

Extratos e pagamentos

Criação dos extratos

Um extrato agrupa, para um afiliado e um mês, as comissões aprovadas criadas antes do fim do mês cujo período de retenção terminou, mais os ajustes negativos. Se o total for inferior ao pagamento mínimo, nada é criado e o saldo transita.

Duas formas de criar os extratos:

• Extratos e pagamentos > Criar os extratos mensais: escolha o mês, verifique os montantes por afiliado na pré-visualização e crie os extratos enviando os e-mails.
• O URL cron, mostrado no resumo das definições. Chame-o uma vez por dia: entre o dia 1 e o dia 5 do mês cria os extratos do mês anterior. Acrescente &period=AAAA-MM para forçar um mês específico. Está protegido por um token.

Pagar aos afiliados

Na lista de extratos, selecione os que vai pagar e use a ação em massa pretendida:

• Exportar ficheiro de transferência SEPA (XML): ficheiro pain.001.001.03 a importar no seu banco, para os afiliados pagos por transferência. Requer EUR como moeda predefinida e o IBAN da empresa.
• Exportar ficheiro PayPal Payouts (CSV): para os pagamentos em lote PayPal, afiliados pagos por PayPal.
• Exportar para a contabilidade (CSV): todos os extratos selecionados, separados por ponto e vírgula.

As exportações de pagamento são recusadas, com uma mensagem que indica o extrato em causa, se um extrato selecionado já estiver pago ou se um IBAN faltar ou for inválido: um ficheiro incompleto deixaria um afiliado sem pagamento, e um extrato pago poderia ser pago duas vezes.

Depois de feita a transferência, marque os extratos como pagos, em lote ou a partir do detalhe de um extrato com a referência e a data do pagamento. As comissões correspondentes passam a Paga.

E-mails

O módulo envia quatro e-mails, traduzidos em 8 idiomas e enviados no idioma do destinatário, incluindo o formato dos montantes:

• Nova candidatura de afiliado, para o endereço de notificação.
• A sua conta de afiliado está ativa, com o link para a área de afiliado.
• Nova venda, com a comissão, a base e a taxa, nunca os dados do cliente. Desativável nas definições e por cada afiliado nos seus dados de pagamento.
• Extrato disponível, com o montante e o link para o extrato.

Os modelos estão na pasta mails/ do módulo e personalizam-se como qualquer e-mail do PrestaShop.

Back office

• Resumo (página de definições): afiliados ativos, candidaturas por analisar, cliques, encomendas e vendas em 30 dias, comissões pendentes, devidas e pagas, melhores afiliados.
• Página de encomenda: uma caixa indica o afiliado, a comissão, o seu estado e a sua origem.
• Exportações CSV das listas de afiliados e comissões, com montantes brutos prontos para uma folha de cálculo.

RGPD e eliminação de contas

O módulo regista-se no módulo RGPD oficial do PrestaShop. A exportação de dados de um cliente inclui o seu perfil de afiliado e as suas comissões. O apagamento anonimiza o afiliado (nome, e-mail, IBAN, site e público apagados, links e cliques eliminados) e mantém as comissões e extratos para a contabilidade.

Quando um funcionário elimina uma conta de cliente, o afiliado ligado é mantido sem conta online e os seus dados de pagamento permanecem.

Resolução de problemas

Nenhum clique é contado

Teste numa janela de navegação privada, sem sessão iniciada com a conta do afiliado: os seus próprios cliques são ignorados. Os navegadores automatizados são filtrados como robôs. Se a sua loja usar uma cache de página completa, uma página servida pela cache não executa PHP e o parâmetro ?aff= não é visto: use os links curtos, que passam sempre pelo PrestaShop, ou exclua o parâmetro da cache.

Uma comissão continua pendente

Verifique se o estado atual da encomenda está assinalado em Aprovar a comissão em. Se o estado foi alterado por um funcionário cujo perfil não tem a permissão Ver sobre o módulo (Parâmetros avançados > Equipa > Permissões), o PrestaShop não executou o módulo: volte a colocar a encomenda nesse estado com uma conta de administrador.

O gerador de links recusa um endereço

O gerador só aceita endereços da sua loja. Cole o endereço completo tal como aparece no navegador, no domínio da loja.

A exportação SEPA é recusada

Leia a mensagem apresentada: indica o extrato já pago ou o afiliado sem IBAN. Desmarque-o ou complete os seus dados. Verifique também se a denominação social e o IBAN da empresa estão preenchidos.

Compatibilidade

• PrestaShop 8.0 a 9.x, o mesmo ZIP cobre as duas versões.
• Multilingue e multimoeda, comissões calculadas na moeda predefinida.
• Arquitetura ModuleAdminController, sem dependências Composer.
• Módulo e e-mails traduzidos em inglês, francês, espanhol, alemão, italiano, neerlandês, polaco e português.