DF Samples: encomenda de amostras de produto (PrestaShop 8 e 9)

Apresentação

O DF Samples acrescenta às páginas de produto um botão para encomendar uma amostra. A amostra pode ser grátis ou custar alguns euros, para o produto ou para a combinação escolhida pelo cliente. O módulo cria um produto-amostra oculto para cada produto inscrito, bloqueia a quantidade em 1, aplica limites por cliente ao conteúdo do carrinho, mede a conversão de amostra em compra e envia um email de follow-up com um cupão de desconto opcional.

O módulo é compatível com PrestaShop 8.0 a 9.x, multiloja e multilíngue, e não usa nenhum override do core. Esta documentação refere-se à versão 1.1.0.

Instalação

1. No back-office, vá a Módulos > Gestor de módulos.
2. Clique em Carregar um módulo e largue o ficheiro dfsamples.zip.
3. Abra Catálogo > Samples (DF): nesta página estão a lista de produtos, o painel e as definições.

Na instalação, o módulo cria:

• três tabelas: dfsamples_product, dfsamples_order e dfsamples_cart;
• uma categoria Samples desativada, sob Início, acessível a todos os grupos de clientes, que vai receber os produtos-amostra;
• as definições predefinidas e um token de segurança para a tarefa cron;
• o separador Catálogo > Samples (DF);
• uma cópia do modelo de email inglês para cada idioma instalado que não tenha um.

Regista-se em 12 hooks, entre os quais displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder e actionOrderStatusPostUpdate.

Atualizar a partir da versão 1.0.0

Carregue o novo ZIP por cima do anterior no gestor de módulos. O script de atualização:

• adiciona a tabela dfsamples_cart e as novas colunas;
• regista os novos hooks;
• cria a categoria de amostras e move para lá os produtos-amostra existentes;
• muda-lhes o nome para o novo formato e adiciona as imagens em falta (no PrestaShop 9, a versão 1.0.0 não copiava a imagem);
• mantém os produtos inscritos, as estatísticas e o histórico de follow-ups.

Se um passo falhar, o botão Resync sample products, no topo da página do módulo, volta a sincronizar todos os produtos-amostra.

Adicionar um produto ao programa de amostras

1. Abra Catálogo > Samples (DF) e clique em Add a product.
2. Pesquise o produto por nome ou referência e selecione-o. Os produtos já inscritos e os produtos-amostra ficam excluídos dos resultados.
3. Introduza o Sample price (tax incl.), o preço da amostra com IVA. Introduza 0,00 para uma amostra grátis.
4. Defina o Max per customer, o máximo deste produto por cliente no período móvel (0 = ilimitado).
5. Ative Sample per option se o produto tiver combinações e o cliente tiver de escolher a sua (ver abaixo).
6. Guarde.

O que o módulo faz ao guardar

O módulo cria um produto-amostra oculto, ou atualiza o existente:

• nome no formato “Sample: Nome do produto” (Échantillon, Muestra, Muster, Campione nos idiomas traduzidos);
• referência no formato SMPL seguido do ID do produto de origem;
• preço sem IVA calculado a partir do preço introduzido e da regra de impostos do produto de origem;
• imagem de capa do produto de origem copiada para todos os formatos de imagem;
• categoria predefinida: a categoria de amostras;
• visibilidade “em lado nenhum”: o produto não aparece nas listagens nem na pesquisa;
• encomendas permitidas sem stock, para nunca bloquear um pedido;
• peso retirado da definição global, usado pelas transportadoras.

Se depois alterar o preço, a opção de combinação, o peso global ou o estado ativo, o produto-amostra é sincronizado de novo. Se foi eliminado manualmente do catálogo, é recriado na próxima gravação.

Amostra por combinação

Com Sample per option ativo, o cliente escolhe a combinação na página de produto como numa compra normal e clica no botão para encomendar uma amostra dessa combinação.

• A combinação fica registada na linha da amostra, por exemplo “Formato: A4, Papel: Couché 300 g”. Aparece num campo de personalização do carrinho, da encomenda, da fatura e do email de follow-up.
• Cada combinação ocupa uma linha própria. A mesma combinação não pode ser adicionada duas vezes.
• O máximo por cliente do produto é contado por combinação.
• O preço da amostra é o mesmo para todas as combinações do produto.

Definições

As definições estão por baixo da lista de produtos, na página Catálogo > Samples (DF).

General settings (definições gerais)

• Button position: por baixo do botão de adicionar ao carrinho (displayProductActions), no bloco de informações adicionais (displayProductAdditionalInfo) ou apenas num local personalizado (displayDfSamplesButton, ver a secção seguinte).
• Default sample price (tax incl.): valor sugerido ao adicionar uma amostra.
• Sample weight: em quilogramas, aplicado a todos os produtos-amostra, usado para os portes.
• Require customer account: ativo por predefinição. Os limites por cliente só podem ser aplicados de forma fiável a clientes identificados.
• Customer group discounts on samples: aplicar (comportamento predefinido do PrestaShop) ou não aplicar. Ver “Preços e descontos de grupo”.
• Samples category: categoria predefinida de todos os produtos-amostra. Mantenha-a desativada. Se escolher outra, as amostras existentes são movidas para lá.
• Redirect sample pages: ativo por predefinição. Um visitante que chega à página de um produto-amostra é redirecionado com 301 para o produto de origem.
• Conversion counted on: apenas a compra do produto amostrado, ou qualquer compra posterior.

