Recuperação de Carrinhos Abandonados em Várias Etapas: guia completo

Apresentação

O módulo Recuperação de Carrinhos Abandonados em Várias Etapas (datafireflycartrecovery) deteta os carrinhos abandonados e contacta os seus clientes com uma sequência de e-mails agendados. Cada etapa tem o seu atraso, o seu conteúdo por idioma e um cupão de desconto opcional cujo incentivo pode aumentar de uma etapa para a outra. Uma ligação assinada permite ao cliente recuperar o carrinho com um clique, com o cupão já aplicado, e o painel mede a receita realmente recuperada, etapa a etapa.

Compatibilidade

• PrestaShop 8.0 a 9.x
• PHP 8.1 a 8.3
• Loja única e multiloja (campanhas, carrinhos e estatísticas separados por loja)
• Interface: FR, EN, ES, DE, IT, PL
• Modelos de e-mail e campanha predefinida: FR, EN, ES, DE, IT, PL, NL, PT. Qualquer outro idioma instalado recebe automaticamente uma cópia editável do modelo do idioma predefinido da loja (na falta deste, o inglês).
• Compatível com o módulo RGPD oficial psgdpr
• Arquitetura PSR-4 sem Composer, sem dependências externas

Instalação

1. No back office, abra Módulos > Gestor de módulos.
2. Clique em Carregar um módulo e selecione datafireflycartrecovery.zip.
3. Clique em Configurar para definir os parâmetros gerais e a aparência dos e-mails.
4. Configure a tarefa agendada (secção seguinte) e envie a si próprio um e-mail de teste a partir de uma etapa.

Atualização a partir de uma versão anterior

Carregue o novo ZIP: os scripts de atualização são executados automaticamente.

• Para 1.3.11: auditoria completa do módulo. Em multiloja, cada loja passa a processar apenas os seus próprios envios (o cron de uma loja enviava também os das outras, com as suas ligações e o seu logótipo). Um cliente que voltou ao carrinho e saiu de novo deixa de receber duas vezes a mesma etapa. Depois de uma paragem do cron, só é enviada a etapa mais avançada. Os cupões de visitantes deixam de ser propostos aos outros visitantes no carrinho. A ligação de cancelamento da subscrição mostra uma página de confirmação (os analisadores de ligações do correio empresarial deixam de cancelar a subscrição dos clientes). As permissões dos funcionários são verificadas em cada ação do back office. O script adiciona três colunas, mantém uma única campanha ativa por loja (a que a análise já usava), corrige o nome do remetente gravado com uma barra invertida e repõe a 0 o valor dos carrinhos esvaziados. As ligações dos e-mails enviados antes da atualização continuam a restaurar o carrinho, sem início de sessão automático.
• Para 1.3.10: um carrinho esvaziado pelo cliente interrompe a sua sequência (e-mails agendados cancelados, motivo “Carrinho esvaziado pelo cliente”) e mostra 0 artigos e um valor de 0. Sem alterações na base de dados.
• Para 1.3.9: o atraso das etapas aparece no idioma do funcionário e sem casas decimais (“1 h 30 min”, “1 d 12 h”). Antes aparecia sempre a abreviatura francesa “j”. Sem alterações na base de dados.
• Para 1.3.8: corrige no PrestaShop 8 os botões do cabeçalho dos painéis (Definições, Desativar, Eliminar, Adicionar uma etapa), que se sobrepunham no mesmo sítio. Sem alterações na base de dados.
• Para 1.3.7: um carrinho eliminado no PrestaShop deixa de receber e-mails de lembrete. O script regista um novo hook. Os e-mails agendados para carrinhos já eliminados são cancelados na primeira execução do cron. Sem alterações na base de dados.
• Para 1.3.6: a pré-visualização dos e-mails mostra o modelo personalizado no tema (ver Personalizar o modelo de e-mail). Sem alterações na base de dados.
• Para 1.3.5: o cupão de lembrete deixa de ser acumulável com outro código promocional. O script regista dois novos hooks. Sem alterações na base de dados.
• Para 1.3.4: corrige uma página em branco “If no employee is assigned in the context, cart ID must be provided to this method” quando um carrinho é gravado fora da navegação (webservice, conector, webhook de pagamento, script), o botão “Enviar agora” fora da janela de envio e um desfasamento das datas de envio quando o servidor MySQL não usa o fuso horário da loja. Sem alterações na base de dados.
• Para 1.3.1: corrige o erro 500 do URL cron no PrestaShop 8. Sem alterações na base de dados.
• Para 1.3.0: adiciona a segmentação por grupos e categorias e as definições de aparência. Os e-mails passam a ter cabeçalho branco com o logótipo da loja, e o azul original mantém-se como cor de destaque. Ajuste se necessário em Aparência dos e-mails.
• Para 1.2.0: regista os novos hooks (RGPD, cabeçalhos de e-mail, novo idioma) e cria os modelos de e-mail em falta para os idiomas instalados.

