# Promoções por quantidade e etiquetas promo: documentação

> Instalação O módulo instala-se como qualquer módulo PrestaShop, pelo back-office ou por FTP. Em Módulos e depois Gestor de módulos, clique em Carregar um módulo e largue o ficheiro dfquantitydeal.zip.…

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

## Instalação

O módulo instala-se como qualquer módulo PrestaShop, pelo back-office ou por FTP.

1. Em **Módulos** e depois **Gestor de módulos**, clique em **Carregar um módulo** e largue o ficheiro `dfquantitydeal.zip`.
2. Por FTP, descomprima o arquivo na pasta `/modules/` da sua loja e instale depois o **DataFirefly - Ofertas por quantidade e selos promocionais** a partir do gestor de módulos.
3. Limpe a cache em **Parâmetros avançados** e depois **Desempenho**.

A instalação cria oito tabelas com o prefixo `ps_df_quantity_deal`, associa o módulo a nove hooks, cria o hook `displayDfQdBadge` e acrescenta o separador **Ofertas por quantidade** ao menu Catálogo.

O módulo não instala qualquer override de classe ou de controlador. A desinstalação elimina as tabelas, as chaves de configuração e o separador.

## Idiomas do módulo

O inglês é o idioma de origem do módulo. As traduções são fornecidas na pasta `translations/` para francês, italiano, espanhol, alemão, neerlandês, polaco e português.

- O back-office é apresentado no idioma do funcionário com sessão iniciada.
- Os textos vistos pelo cliente (frases do bloco das ofertas, incentivos do carrinho, botões) seguem o idioma da loja.
- O separador do menu recebe o nome traduzido em cada idioma instalado.
- O nome do desconto do carrinho é criado na instalação no idioma predefinido da loja. Pode alterá-lo nas definições gerais.

Para ajustar uma formulação, abra **Internacional** e depois **Traduções**, tipo **Traduções de módulos instalados**, módulo **dfquantitydeal**.

## Definições gerais

O botão **Configurar** da ficha do módulo abre as definições que se aplicam a todas as ofertas.

- **Ativar o módulo**: desliga a apresentação dos selos e o cálculo dos descontos sem desinstalar.
- **Selos nas listagens**: mostra o selo nas miniaturas das páginas de categoria, dos resultados de pesquisa e dos blocos de produtos.
- **Selo na página do produto**: interruptor separado, para mostrar o selo apenas nas listagens, se preferir.
- **Tabela de ofertas na página do produto**: mostra o bloco que lista as ofertas aplicáveis ao produto.
- **Detalhe das ofertas no carrinho**: mostra o montante trazido por cada oferta.
- **Posição do detalhe das ofertas**: acordeão sob a linha Desconto(s) (por predefinição), acima da linha Envio, abaixo do total do carrinho (IVA incl.) ou abaixo da lista de produtos.
- **Selo e preço riscado nas linhas do carrinho**: em cada linha em causa, mostra o selo da oferta, risca o preço inicial e mostra o preço com desconto por baixo.
- **Ocultar o vale de desconto automático**: remove do resumo a linha do vale gerado pelo módulo, já contabilizada na linha Desconto(s). Assim, o cliente não pode remover um desconto que é recalculado a cada alteração do carrinho.
- **Incentivar a completar o lote no carrinho**: mostra um aviso quando faltam apenas alguns artigos para ativar uma oferta.
- **Calcular os descontos com IVA incluído**: ativa, a regra de carrinho leva um montante com IVA incluído. Desativada, o montante é sem IVA e o PrestaShop aplica o imposto segundo as suas regras.
- **Nome do desconto do carrinho**: texto apresentado na linha de desconto do carrinho e da encomenda.
- **Tamanho da letra do selo (px)**: 13 por predefinição.
- **Método de apresentação dos selos**: automático (injeção pelo script front), manual (apenas através do hook `displayDfQdBadge`) ou ambos.
- **Posição das ofertas na página do produto**: ver a secção dedicada mais abaixo.
- **Seletor CSS personalizado** e **Posição em relação ao seletor**: usados apenas com a posição «Seletor CSS personalizado».

## Diagnóstico

A página de configuração mostra um painel **Diagnóstico** por cima das definições. Indica se o módulo está ativado, se cada hook necessário existe na base de dados e se o módulo lhe está associado, o número de ofertas ativas hoje e o número de ofertas associadas à loja atual.

