Barra de portes grátis (dffreeshipbar): guia completo

Guia completo do módulo dffreeshipbar para PrestaShop 8 e 9: instalação, limiares por país e por estado, filtragem por transportadora, locais de apresentação, multiloja e resolução de problemas. Todas as regras de resolução são detalhadas, incluindo os casos-limite.

Visão geral

O dffreeshipbar apresenta uma barra de progresso que indica ao cliente quanto lhe falta gastar para beneficiar de portes grátis. Quando o limiar é atingido, a mensagem muda para uma confirmação.

O módulo funciona com limiares próprios, guardados nas suas tabelas. Nunca consulta a variável nativa PS_SHIPPING_FREE_PRICE: pode deixá-la a 0 e gerir os seus portes grátis através de escalões de transportadora, sem qualquer conflito.

A particularidade do módulo é a sua resolução territorial a dois níveis. Um limiar pode ser definido ao nível do país, mas também ao nível do estado do PrestaShop, o que permite tratar de forma diferente territórios administrativamente ligados ao mesmo país, como as regiões insulares ou os departamentos ultramarinos.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 no mínimo (8.0 a 8.3 suportadas)
• Tema Classic, Hummingbird ou tema personalizado que chame os hooks padrão
• Acesso de administrador ao back-office

Instalação

1. No back-office, vá a Módulos → Gestor de módulos → Carregar um módulo.
2. Envie o ficheiro dffreeshipbar-2.1.0.zip.
3. Clique em Instalar e depois em Configurar.

Na instalação, o módulo cria duas tabelas e regista os seus hooks:

• PREFIX_dffreeshipbar_country — limiares ao nível do país, com uma coluna id_shop.
• PREFIX_dffreeshipbar_state — limiares ao nível do estado, com uma coluna id_shop.

Hooks registados: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Configuração geral

O ecrã de configuração está em Módulos → DataFirefly – Barra de portes grátis → Configurar. Compõe-se de três painéis: parâmetros gerais, regras de transportadora e limiares por território.

Limiar global de recurso

Duas definições ligadas entre si:

• Utilizar um limiar global predefinido: quando este interruptor está em Não, a barra só aparece nos territórios configurados explicitamente. Quando está em Sim, qualquer território não configurado recebe o montante indicado abaixo.
• Limiar global predefinido: o montante aplicado em último recurso.

Deixe o recurso desativado se os seus portes grátis abrangerem apenas alguns destinos. Ative-o se forem universais e as exceções forem raras.

Base de cálculo

• Comparar os totais com IVA: determina se o total do carrinho é avaliado com ou sem impostos. Esta definição tem de coincidir com a base usada pelos seus escalões de transportadora, sob pena de a barra e o processo de encomenda apresentarem resultados divergentes.
• Incluir os vales de desconto no total: com este interruptor ativo, os descontos de carrinho são deduzidos antes da comparação com o limiar. Um carrinho de 70 € com um vale de 10 € é então avaliado em 60 €.

O total avaliado corresponde a uma chamada nativa:

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Os portes e a embalagem para oferta nunca contam para a progressão.

Exigir uma morada de entrega

Enquanto o cliente não indicar uma morada, o destino é apenas uma estimativa e o estado permanece desconhecido. Três modos:

• Nunca: a barra aparece logo na navegação do catálogo, com base no país estimado.
• Nos países com estados (recomendado): a barra mantém-se visível em todo o lado, exceto nos países cujos estados podem ter condições diferentes. Um visitante estimado na Bélgica vê a barra; um visitante estimado num país com estados só a vê depois de introduzir a morada, uma vez que o estado determinará o limiar real.
• Sempre: nada enquanto não existir uma morada no carrinho.

Locais de apresentação e aspeto

• Apresentar no topo da página: faixa visível em todo o site.
• Apresentar no carrinho e na encomenda: bloco apresentado no momento da decisão.
• Ativar a animação: riscas animadas na barra enquanto está a progredir. A animação é automaticamente neutralizada para os visitantes que tenham ativado prefers-reduced-motion.
• Quatro cores: fundo, barra, texto e mensagem de sucesso.

Para uma colocação livre no seu tema, o módulo implementa a WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Limiares por território