Tarefa agendada (cron)

O módulo funciona com execuções regulares acionadas por um URL protegido por token. Em cada execução:

1. Análise: os carrinhos inativos para além do atraso de abandono são qualificados (segmentação, anti-repetição) e as suas etapas agendadas.
2. Envio: os e-mails devidos são enviados respeitando todas as proteções.
3. Limpeza: os cupões do módulo expirados há 7 dias e nunca utilizados são eliminados.

O URL exato, com o token, aparece no painel (botão Configurar, com cópia num clique) e na configuração do módulo:

https://A-SUA-LOJA/index.php?fc=module&module=datafireflycartrecovery&controller=cron&token=O_TOKEN

Agende uma chamada mais ou menos a cada 10 minutos:

*/10 * * * * curl -s "https://A-SUA-LOJA/index.php?fc=module&module=datafireflycartrecovery&controller=cron&token=O_TOKEN" >/dev/null 2>&1

Um bloqueio garante que apenas uma execução decorre de cada vez: duas chamadas simultâneas nunca enviam o mesmo e-mail duas vezes.

Estado do processamento

O topo do painel indica o estado da tarefa agendada: verde se a última execução automática (cron ou execução sem cron) ocorreu há menos de 30 minutos, laranja até 3 horas, vermelho para além disso ou se nunca foi executada. O botão Executar agora lança uma execução imediata e mostra o resultado: carrinhos detetados, e-mails enviados, e-mails adiados fora da janela de envio, falhas. Não põe o indicador a verde: só uma execução automática prova que o cron funciona.

Sem acesso a tarefas cron

Ative Execução sem cron do servidor na configuração do módulo. O processamento passa a ser acionado pelas visitas à loja, no máximo a cada 10 minutos, depois de a página ser enviada ao visitante: a navegação não fica mais lenta. Esta opção requer PHP-FPM ou LiteSpeed. Num servidor em mod_php, fica inativa e aparece um aviso ao gravar: crie então uma tarefa cron real.

Definições gerais

• Atraso de abandono (60 min por predefinição): inatividade a partir da qual um carrinho é considerado abandonado.
• E-mails por execução (50 por predefinição): número de e-mails processados em cada execução.
• Máximo de e-mails por carrinho (3 por predefinição): limite para todas as etapas, 0 para nenhum limite.
• Duração máxima (30 dias por predefinição): depois disso, um carrinho não convertido passa ao estado Perdido.
• Início de sessão automático pela ligação (ativo por predefinição): volta a iniciar a sessão do cliente registado que clica na ligação de restauro, durante 7 dias após o envio do e-mail, desde que o e-mail da sua conta seja ainda o endereço para o qual o lembrete foi enviado.
• E-mail e nome do remetente: se vazios, são usados os da loja. O nome não pode conter os caracteres < > ; = # { }, recusados pelo PrestaShop no envio.
• Execução sem cron do servidor: ver a secção anterior.

Aparência dos e-mails

Na configuração do módulo, o bloco Aparência dos e-mails alinha os lembretes com a sua identidade visual:

• Logótipo da loja: usa o logótipo de e-mails definido em Aparência > Tema e logótipo, caso contrário o logótipo principal. As dimensões são calculadas para uma apresentação correta no Outlook. Sem logótipo, aparece o nome da loja.
• Cor de destaque: botão, ligações, linha sob o cabeçalho e bloco do cupão.
• Fundo do cabeçalho: branco recomendado se o logótipo for escuro.