A ligação **Testar o endpoint dos selos** abre o controlador front que fornece os selos. Uma resposta JSON confirma que ele responde. Um erro 404 indica que é preciso limpar a cache e regenerar os URL amigáveis.

Abrir a página de configuração associa automaticamente os hooks em falta, o que corrige a maioria das instalações feitas antes de uma atualização.

## Criar uma oferta

Abra **Catálogo** e depois **Ofertas por quantidade**, e clique em **Nova oferta**. O formulário está dividido em três separadores.

### Separador Oferta

- **Nome da oferta**: campo traduzido, usado na lista do back-office e no bloco das ofertas da página do produto.
- **Tipo de oferta**: as cinco mecânicas descritas mais abaixo. O formulário oculta os campos desnecessários conforme o tipo escolhido.
- **Quantidade comprada (X)** e **Quantidade oferecida (Y)**: para o tipo X comprados + Y oferecidos, e apenas X para o preço de lote.
- **Posição do artigo com desconto (N)**: 2 para «o 2.º a -25 %», 3 para «o 3.º a -50 %».
- **Valor do desconto**: percentagem, montante do desconto ou preço fixo, conforme o tipo. A designação do campo muda automaticamente.
- **Oferta repetível**: ativada, a oferta aplica-se tantas vezes quantas a quantidade permitir (12 artigos ativam duas vezes uma oferta 4+2). Desativada, aplica-se apenas uma vez por carrinho.
- **Agrupamento das quantidades**: por produto, por combinação ou mix and match.
- **Prioridade**: os valores mais baixos passam primeiro.
- **Ativar a oferta**: equivalente ao botão de ativação da lista.

### Separador Condições

- **Âmbito**: todo o catálogo, produtos selecionados, categorias selecionadas ou marcas selecionadas. O campo de seleção correspondente aparece conforme a escolha.
- **Produtos abrangidos**: escreva pelo menos dois caracteres para lançar a pesquisa, que incide sobre o nome, a referência e o ID. Clique num resultado para o acrescentar à lista.
- **Categorias abrangidas**: árvore de categorias com caixas de seleção. Um produto associado a uma das categorias assinaladas ativa a oferta.
- **Marcas abrangidas**: lista dos fabricantes da loja.
- **Grupos de clientes**: deixe tudo desmarcado para aplicar a oferta a todos os grupos, visitantes incluídos.
- **Excluir os produtos já em promoção**: os produtos com um preço específico saem do cálculo.
- **Data de início** e **Data de fim**: deixe vazio para uma oferta permanente. Uma data sem hora é completada com 00:00:00 no início e 23:59:59 no fim.
- **Lojas**: visível apenas se o modo multiloja estiver ativo.

Uma promoção sem data de fim é permanente, e uma vantagem permanente deixa de ser uma promoção: o Decreto-Lei n.º 70/2007 distingue saldos, promoções e liquidações, cada um com o seu regime, e o Decreto-Lei n.º 57/2008 proíbe apresentar como vantagem excecional o que é o preço normal. Se quiser uma mecânica permanente do tipo «3 por 10 €», apresente-a como formato de venda ou preço de lote, e não como uma promoção por tempo limitado.

### Separador Selo e apresentação

- **Texto do selo**: campo traduzido. Deixe vazio para uma geração automática a partir dos valores da oferta.
- **Cor de fundo** e **Cor do texto**: seletores de cor, com vermelho e branco por predefinição.
- **Forma**: quadrado, cantos arredondados, pílula, fita diagonal, autocolante redondo.
- **Posição na miniatura**: canto superior esquerdo, canto superior direito, canto inferior esquerdo, canto inferior direito, ou em linha (abaixo do preço).
- **Mostrar nas listagens**, **Mostrar na página do produto**, **Mostrar na tabela de ofertas**: três interruptores por oferta, que se somam às definições globais.
- **Descrição da oferta**: texto formatado e traduzido, apresentado no bloco das ofertas da página do produto.

## Os cinco tipos de ofertas

### X comprados + Y oferecidos

O formato clássico do 2+1, 3+1 ou 4+2. O motor divide as unidades elegíveis do carrinho em lotes de X mais Y. Em cada lote completo, as Y unidades mais baratas são oferecidas.

