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

> Guia completo do módulo dffreeshipbar 2.3.0 para PrestaShop 8 e 9: instalação, limiares por país e por estado, posições de apresentação (incluindo a página de produto e o carrinho lateral…

- Página: <https://www.datafirefly.com/pt/documentation/dffreeshipbar/>
- Idioma: pt
- Atualizado em: 2026-10-10
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffreeshipbar/index.md), [en](https://www.datafirefly.com/en/documentation/dffreeshipbar/index.md), [es](https://www.datafirefly.com/es/documentation/dffreeshipbar/index.md), [de](https://www.datafirefly.com/de/documentation/dffreeshipbar/index.md), [it](https://www.datafirefly.com/it/documentation/dffreeshipbar/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreeshipbar/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreeshipbar/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

Guia completo do módulo **dffreeshipbar** 2.3.0 para PrestaShop 8 e 9: instalação, limiares por país e por estado, posições de apresentação (incluindo a página de produto e o carrinho lateral do Creative Elements), mensagens, aparência, transportadoras, várias moedas e resolução de problemas.

## Visão geral

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

O módulo funciona com **os seus próprios limiares**, guardados em tabelas próprias. Nunca lê a variável nativa `PS_SHIPPING_FREE_PRICE`: pode deixá-la a 0 e gerir os portes grátis com escalões da transportadora sem conflitos.

A sua particularidade é a **resolução territorial em dois níveis**: um limiar pode ser definido por país e por estado do PrestaShop. Territórios associados ao mesmo país, como os departamentos ultramarinos franceses ou, em Portugal, os Açores e a Madeira quando configurados como estados, podem assim ser tratados de forma diferente.

## Requisitos

- PrestaShop 8.0 a 9.x
- PHP 7.4 no mínimo (8.0 a 8.3 suportadas)
- Tema Classic, Hummingbird ou um tema personalizado que chame os hooks padrão
- Creative Elements (opcional) para a posição no carrinho lateral

## Instalação

1. No back office, aceder a **Módulos → Gestor de módulos → Enviar um módulo**.
2. Enviar o ficheiro `dffreeshipbar-2.3.0.zip`.
3. Clicar em **Instalar** e depois em **Configurar**.

O módulo cria duas tabelas (`PREFIX_dffreeshipbar_country` e `PREFIX_dffreeshipbar_state`, cada uma com uma coluna `id_shop`) e regista os hooks `displayHeader`, `displayBanner`, `displayNav2`, `displayNavFullWidth`, `displayShoppingCartFooter`, `displayCheckoutSummaryTop`, `displayProductAdditionalInfo`, `displayCEShoppingCartFooter` e `actionCarrierUpdate`.

**Nota.** O limiar global está desativado por predefinição. Enquanto nenhum território tiver limiar, a barra não aparece em lado nenhum, e a faixa de resumo do back office indica-o. Mais vale não ter barra do que prometer portes grátis que não oferece.

## O ecrã de configuração

O ecrã encontra-se em **Módulos → DataFirefly - Barra de portes grátis → Configurar**. No topo, uma faixa de resumo indica o estado do módulo, o número de territórios com limiar e de territórios excluídos, o limiar global, o filtro de transportadoras e as posições ativas. Cada bloco abre o separador correspondente.

A configuração divide-se em cinco separadores: **Geral**, **Territórios**, **Transportadoras**, **Mensagens** e **Aparência**. O separador ativo mantém-se após guardar.

**Idioma da interface de gestão.** O back office do módulo está disponível em inglês, francês, alemão, espanhol, italiano e polaco. Num back office em português, as etiquetas aparecem em inglês. Os textos que os seus clientes veem definem-se em português no separador Mensagens.

## Separador Geral

### Limiar global

- **Use a global fallback threshold**: em _Não_, a barra só aparece nos territórios configurados. Em _Sim_, qualquer território não configurado recebe o montante indicado.
- **Global fallback threshold**: o montante aplicado em último recurso.

### Várias moedas

Todos os montantes do módulo introduzem-se na **moeda predefinida** da loja. Para um visitante que paga noutra moeda, o limiar é convertido à taxa de câmbio do PrestaShop antes da comparação com o carrinho, e os montantes apresentados são formatados na sua moeda.

### Exigir uma morada de entrega

Antes de ser introduzida uma morada, o destino é apenas uma estimativa e o estado é desconhecido. Três modos:

- **Never**: a barra aparece logo durante a navegação, com base no país estimado.
- **For countries with states** (recomendado): a barra fica visível em todo o lado exceto nos países cujos estados possam ter condições diferentes, onde aguarda a morada.
- **Always**: nada enquanto o carrinho não tiver morada.

### Base de cálculo

- **Comparar totais com IVA**: deve corresponder à base dos escalões da transportadora, caso contrário a barra e o checkout divergem.
- **Incluir as regras de carrinho no total**: um carrinho de 70 € com um vale de 10 € é então avaliado em 60 €.

Os portes nunca contam para o progresso.

### Grupos de clientes

Sem nenhuma caixa marcada, todos os clientes veem a barra. Marque grupos para a reservar a eles, por exemplo a particulares quando as empresas têm outras condições de envio. Um visitante sem sessão iniciada pertence ao grupo «Visitante».

### Ocultar enquanto o carrinho estiver vazio

A barra aparece com o primeiro produto adicionado. A página de produto mantém-na em todos os casos, porque é aí que o cliente decide adicionar.

### Posições de apresentação

- **Topo da página**: faixa visível em todo o site.
- **Página de produto**: ver a secção dedicada abaixo.
- **Carrinho e checkout**: bloco na página do carrinho e no processo de encomenda.
- **Carrinho lateral do Creative Elements**: ver a secção dedicada abaixo.

Para uma colocação livre, o módulo implementa `WidgetInterface`:

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

## A barra na página de produto

A barra aparece sob o botão de adicionar ao carrinho (hook `displayProductAdditionalInfo`). Além do progresso atual, uma linha indica o efeito de adicionar o produto apresentado:

- se o produto chegar para atingir o limiar: «Adicione este produto e a sua encomenda tem portes grátis»;
- caso contrário: «Com este produto, faltam apenas 2,50 € para portes grátis».

O cálculo usa o preço da combinação selecionada multiplicado pela quantidade indicada, com a mesma base de IVA do carrinho e os preços específicos do cliente. Repete-se quando o cliente muda de combinação ou de quantidade.

**Atualização a partir de uma versão anterior.** Esta posição começa desativada numa loja existente, para que a atualização não altere o que os clientes veem. Ative-a no separador Geral.

## O carrinho lateral do Creative Elements

Numa loja cujo cabeçalho é construído com o Creative Elements, a barra integra-se no carrinho lateral do widget **Carrinho** no estilo _Sidebar_, através do hook `displayCEShoppingCartFooter` que esse widget executa. O estilo _Classic_ não abre carrinho lateral.

A definição **Posição no carrinho lateral** oferece três locais: sob o título, acima do resumo ou acima dos botões de checkout.

A barra atualiza-se em Ajax a cada adição ao carrinho e a cada remoção no carrinho lateral, sem recarregar, e o indicador desliza a partir do valor anterior. O Creative Elements só reconstrói a lista de produtos e o resumo: a barra mantém-se no lugar entre atualizações.

## Separador Territórios

A tabela lista todos os países ativos da loja e, sob cada país com estados, os seus estados, recuados. Um campo de pesquisa e um filtro de territórios configurados facilitam a navegação. Os montantes estão na moeda predefinida.

### Ordem de resolução

Para uma morada de entrega, o módulo procura por esta ordem e para no primeiro resultado: o **estado** da morada, depois o **país**, depois o **limiar global**, se estiver ativo. Sem resultado, a barra não é apresentada.

### Caixa e montante: dois efeitos diferentes

- **Caixa desmarcada**: a barra fica oculta para esse território, sem herança do país nem do limiar global.
- **Caixa marcada, montante vazio**: a regra é eliminada e o território herda do nível superior.
- **Caixa marcada, montante indicado**: aplica-se esse montante.

**Atenção.** Para excluir um território, desmarque a caixa. Esvaziar o montante produz o efeito contrário: o território herda o limiar do seu país.

### Exemplo: apenas França continental

- **França**: marcada, montante `65`.
- **Córsega**: marcada, montante vazio; herda os 65 €.
- **Guadalupe, Martinica, Guiana Francesa, Reunião, Maiote**: desmarcadas.
- **Limiar global**: desativado.

## Separador Transportadoras

Três modos: todas as transportadoras, apresentação reservada às transportadoras marcadas, ou ocultação para as transportadoras marcadas. As regras são guardadas no `id_reference` da transportadora: o PrestaShop recria uma transportadora a cada alteração, mas a sua referência mantém-se.

A definição **Antes da escolha da transportadora** decide se a barra aparece no catálogo e no carrinho enquanto nenhuma transportadora foi escolhida.

## Separador Mensagens

Cinco mensagens personalizam-se para cada idioma ativo:

- **Carrinho vazio**
- **Carrinho em curso**
- **Limiar atingido**
- **Página de produto: este produto dá portes grátis**
- **Página de produto: montante em falta após adicionar o produto**

Estão disponíveis dois marcadores: `{amount}` para o montante em falta e `{threshold}` para o limiar. São substituídos pelo montante formatado na moeda do visitante, a negrito. Exemplo em português: _Faltam apenas {amount} para portes grátis!_ O texto é apresentado tal como está: o HTML introduzido não é interpretado. Um campo vazio mantém o texto fornecido, que para o português está em inglês. Preencha por isso as cinco mensagens para o seu idioma português.

## Separador Aparência

- **Cores**: fundo, barra, texto e mensagem de sucesso, com um seletor de cor e um campo hexadecimal sincronizados.
- **Ícone**: camião, encomenda, presente ou nenhum. Os ícones são SVG e um visto substitui o ícone quando o limiar é atingido.
- **Animação**: riscas animadas durante o progresso, desativadas automaticamente para os visitantes que pediram ao sistema para reduzir o movimento.
- **Faixa que se pode fechar**: acrescenta um botão de fecho à faixa do topo da página. Depois de fechada, fica oculta até o navegador ser fechado. As restantes posições não são afetadas.

Uma **pré-visualização em direto** mostra a faixa superior, a página de produto e o limiar atingido, e atualiza-se a cada alteração antes de guardar.

## Atualização em tempo real

Cada posição imprime um contentor, mesmo quando a barra não tem nada para mostrar. Após um evento de carrinho, morada, passo do checkout, combinação ou quantidade, um único pedido obtém a barra de todas as posições da página, e cada contentor é preenchido ou esvaziado no lugar. Uma barra oculta no carregamento pode assim aparecer sem recarregar, e o inverso.

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

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

## Multiloja

Os limiares têm um `id_shop`: cada loja tem as suas regras. Selecione o contexto da loja no topo do back office antes de abrir a configuração.

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

Substituir o ZIP executa automaticamente os scripts de migração. Os seus limiares são mantidos. As novas opções começam desativadas numa loja existente: página de produto, ocultação com carrinho vazio, faixa que se pode fechar e restrição por grupo. As cores guardadas por versões anteriores são normalizadas para `#rrggbb`, e as caches Smarty e opcache são limpas.

## Resolução de problemas

### A barra não aparece em lado nenhum

1. A faixa de resumo indica que nenhum território tem limiar?
2. O módulo e as posições pretendidas estão ativos?
3. A exigência de morada está em _Always_ enquanto testa sem morada?
4. Há grupos de clientes marcados aos quais a sua conta de teste não pertence?
5. A opção para carrinho vazio está ativa com o carrinho vazio?

### A barra aparece onde não devia

Verifique se a caixa do território está mesmo desmarcada, e não apenas se o montante foi esvaziado.

### Nada no carrinho lateral do Creative Elements

- O widget Carrinho tem de usar o estilo _Sidebar_.
- A opção do carrinho lateral do Creative Elements tem de estar ativa.
- Após uma atualização a partir da 2.1.0 ou anterior, limpe a cache em **Parâmetros avançados → Desempenho**.

### O montante não corresponde ao checkout

- A definição de IVA tem de corresponder à base dos escalões da transportadora.
- Um vale pode fazer o carrinho voltar a ficar abaixo do limiar.
- O módulo não lê os seus escalões: transponha para o módulo qualquer alteração de escalão.

### A barra não se atualiza após adicionar ao carrinho

A atualização baseia-se nos eventos JavaScript do PrestaShop. Se um módulo de carrinho de terceiros não os emitir, dispare `dffreeshipbar:refresh` a partir do código dele. Verifique também a consola: um erro JavaScript anterior impede a instalação da escuta.

## Desinstalação

A desinstalação elimina as duas tabelas de limiares e todas as chaves de configuração com o prefixo `DFFREESHIPBAR_`, mensagens incluídas. Exporte as duas tabelas se prevê reinstalar.

## FAQ rápida

- **O módulo lê PS_SHIPPING_FREE_PRICE?** Nunca.
- **O módulo lê os escalões da transportadora?** Não, os limiares introduzem-se manualmente. Uma sincronização automática é possível como desenvolvimento à medida.
- **Os meus portes grátis dependem também do peso. Está previsto?** Não, o módulo mede apenas um montante.
- **Posso usar negrito ou uma ligação numa mensagem?** Não, o texto é protegido. Os montantes dos marcadores ficam a negrito automaticamente.
- **Uma faixa fechada volta a aparecer?** Na próxima abertura do navegador.

## Suporte e atualizações

O módulo inclui **12 meses de atualizações e suporte**. Suporte por email em francês ou inglês, resposta em 24 horas úteis. Contacte [o suporte DataFirefly](https://www.datafirefly.com/pt/contacto/) indicando as versões do PrestaShop, do PHP e do módulo, o tema utilizado, e o território e a transportadora em causa.