O texto sobre estas cores passa automaticamente a branco ou escuro consoante o contraste: um botão amarelo recebe texto escuro, um botão azul-marinho texto branco. O resultado é visível na pré-visualização de cada etapa.

Personalizar o modelo de e-mail

O texto de cada etapa (assunto, corpo, botão) define-se no back office. Para alterar a própria estrutura do e-mail (disposição, tipos de letra, rodapé), copie o modelo do módulo para o seu tema. O PrestaShop passa a usá-lo em vez do modelo do módulo, tanto no envio como na pré-visualização e no e-mail de teste.

themes/O-SEU-TEMA/modules/datafireflycartrecovery/mails/pt/df_cart_recovery.html
themes/O-SEU-TEMA/modules/datafireflycartrecovery/mails/pt/df_cart_recovery.txt

Para cada idioma, o PrestaShop procura no tema ativo, depois no tema pai e, por fim, no módulo. Tenta o idioma do cliente, depois o idioma predefinido da loja e, por fim, o inglês.

Mantenha as variáveis substituídas no envio:

• HTML: {body_html}, {cart_table}, {voucher_block}, {restore_url}, {unsubscribe_url}, {cta_label}, {shop_name}, {tracking_pixel}, {header_brand}, {header_bg}, {header_text}, {accent_color}, {accent_text}.
• Texto: {body_text}, {cart_text}, {voucher_text}, {restore_url}, {unsubscribe_url}, {shop_name}.

Sem {tracking_pixel}, as aberturas deixam de ser contabilizadas. Sem {unsubscribe_url}, a ligação de cancelamento desaparece, o que é um problema de conformidade. Depois de uma atualização do módulo, compare a sua cópia com o modelo do módulo para incluir uma eventual nova variável.

Campanhas e segmentação

Uma campanha agrupa uma sequência de etapas e as suas regras. O ecrã da campanha mostra as definições e, por baixo, a lista das etapas.

• Valor mínimo do carrinho: 0 para nenhum mínimo.
• Janela de envio: intervalo horário fora do qual os e-mails devidos são adiados. Pode passar da meia-noite (das 22 às 6). Início e fim iguais: envio a qualquer hora.
• Anti-repetição (em dias): um destinatário que recebeu um lembrete para outro carrinho neste período, ou com outro carrinho já em sequência, não volta a ser contactado. A regra é verificada de novo imediatamente antes de cada envio.
• Incluir visitantes: inclui ou não os clientes visitantes.
• Excluir contas B2B: exclui os clientes com empresa, SIRET ou número de IVA preenchidos.
• Grupos de clientes excluídos: nenhum e-mail para os clientes de um destes grupos (revendedores, pessoal).
• Categorias excluídas: um carrinho com pelo menos um produto destas categorias não recebe lembrete (cartões-presente, produtos de margem baixa, produtos sujeitos a receita). Um campo de pesquisa filtra a árvore.

Etapas da sequência

• Posição: ordem da etapa, única na campanha.
• Atraso após o abandono (em minutos): 60 = 1 h, 1440 = 24 h, 4320 = 72 h. Tem de aumentar com a posição: cada etapa é enviada depois da anterior.
• Assunto, texto do botão e corpo por idioma: o corpo é redigido num editor visual. Se o texto do botão ficar vazio, é usada uma etiqueta predefinida traduzida. O assunto não pode conter os caracteres < e >, recusados pelo PrestaShop no envio.
• Etapa ativa: suspende uma etapa sem a eliminar.

Variáveis

Utilizáveis no assunto, no texto do botão e no corpo. Um clique numa variável copia-a.

• {firstname}, {lastname}: nome e apelido do cliente.
• {shop_name}: nome da loja.
• {cart_total}: total do carrinho na sua moeda.
• {voucher_code}, {voucher_value}, {voucher_expiry}: código, valor (por exemplo 10 % ou 5,00 €) e data de validade do cupão. Vazias se a etapa não gerar cupão.

O corpo é inserido num modelo responsivo que acrescenta o cabeçalho, o resumo do carrinho (fotografias, combinações, total), o bloco do cupão, o botão e o rodapé com a ligação de cancelamento. É gerada uma versão de texto limpa para os clientes de e-mail que não mostram HTML.