Exemplo: oferta 4+2, seis artigos a 4,49 € no carrinho. Um lote completo, duas unidades oferecidas, desconto de 8,98 €. Com apenas cinco artigos, nenhum lote fica completo e o desconto é nulo.

### O N.º a -X %

O motor divide as unidades em lotes de N. Em cada lote, a unidade na posição N recebe a percentagem de desconto. Como as unidades são ordenadas por preço decrescente, o artigo com desconto é o mais barato do lote.

Exemplo: oferta «o 2.º a -25 %», quatro artigos a 20 €. Dois lotes de dois, dois artigos com 5 € de desconto, desconto total de 10 €.

### O N.º com um desconto fixo

A mesma divisão, mas o desconto é um montante fixo. Está limitado ao preço do artigo: um desconto de 30 € num artigo de 8 € dá 8 € de desconto, e não 30 €.

### O N.º a preço fixo

O artigo na posição N passa para o preço que fixar. O desconto corresponde à diferença. Em «o 2.º a 1 €» com dois artigos a 12 €, o desconto é de 11 €.

### Preço de lote

Em cada lote de X unidades, o total passa para o preço que anuncia. Numa oferta de 3 por 10 € com seis artigos a 5 €, o motor forma dois lotes e aplica 10 € de desconto no total.

As palavras que usa nas etiquetas têm consequências. «Oferta» e «grátis» só podem descrever algo que o cliente recebe realmente sem custo, e um preço de lote apresentado como vantajoso face à compra separada é um anúncio de redução, sujeito à regra do preço mais baixo dos 30 dias do Decreto-Lei n.º 66/2021. Se o preço unitário subiu pouco antes de lançar o «3 por 10 €», a comparação deixa de ser lícita.

## Que artigo é oferecido

O motor ordena as unidades elegíveis por preço decrescente e aplica depois a vantagem às mais baratas de cada lote. É a regra usada pela grande distribuição e a que o cliente espera.

Num lote 3+1 com artigos a 20 €, 15 €, 10 € e 5 €, o artigo oferecido é o de 5 €. O cliente paga 45 € em vez de 50 €.

## Agrupamento das quantidades

- **Por produto**: todas as combinações de uma mesma referência contam em conjunto. Seis frascos do mesmo gel de banho ativam uma oferta 4+2, mesmo que sejam três perfumes diferentes.
- **Por combinação**: cada combinação conta por si. São precisas seis unidades do mesmo perfume para ativar a mesma oferta.
- **Mix and match**: todas as unidades dos produtos associados à oferta alimentam a mesma contagem. É útil para fazer 4+2 numa gama completa.

## Prioridade e acumulação entre ofertas

As ofertas são avaliadas pela ordem da sua prioridade, da mais baixa para a mais alta. Cada oferta consome as unidades que usa, e a seguinte trabalha sobre o resto. Uma mesma unidade nunca recebe desconto duas vezes.

Exemplo: sete artigos no carrinho e uma oferta 4+2 com prioridade 10. Seis unidades são consumidas pelo lote, e a sétima fica disponível para uma oferta de prioridade 20 que vise o mesmo produto.

Coloque as suas ofertas mais generosas numa prioridade baixa se quiser que se apliquem primeiro. Com prioridades iguais, a ordem segue o identificador da oferta.

## O selo

### Variáveis do texto

O campo Texto do selo aceita cinco variáveis, substituídas na apresentação pelos valores da oferta.

- `{x}`: quantidade comprada
- `{y}`: quantidade oferecida
- `{n}`: posição do artigo com desconto
- `{value}`: valor do desconto, sem zeros desnecessários
- `{price}`: valor do desconto formatado como preço, na moeda do cliente

Também pode escrever o texto de forma fixa: «4+2 grátis», «3+1 oferecido», «o 2.º a -25 %». O campo é traduzido, pelo que cada idioma tem a sua formulação.

Se o campo ficar vazio, o módulo gera uma designação curta a partir do tipo e dos valores: `4+2` para uma oferta X comprados Y oferecidos, `-25% x2` para um N.º a percentagem.

### Apresentação automática

Por predefinição, um script front identifica as miniaturas de produto da página, pede os respetivos selos ao módulo numa única chamada Ajax e coloca-os sobre a imagem ou por baixo do preço, conforme a posição da oferta. Este funcionamento não depende de nenhum hook de miniatura, o que cobre os temas personalizados que já não chamam `displayProductPriceBlock`. A colocação é repetida após as atualizações Ajax da pesquisa por facetas, da paginação e da vista rápida.