É o coração do módulo. A tabela lista todos os países ativos da loja e, sob cada país com estados, os respetivos estados, indentados.

Ordem de resolução

Para uma dada morada de entrega, o módulo procura por esta ordem e para no primeiro resultado:

1. O estado da morada, se existir uma regra para ele.
2. O país da morada, se existir uma regra para ele.
3. O limiar global de recurso, se estiver ativado.

Se nenhuma destas três etapas produzir um montante, a barra não é apresentada.

Caixa de seleção e campo do montante: dois efeitos diferentes

É o ponto mais importante da configuração e o mais frequentemente mal compreendido:

• Caixa desassinalada → a barra fica oculta nesse território. Não herda nem do país pai, nem do limiar global. A resolução termina aí.
• Caixa assinalada, montante vazio → a regra é eliminada e o território herda do nível superior.
• Caixa assinalada, montante preenchido → aplica-se esse montante.

Exemplo: portes grátis apenas no continente

Caso corrente de uma loja francesa que oferece os portes a partir de 65 € na França continental e na Córsega, mas não nos territórios ultramarinos:

• França: caixa assinalada, montante 65.
• Córsega: caixa assinalada, montante vazio; herda os 65 € da França.
• Guadalupe, Martinica, Guiana, Reunião, Maiote: caixas desassinaladas. Nenhuma barra nesses destinos.
• Limiar global de recurso: desativado, para que nenhum outro país receba a barra por acidente.

Um cliente da Guadalupe nunca verá, portanto, a promessa de portes grátis, mesmo que a sua morada esteja ligada ao país «França» no PrestaShop.

Filtro e pesquisa

O campo de pesquisa filtra países e estados por nome. A caixa Mostrar apenas os territórios configurados reduz a tabela às linhas que já têm uma regra, útil numa loja aberta a uma centena de países.

Os dois botões de gravação são independentes: Gravar os países e Gravar os estados.

Regras de transportadora

Se os seus portes grátis só forem concedidos por determinadas transportadoras, restrinja a apresentação em conformidade. Três modos:

• Todas as transportadoras: sem filtragem.
• Apresentar apenas nas transportadoras assinaladas: lista branca.
• Ocultar nas transportadoras assinaladas: lista negra.

Antes da seleção da transportadora

A transportadora só é conhecida na etapa de entrega. A definição Antes da seleção da transportadora decide o que acontece antes desse momento:

• Apresentar: a barra aparece no catálogo e no carrinho e desaparece se o cliente escolher uma transportadora excluída.
• Ocultar: a barra só aparece depois de selecionada uma transportadora elegível.

Atualização em tempo real

A barra é recalculada do lado do servidor e atualizada sem recarregar a página em cada evento do carrinho: adição, remoção, mudança de quantidade, alteração de morada, mudança de etapa do processo de encomenda.

O script escuta os eventos do PrestaShop updatedCart, updateCart, updatedAddressForm, changedCheckoutStep e updateDeliveryForm. Pode despoletar uma atualização manual a partir do seu próprio código:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

É o servidor que decide a visibilidade: se o território ou a transportadora deixarem de qualificar, a barra é retirada do DOM em vez de ficar com um valor desatualizado.

Multiloja

Os limiares são guardados com uma coluna id_shop. Cada loja tem, por isso, as suas próprias regras de países e estados, independentes umas das outras.

Para configurar uma loja específica, selecione o respetivo contexto no topo do back-office antes de abrir o ecrã de configuração. O painel dos limiares apresenta o nome da loja atual como lembrete.

Traduções

O módulo é fornecido traduzido em francês, inglês, alemão, espanhol, italiano e polaco.

Para adaptar os textos apresentados ao cliente, vá a Internacional → Traduções, selecione «Traduções do módulo», escolha dffreeshipbar e o idioma e procure depois o domínio Modules.Dffreeshipbar.Shop. As cadeias disponíveis:

• «Faltam apenas %amount% para ter portes grátis!» — carrinho em curso.
• «Portes grátis a partir de %amount%.» — carrinho vazio.
• «Parabéns! A sua encomenda tem portes grátis.» — limiar atingido.

O marcador %amount% é substituído pelo montante formatado segundo a moeda e a localização ativas. Conserve-o nas suas traduções.