Pré-visualização e e-mail de teste

Depois de gravar a etapa:

• O botão Pré-visualizar de cada separador de idioma (ou o ícone do olho na lista de etapas) abre o resultado final, com alternância computador / telemóvel.
• O bloco Enviar um e-mail de teste envia a etapa para o endereço e no idioma que escolher. O assunto recebe o prefixo [TEST].

Cupões de desconto

Cada etapa pode gerar um cupão no momento do envio:

• Tipo: percentagem ou valor fixo (com ou sem IVA).
• Valor (percentagem entre 0 e 100) e valor mínimo de aplicação.
• Validade em dias.
• Portes grátis, sozinhos ou combinados com o desconto.

• O cupão é de utilização única e de validade limitada. É nominativo para os clientes registados. Para os visitantes não fica associado à conta, porque o PrestaShop cria uma nova conta de visitante a cada encomenda: o código mantém-se secreto, utilizável uma única vez e nunca é proposto aos outros visitantes no carrinho.
• Sem acumulação com outro código promocional: se o cliente introduzir outro código quando há um cupão de lembrete no carrinho, ou o inverso, o código é recusado com a mensagem “Este código promocional não pode ser acumulado com outro código promocional.” e o código já presente é mantido. As regras automáticas sem código (por exemplo, portes grátis a partir de X) continuam acumuláveis.
• Progressão sem acumulação: quando uma nova etapa gera um cupão, o cupão anterior ainda não utilizado do mesmo carrinho é desativado. Só pode haver um cupão de lembrete de cada vez no carrinho: introduzir um código DFCR- válido substitui o que já lá está, e um código errado ou expirado não retira o cupão aplicado.
• Limpeza: os cupões expirados há 7 dias e nunca utilizados são eliminados automaticamente.

Restauro do carrinho com um clique

Cada e-mail contém uma ligação assinada (HMAC). Ao clicar:

• o carrinho é reconstruído e o cliente chega à página do carrinho;
• o cupão do e-mail clicado é aplicado automaticamente (um eventual cupão de lembrete anterior é retirado), exceto se o carrinho já contiver outro código promocional: nesse caso, o do cliente é mantido;
• o cliente registado volta a iniciar a sessão se a opção estiver ativa e o e-mail tiver menos de 7 dias; a morada escolhida no carrinho é mantida;
• o clique é contabilizado.

Em multiloja, as ligações apontam para a loja do carrinho, no idioma do cliente, e um carrinho só é restaurado na sua loja.

Qualquer alteração dos parâmetros da ligação invalida-a. Um carrinho já encomendado redireciona para a página inicial. Se outro cliente tiver sessão iniciada no navegador, a sessão e o carrinho dele não são alterados e o carrinho do e-mail não é restaurado.

Desenrolar de uma sequência

• Retoma: se o cliente voltar a alterar o carrinho, os lembretes pendentes são cancelados (motivo “Cliente voltou ao carrinho”). Se sair de novo, a sequência é reagendada a partir da etapa seguinte, sem reenviar uma etapa já recebida.
• Recuperação de atrasos: depois de uma paragem do cron, se várias etapas do mesmo carrinho forem devidas ao mesmo tempo, só é enviada a mais avançada. As outras são ignoradas com o motivo “Substituída pela etapa seguinte, já devida”.
• Carrinho esvaziado: se o cliente retirar todos os artigos do carrinho, a sequência termina e o carrinho mostra 0 artigos e um valor de 0.
• Carrinhos antigos: um carrinho inativo há mais de 7 dias nunca recebe lembrete. Depois de um cron parado durante muito tempo, a primeira execução não escreve, portanto, a clientes que saíram há semanas. Se o cliente voltar ao carrinho, volta a ser elegível.
• Produtos indisponíveis: se nenhum produto do carrinho puder ainda ser encomendado (sem stock e sem encomendas permitidas, produto desativado), a etapa é ignorada. As etapas seguintes mantêm-se agendadas em caso de reposição de stock.
• Falha de envio: em caso de erro SMTP, o e-mail é tentado de novo 15 e depois 30 minutos mais tarde. Após 3 falhas, passa ao estado falhado com a mensagem de erro e o cupão criado é eliminado.
• Carrinho eliminado: se o carrinho for eliminado no PrestaShop (Encomendas > Carrinhos, script de limpeza, módulo de terceiros), os seus e-mails agendados são cancelados, de imediato ou na execução seguinte do cron, e é feita uma última verificação imediatamente antes de cada envio.
• Encomenda: quando uma encomenda é validada, os lembretes restantes são cancelados. Uma encomenda criada sem passar pelo processo de checkout (importação, ERP) é detetada imediatamente antes do envio seguinte e atribuída da mesma forma.