### Hook dedicado displayDfQdBadge

Para colocar o selo num sítio preciso do seu tema ou de outro módulo, chame o hook dedicado no template:

```
{hook h='displayDfQdBadge' id_product=$product.id_product}
```

Estão disponíveis dois parâmetros opcionais.

- `mode`: `auto` (por predefinição) segue a posição definida em cada oferta, `inline` força a apresentação no fluxo da página, `overlay` força a sobreposição à imagem. O contentor recebe automaticamente `position: relative`.
- `context`: `list` ou `product`, para aplicar as definições «listagens» ou «página do produto» da oferta. Detetado automaticamente se estiver ausente.

```
{hook h='displayDfQdBadge' id_product=$product.id_product mode='inline'}
```

O hook aparece em **Design** e depois **Posições** com o nome «DataFirefly - Quantity deal badge».

Se o seu tema chamar este hook nos templates, mude o **Método de apresentação dos selos** para **Manual**. Caso contrário, os selos aparecem duas vezes: uma pelo hook e outra pelo script.

## O bloco das ofertas na página do produto

Para cada oferta aplicável, o bloco mostra o selo, o nome da oferta, uma frase que diz ao cliente o que fazer e a descrição, se tiver preenchido uma. Exemplos de frases: «Adicione 6 artigos ao carrinho, os últimos 2 serão oferecidos», «Adicione 3 artigos ao carrinho, o lote custará 10,00 €». O título «Ofertas em curso» só aparece se uma das ofertas tiver data de fim.

A definição **Posição das ofertas na página do produto** propõe onze posições:

- acima ou abaixo do título do produto;
- abaixo da referência, abaixo da descrição curta;
- acima ou abaixo do preço;
- acima das combinações;
- acima do botão Adicionar ao carrinho, ou abaixo deste botão (posição nativa, por predefinição);
- num separador dedicado na página do produto;
- através de um seletor CSS personalizado.

O bloco é gerado pelo hook nativo `displayProductAdditionalInfo` e depois deslocado no navegador, sem alterar o seu tema. O separador dedicado passa por `displayProductExtraContent`. Com o seletor CSS personalizado, escreva por exemplo `.product-information h1` e escolha se o bloco fica imediatamente antes, imediatamente depois, no início ou no fim do elemento. Se o seletor não encontrar nada, o bloco fica na posição nativa.

## O carrinho

### Cálculo do desconto

A cada alteração do carrinho, o motor recalcula o total dos descontos e sincroniza uma regra de carrinho privada. O seu código interno começa por `DFQD`, seguido do identificador do carrinho. O cliente vê apenas uma linha de desconto e não tem qualquer código para introduzir.

A regra só é atualizada se o montante tiver mudado, o que evita recriá-la a cada carregamento de página. Se o total voltar a zero, a regra é desassociada do carrinho e depois eliminada.

Na validação da encomenda, a regra é desativada e a sua data de fim é recuada para o passado, para não poder ser reutilizada. Continua ligada à encomenda, pelo que fica visível nas suas exportações contabilísticas e utilizável numa nota de crédito.

O montante do desconto não pode ultrapassar o total dos produtos do carrinho. Nesse caso, o PrestaShop limita-o automaticamente.

Um desconto global no carrinho tem de ser repartido pelas taxas de IVA dos artigos que o originaram. Confirme com o seu contabilista certificado como o seu software de faturação certificado pela AT trata esta linha, sobretudo num carrinho que junte artigos a 23 % e a 6 %: é no documento certificado que a repartição conta, não no PDF do PrestaShop.

### Detalhe por oferta

O montante trazido por cada oferta aparece na posição escolhida nas definições. No modo acordeão, a linha Desconto(s) nativa torna-se clicável e abre o detalhe. O estado aberto ou fechado mantém-se nas atualizações Ajax do carrinho.

### Linhas de produtos

Com a opção **Selo e preço riscado nas linhas do carrinho**, cada linha em causa mostra o selo da oferta por baixo do preço unitário, o total inicial riscado e o preço com desconto por baixo. Nas ofertas X comprados Y oferecidos, uma menção indica o número de unidades oferecidas e o montante poupado.

### Incentivo a completar o lote