Limits (limites)

• Max samples per cart: 0 = ilimitado.
• Max samples per customer per window: todos os produtos-amostra em conjunto, 0 = ilimitado.
• Rolling window: período móvel em dias, 30 por predefinição. Com 0, os limites por cliente aplicam-se a todas as encomendas anteriores, sem limite de tempo.

Automatic follow-up (follow-up automático)

• Enable follow-up emails: ativa os emails de follow-up.
• Delay after sample order: em dias, 14 por predefinição.
• Only customers subscribed to the newsletter: ative se a sua base legal para emails comerciais for o consentimento.
• Include a discount voucher: é gerado um cupão nominativo de utilização única para cada follow-up.
• Voucher amount: em percentagem, 10 por predefinição.
• Voucher validity: em dias, 30 por predefinição.

O URL da tarefa cron aparece nesta secção e no painel.

Mostrar o botão com Creative Elements ou um tema personalizado

Quando a página de produto é construída com um page builder, os hooks nativos nem sempre são apresentados, ou não onde quer. O módulo fornece um hook dedicado, displayDfSamplesButton.

1. Na definição Button position, escolha Custom placement only (displayDfSamplesButton). O botão deixa de ser acrescentado aos hooks nativos, o que evita que apareça duas vezes.
2. Com Creative Elements: no modelo da página de produto, adicione o widget Module no local pretendido e escolha o módulo DF Samples e o hook displayDfSamplesButton.
3. Num tema personalizado: acrescente {hook h='displayDfSamplesButton'} ao template da página de produto, por exemplo templates/catalog/product.tpl.

Seja qual for o local, o botão acompanha a combinação selecionada e atualiza-se quando o cliente a muda.

Preços e descontos de grupo

O preço da amostra é independente do produto de origem: os preços por quantidade, os preços específicos e a quantidade mínima do produto de origem não se aplicam. Só uma regra de preço de catálogo dirigida a todos os produtos sem distinção se aplicaria também às amostras.

O desconto de um grupo de clientes (Clientes > Grupos, por exemplo -15 % para revendedores) aplica-se por predefinição a todos os produtos, amostras incluídas. Com Do not apply: samples keep their price, o módulo exclui os produtos-amostra do desconto de cada grupo: os revendedores pagam o preço definido para a amostra e o desconto continua a aplicar-se ao resto do catálogo. Os grupos criados mais tarde são tidos em conta automaticamente.

O botão mostra o preço que o cliente autenticado vai pagar, com desconto de grupo e IVA incluídos.

Limites e controlo do carrinho

As regras são verificadas sempre que o carrinho é guardado, e não apenas ao clicar no botão. Uma adição pelos botões + e – da página do carrinho, por um URL direto, por “Encomendar novamente” ou pela fusão de carrinhos no login passa pelos mesmos controlos:

1. as linhas de amostras desativadas são removidas;
2. os duplicados são removidos (mesma amostra, ou mesma combinação no modo combinação);
3. a quantidade de cada linha volta a 1;
4. é aplicado o máximo por carrinho;
5. são aplicados o máximo por produto e o máximo global por cliente no período móvel.

Quando uma linha tem de sair, é removida a mais recente. O cliente vê uma mensagem na página do carrinho ou da encomenda. As encomendas canceladas, reembolsadas ou com erro de pagamento não contam para os limites. Os carrinhos criados por um funcionário no back-office não estão sujeitos aos limites.

Configurar a tarefa cron

Os follow-ups são enviados por uma tarefa cron. Agende de hora a hora o URL indicado nas definições. Exemplo de crontab:

0 * * * * wget -q -O /dev/null "https://a-sua-loja.pt/module/dfsamples/cron?token=O_SEU_TOKEN"

Cada execução processa até 50 encomendas e devolve um resumo JSON: processed, sent, skipped, waiting e retry.

Regras aplicadas pela tarefa cron

• Um único email por encomenda, mesmo que contenha várias amostras. Lista os produtos testados e contém no máximo um cupão.
• Só são consideradas as amostras não convertidas e sem follow-up, depois de decorrido o prazo.
• A encomenda da amostra tem de ter atingido um estado pago, enviado ou entregue. Uma encomenda ainda a aguardar pagamento é revista mais tarde e descartada se continuar por pagar 60 dias depois da data prevista do follow-up.
• As encomendas canceladas, reembolsadas ou com erro de pagamento são ignoradas.
• Uma amostra cujo produto foi comprado na mesma encomenda não recebe follow-up.
• Com a opção newsletter ativa, os clientes não inscritos não recebem follow-up.
• Se o envio falhar, o módulo tenta de novo nas execuções seguintes, no máximo três vezes e com pelo menos seis horas de intervalo. O cupão gerado para um email que não saiu é eliminado.
• Duas execuções simultâneas não podem enviar o mesmo email: cada encomenda é reservada antes do processamento.