Acompanhamento e atribuição

• Aberturas: píxel invisível em cada e-mail.
• Cliques: clique no botão ou na ligação de restauro.
• Recuperação: um carrinho só conta como Recuperado se pelo menos um e-mail de lembrete tiver sido enviado antes da encomenda. Uma encomenda feita antes de qualquer e-mail recebe o estado Encomendado sem lembrete e não entra na receita recuperada.
• Atribuição por etapa: cada carrinho recuperado é atribuído ao último e-mail enviado antes da compra.
• Encomenda dividida: quando o PrestaShop cria várias encomendas para o mesmo carrinho (transportadoras diferentes), a receita recuperada é o total de todas essas encomendas.

Painel

• Período: 7, 30 ou 90 dias.
• Indicadores: carrinhos detetados e valor abandonado, carrinhos recuperados e taxa de recuperação, e-mails enviados, taxas de abertura e de clique, e-mails a aguardar envio, receita recuperada. Os valores são convertidos para a moeda predefinida da loja. O valor abandonado é o do carrinho no momento do abandono.
• Gráfico das deteções e recuperações por dia.
• Desempenho por etapa da campanha ativa: enviados, abertos, clicados, taxa de clique, carrinhos recuperados e receita atribuída.

Carrinhos acompanhados

O separador Carrinhos lista os carrinhos acompanhados com filtro por estado, pesquisa (e-mail, nome ou número do carrinho, #123 para um carrinho específico), paginação e exportação CSV dos resultados filtrados. Cada linha mostra o cliente, o valor, o estado, o número de e-mails enviados e agendados, uma ligação para o carrinho e, se aplicável, para a encomenda no back office. O ícone de exclusão interrompe todos os lembretes de um carrinho.

Estado	Significado
Ativo	Carrinho em curso, ainda não abandonado
Lembrete em curso	Sequência agendada ou em envio
Recuperado	Encomenda feita após pelo menos um e-mail de lembrete
Encomendado sem lembrete	Encomenda feita antes de qualquer e-mail, não atribuída
Perdido	Sequência terminada ou período de acompanhamento ultrapassado
Excluído	Filtrado pela campanha (valor, visitante, B2B, grupo, categoria, anti-repetição): reavaliado se o cliente alterar o carrinho. Excluído manualmente ou carrinho eliminado no PrestaShop: definitivo
Subscrição cancelada	O cliente já não quer receber lembretes

Registo de envios

O separador Registo de envios detalha cada e-mail: data prevista e data de envio, destinatário, etapa, estado (agendado, enviado, ignorado, cancelado, falhado), abertura, clique, código de desconto e motivo (cliente voltou ao carrinho, carrinho esvaziado pelo cliente, limite atingido, produtos indisponíveis, anti-repetição, etapa substituída pela seguinte, erro SMTP, carrinho eliminado no PrestaShop…). Para um e-mail agendado, pode enviá-lo agora ou cancelá-lo. “Enviar agora” envia o e-mail de imediato, mesmo fora da janela de envio, e mostra o resultado ou o motivo do não envio.

RGPD e entregabilidade

• Cada e-mail contém uma ligação de cancelamento da subscrição. Abre uma página de confirmação: o cancelamento faz-se com o botão, para que os analisadores de ligações do correio empresarial não cancelem a subscrição dos clientes sem o seu conhecimento. O endereço entra numa lista de exclusão permanente e os envios pendentes de todos os seus carrinhos são cancelados.
• Os cabeçalhos List-Unsubscribe e List-Unsubscribe-Post permitem cancelar a subscrição com um clique no Gmail, no Yahoo e noutros serviços que o exigem para e-mails de marketing.
• Só são acompanhados os carrinhos associados a um endereço de e-mail (cliente ou visitante que validou o passo de dados pessoais): nenhum endereço é recolhido antes de o cliente o submeter.
• Com o módulo oficial psgdpr, o módulo aparece na lista de módulos que tratam dados: a exportação e a eliminação dos dados de um cliente incluem os seus carrinhos acompanhados e os e-mails de lembrete. A exportação indica também a eventual presença do endereço na lista de exclusão.
• A eliminação de uma conta de cliente apaga os seus carrinhos acompanhados, a fila de envio e os eventos. A sua eventual oposição mantém-se na lista de exclusão.
• A desinstalação elimina as tabelas, a configuração e o separador de administração.

Perguntas frequentes e resolução de problemas

Não é enviado nenhum lembrete

Veja o estado do processamento no topo do painel. Se estiver vermelho, a tarefa cron não chama o URL (ou não com o token correto): use Executar agora para verificar e depois corrija a tarefa ou ative a execução sem cron do servidor. Confirme em seguida que a campanha e pelo menos uma etapa estão ativas, que a hora está dentro da janela de envio, e consulte o Registo de envios: aí encontra o motivo de cada e-mail ignorado ou falhado.

O cliente não consegue adicionar o seu código promocional

É intencional: o cupão de lembrete não é acumulável com nenhum outro código promocional. O cliente tem de retirar primeiro o código que está no carrinho e depois introduzir o outro. As regras automáticas sem código não são afetadas.

Um carrinho eliminado continua a receber e-mails

Até à versão 1.3.6, um e-mail já agendado era enviado mesmo que o carrinho tivesse sido eliminado no PrestaShop. Atualize para a 1.3.7 ou superior: os envios desses carrinhos são cancelados e o registo de envios mostra o motivo “Carrinho eliminado no PrestaShop”.

Um cliente recebeu duas vezes o mesmo lembrete

Até à versão 1.3.10, dois casos podiam produzir um duplicado: um cliente que voltou ao carrinho e depois saiu de novo, e duas lojas da mesma instalação multiloja a processar a mesma fila. Atualize para a 1.3.11 ou superior.

Página em branco “If no employee is assigned in the context, cart ID must be provided to this method”

Esta mensagem do núcleo do PrestaShop podia aparecer nas versões 1.0.0 a 1.3.1 quando um carrinho era gravado fora da navegação (webservice, conector, webhook de pagamento, script). Atualize para a 1.3.4 ou superior.

O URL cron devolve um erro 500

No PrestaShop 8, as versões 1.0.0 a 1.3.0 provocavam um erro 500 no URL cron. Atualize para a 1.3.1 ou superior e verifique a versão apresentada no gestor de módulos. Se o erro persistir, ative o modo debug do PrestaShop ou consulte os logs PHP do servidor para ler a mensagem exata.

Um carrinho não aparece na lista

Um carrinho só é acompanhado quando está associado a um endereço de e-mail: cliente com sessão iniciada ou visitante que validou o passo de dados pessoais. Passa a abandonado após o atraso de abandono (60 minutos por predefinição) e na execução seguinte do cron.

O meu logótipo não aparece ou está ilegível

Verifique se a opção Logótipo da loja está ativa e se há um logótipo definido em Aparência > Tema e logótipo. Se o logótipo for escuro, escolha um fundo de cabeçalho claro. Alguns clientes de e-mail bloqueiam as imagens por predefinição: nesse caso, aparece o nome da loja.

O e-mail de teste não chega

Verifique se a etapa tem assunto no idioma escolhido e se a loja consegue enviar e-mails (Parâmetros avançados > E-mail, botão de teste do PrestaShop). Consulte também a pasta de spam.

Um cliente pode receber demasiados e-mails?

Não: o limite de e-mails por carrinho, a anti-repetição por destinatário e a janela de envio controlam a frequência. Uma encomenda ou um cancelamento da subscrição anulam os lembretes restantes.

O módulo é compatível com multiloja?

Sim. Campanhas, carrinhos acompanhados, definições de aparência e estatísticas são separados por loja.

É compatível com o PrestaShop 9?

Sim. O módulo é compatível com o PrestaShop 8 e 9 e acompanha as alterações de API do PS9 (formatação de preços através da API Locale, controladores, envio de e-mails).