Quando faltam apenas alguns artigos para ativar uma oferta, um aviso «Oferta em curso» indica-o com uma frase do tipo «Mais 1 artigo e recebe 2 oferecidos». O botão **Adicionar** coloca diretamente as unidades em falta no carrinho.

### Linha do vale automático

A regra de carrinho gerada aparece normalmente na lista dos vales de desconto, quando o seu montante já está contabilizado na linha Desconto(s). A opção **Ocultar o vale de desconto automático**, ativa por predefinição, remove essa linha do resumo. O módulo identifica-a pelo nome, configurado nas definições gerais.

## Adaptar a apresentação ao seu tema

Há três templates que pode substituir. Copie-os de `/modules/dfquantitydeal/views/templates/hook/` para `/themes/o-seu-tema/modules/dfquantitydeal/views/templates/hook/`.

- `badge.tpl`: o selo gerado pelo hook `displayDfQdBadge`
- `offers.tpl`: o bloco das ofertas da página do produto
- `cart.tpl`: o detalhe das ofertas e os incentivos do carrinho

O CSS está isolado sob o prefixo `dfqd`. Para um ajuste pontual, aponte às classes a partir da folha de estilos do seu tema, em vez de alterar `views/css/front.css`, que seria substituído na atualização.

## Multiloja e multi-idioma

Cada oferta está associada às lojas que assinalar no separador Condições. Uma oferta criada numa loja não aparece nas outras enquanto não lhes for associada.

Os campos Nome, Texto do selo e Descrição são traduzidos nos idiomas instalados. O selo e as frases apresentadas seguem o idioma do cliente.

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

Instale o novo ZIP por cima do antigo a partir do gestor de módulos. Os scripts de atualização acrescentam as definições e os hooks surgidos desde a sua versão, sem tocar nas suas ofertas.

A passagem para a 1.1.5 renomeia o separador do menu em cada idioma instalado e dá ao hook `displayDfQdBadge` um título em inglês. Se o nome do desconto do carrinho tiver ficado no antigo valor predefinido «Offres quantitatives», é substituído pela sua tradução no idioma predefinido da loja. Um nome que tenha personalizado é mantido.

## Resolução de problemas

### O selo não aparece

1. Abra a configuração do módulo e leia o painel Diagnóstico: módulo ativado, hooks associados, ofertas ativas hoje.
2. Confirme que a oferta está ativa e que a data de hoje está dentro do período de validade.
3. Verifique o âmbito: um produto tem de estar explicitamente associado à oferta, ou pertencer a uma categoria ou marca assinalada.
4. Verifique os interruptores de apresentação, nas definições gerais e no separador Selo e apresentação da oferta.
5. Se o método de apresentação estiver em Manual, confirme que o seu template chama o hook `displayDfQdBadge`.
6. Se o grupo de clientes estiver restrito, teste com uma conta do grupo certo.
7. Limpe a cache do Smarty e a cache do seu servidor.

### Os selos aparecem duas vezes

O seu tema chama o hook `displayDfQdBadge` e o script front também injeta os selos. Mude o **Método de apresentação dos selos** para **Manual**.

### O desconto não é aplicado ao carrinho

A quantidade tem de atingir o limiar da oferta, segundo o modo de agrupamento escolhido. No modo Por combinação, seis unidades repartidas por três combinações não ativam uma oferta 4+2. Confirme também que o produto não está excluído pela opção sobre os produtos já em promoção.

### Duas ofertas sobrepõem-se

É o comportamento esperado: uma unidade consumida pela primeira oferta sai do cálculo da segunda. Se quiser que uma oferta passe antes da outra, baixe a sua prioridade.

### O selo ou o bloco das ofertas aparece no sítio errado

Para o selo, mude a posição da oferta para **Em linha (abaixo do preço)**, ou chame o hook `displayDfQdBadge` no ponto pretendido do seu template de miniatura. Para o bloco das ofertas, escolha outra posição ou use o seletor CSS personalizado.

### A ligação de teste dos selos devolve um erro 404

Limpe a cache em **Parâmetros avançados** e depois **Desempenho**, e volte a guardar as definições de **Tráfego & SEO** para regenerar os URL amigáveis.

## Desinstalação

A desinstalação elimina as oito tabelas do módulo, as suas chaves de configuração e o separador do menu Catálogo. As regras de carrinho já ligadas a encomendas anteriores são conservadas, para não alterar o seu histórico contabilístico.