Acompanhamento de conversão

Na validação de uma encomenda com uma amostra, o módulo regista o cliente, o seu email, o produto de origem, a combinação, o idioma e a loja.

Quando esse cliente faz uma encomenda posterior, as amostras correspondentes são marcadas como convertidas:

• no modo produto (predefinido): se a encomenda contiver o produto de que recebeu a amostra;
• no modo qualquer compra: assim que a encomenda contiver um produto real.

A conversão só é contada quando a encomenda de compra atinge um estado validado (pagamento aceite, por exemplo). Uma encomenda paga por transferência é, portanto, contada quando o pagamento é recebido. Uma compra na mesma encomenda que a amostra não é uma conversão.

Painel

O painel por cima da lista de produtos mostra:

• Samples ordered: número de linhas de amostra registadas;
• Conversions: número de amostras seguidas de uma compra, e taxa de conversão;
• Revenue from conversions: total com IVA das encomendas de conversão, convertido para a moeda predefinida;
• Pending follow-ups: follow-ups pendentes.

A lista de produtos mostra também, por produto, o número de amostras encomendadas, o número de conversões e se o modo combinação está ativo.

Emails de follow-up

Os modelos estão na pasta mails do módulo, em francês, inglês, espanhol, alemão e italiano, em versão HTML e texto (dfsamples_followup). Para o português, o modelo inglês é copiado na instalação para mails/pt/: traduza os dois ficheiros dessa pasta, mantendo as variáveis entre chavetas.

Variáveis disponíveis:

• {firstname} e {lastname};
• {product_name}: o produto ou produtos testados, separados por vírgulas;
• {product_link}: link para a página do primeiro produto;
• {voucher_block}: cupão formatado para a versão HTML, vazio se o cupão estiver desativado;
• {voucher_text}: o mesmo conteúdo para a versão texto;
• {shop_name}.

Cupões de desconto

Com a opção ativa, cada follow-up cria uma regra de carrinho do PrestaShop:

• código no formato SMPL seguido de oito caracteres aleatórios;
• reservado ao destinatário, de utilização única;
• desconto em percentagem, validade configurável.

Os cupões aparecem em Catálogo > Descontos > Regras de carrinho.

Catálogo, sitemap e feeds de produtos

Os produtos-amostra têm a visibilidade “em lado nenhum” e ficam na categoria de amostras desativada. Não aparecem nas listagens, na pesquisa nem nos blocos de destaque, e a sua página redireciona para o produto de origem. A maioria dos módulos de sitemap e de feeds ignora estes produtos. Se o seu os incluir, exclua nas definições dele a categoria de amostras ou as referências que começam por SMPL.

Compatibilidade com o checkout

O módulo não intervém no processo de encomenda: uma amostra é uma linha de produto normal. Funciona com o checkout nativo e com os checkouts numa só página que usam os passos nativos do PrestaShop. A mensagem de remoção de uma amostra aparece nas páginas do carrinho e da encomenda.

Desinstalação

A desinstalação elimina as tabelas, as definições e o separador do módulo. Os produtos-amostra são desativados, não eliminados, e a categoria de amostras é mantida, para que o histórico de encomendas continue coerente. Uma reinstalação reutiliza esta categoria. Pode eliminar estes produtos e a categoria manualmente se já não precisar deles.

Resolução de problemas

O botão não aparece na página de produto

Confirme que o produto está inscrito e ativo em Catálogo > Samples (DF). Depois mude a posição do botão: alguns temas não apresentam displayProductActions. Com um page builder, use o hook displayDfSamplesButton.

Aparece uma mensagem em vez do botão

Uma mensagem sobre o limite de amostras do produto significa que o cliente atingiu o seu máximo no período móvel. Uma mensagem sobre o máximo de amostras por encomenda significa que o máximo por carrinho foi atingido. Ajuste os limites se necessário.

Os produtos-amostra não têm imagem

Acontecia com as amostras criadas pela versão 1.0.0 no PrestaShop 9. Clique em Resync sample products: as imagens em falta são adicionadas.

O preço apresentado não é o esperado

O preço é introduzido com IVA e convertido segundo a regra de impostos do produto de origem. Para um cliente de um grupo com desconto, verifique a definição “Customer group discounts on samples”. Uma regra de preço de catálogo global também se aplica às amostras.

Os follow-ups não são enviados

Abra o URL da tarefa cron num navegador e leia o resumo JSON. enabled: false significa que os follow-ups estão desativados. waiting conta as encomendas de amostras ainda por pagar. Verifique também o prazo, a opção newsletter e a configuração de email da loja (Parâmetros avançados > Email).

Uma amostra desaparece do carrinho

É o controlo do carrinho: duplicado, máximo por carrinho ou limite do cliente atingido. O cliente vê uma mensagem na página do carrinho.