Atualização a partir da versão 1.0

A atualização é automática ao substituir o ZIP. Os scripts de upgrade executam as seguintes operações:

• Criação da tabela dos estados.
• Mudança do nome da coluna active para enabled na tabela dos países. Os seus limiares existentes são conservados.
• O limiar global de recurso é ativado se já tivesse um na 1.0, para não alterar aquilo que os seus clientes veem.
• O modo de exigência de morada fica em Nunca, que corresponde ao comportamento da versão 1.0. Passe-o para o modo recomendado quando entender.

Resolução de problemas

A barra não aparece em lado nenhum

1. O módulo está ativado? (interruptor Ativar o módulo).
2. Configurou pelo menos um território ou ativou o limiar global de recurso? Sem um ou outro, a barra nunca aparece.
3. O modo de exigência de morada está em Sempre enquanto está a testar sem morada de entrega?
4. Os locais de apresentação estão ativados? (faixa e/ou carrinho).
5. O seu tema chama os hooks utilizados? Verifique em Módulos → Posições. Num tema personalizado, use antes o widget.

A barra aparece onde não devia

O caso típico é um território que herda quando devia estar excluído. Verifique se a caixa do território está mesmo desassinalada e não apenas com o montante esvaziado: as duas ações têm efeitos opostos.

O limiar apresentado não corresponde ao checkout

• Verifique se a definição Comparar os totais com IVA corresponde à base dos seus escalões de transportadora.
• Verifique a definição dos vales de desconto: um carrinho com desconto pode cair abaixo do limiar.
• O módulo não lê os seus escalões de transportadora. Se alterou um escalão, transponha o novo valor para o módulo.

A barra não se atualiza depois de acrescentar ao carrinho

A atualização assenta nos eventos JavaScript do PrestaShop. Alguns temas ou módulos de carrinho de terceiros não os emitem. Duas verificações:

• A consola do navegador assinala algum erro de JavaScript noutro recurso? Um erro bloqueante a montante impede a escuta de se instalar.
• O seu módulo de carrinho ajax emite mesmo prestashop.emit('updatedCart')? Caso contrário, despolete dffreeshipbar:refresh a partir do seu código.

As regras de transportadora parecem ignoradas

Verifique se a transportadora selecionada é mesmo a que julga: depois de uma alteração de tarifa, o PrestaShop cria uma nova transportadora. O módulo segue a referência, pelo que a regra deveria acompanhar; mas se a transportadora tiver sido recriada de raiz em vez de alterada, a sua referência é nova e é preciso voltar a assinalá-la.

Desinstalação

Vá a Módulos → Gestor de módulos → DataFirefly – Barra de portes grátis → Desinstalar. A desinstalação elimina as duas tabelas de limiares e todas as chaves de configuração com o prefixo DFFREESHIPBAR_.

FAQ rápida

• O módulo lê a PS_SHIPPING_FREE_PRICE? Não, nunca. Pode deixá-la a 0 e gerir os portes grátis por escalões de transportadora.
• O módulo lê os meus escalões de transportadora para deduzir o limiar? Não. Os limiares são introduzidos manualmente. Uma sincronização automática a partir dos escalões é possível através de desenvolvimento específico.
• Os meus portes grátis também dependem do peso. É suportado? Não, o módulo só avalia um montante. Uma condição de peso exige desenvolvimento específico.
• Posso apresentar a barra fora dos locais propostos? Sim, através de {widget name='dffreeshipbar'} em qualquer template.
• O módulo funciona com o tema Hummingbird? Sim. Os hooks displayNavFullWidth e displayCheckoutSummaryTop estão registados para ele e o widget cobre as colocações personalizadas.
• Os limiares são independentes por loja? Sim, cada linha tem um id_shop.

Apoio ao cliente e atualizações

O módulo inclui 12 meses de atualizações e de apoio a partir da data de compra. Apoio por e-mail em francês ou em inglês, com resposta em 24 horas úteis.

Para qualquer questão ou anomalia, contacte o apoio da DataFirefly indicando:

• Versão do PrestaShop e do PHP
• Versão do módulo instalada
• Tema utilizado
• Território e transportadora em causa no comportamento observado
• Descrição do comportamento observado face ao esperado