# Embrulho para Oferta e Mensagem: guia completo

> Apresentação O módulo Embrulho para Oferta e Mensagem (dfgiftwrap) acrescenta, no funil de encomenda, a escolha de um embrulho para oferta pago e de um cartão de mensagem personalizado. O…

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

## Apresentação

O módulo **Embrulho para Oferta e Mensagem** (`dfgiftwrap`) acrescenta, no funil de encomenda, a escolha de um **embrulho para oferta pago** e de um **cartão de mensagem personalizado**. O cliente seleciona uma opção de embrulho ilustrada, pode juntar-lhe uma mensagem livre, e os custos correspondentes integram-se de forma limpa no total da encomenda, sendo o IVA, a moeda e o multiloja geridos pelo núcleo do PrestaShop, até à fatura.

Os custos não são uma simples apresentação: são suportados por um produto-custo dedicado e um preço específico limitado ao carrinho do cliente. O montante encontra-se portanto naturalmente nos totais, na encomenda e na fatura, com o IVA correto.

A interface é entregue em francês. Numa loja em português, traduza as cadeias do checkout (« Embrulho para oferta », « Adicionar um cartão de mensagem », contador de caracteres) em Parâmetros avançados > Traduções > Traduções dos módulos instalados, e preencha o nome de cada opção de embrulho no seu campo multilingue em pt.

## Compatibilidade

- PrestaShop 8.0 a 9.x
- Monoloja e multiloja
- PHP 7.4 a 8.3
- Tema Classic e temas personalizados
- Interface entregue em francês e inteiramente traduzível
- Nenhuma dependência (nem Composer nem framework)

## Instalação

1. No back-office, abra **Módulos > Gestor de módulos**.
2. Clique em **Instalar um módulo** e selecione o ficheiro `dfgiftwrap.zip`.
3. Depois de instalado, clique em **Configurar**.

Na instalação, o módulo cria as suas tabelas, regista os seus hooks (recursos do front-office, bloco no checkout, validação de encomenda, ficha de encomenda no BO, confirmação) e gera um **produto-custo oculto** (referência `DF-GIFTWRAP-FEE`): virtual, não visível na loja, preço não apresentado. É ele que suporta o montante embrulho + cartão no carrinho. Não o elimine manualmente.

## Configuração

### Definições gerais

- **Ativar o embrulho para oferta**: mostra ou oculta o bloco das opções de embrulho no checkout.
- **Ativar o cartão de mensagem**: mostra ou oculta a opção cartão + mensagem.
- **Preço do cartão**: montante (sem IVA) cobrado quando o cliente adiciona um cartão de mensagem.
- **Comprimento máximo da mensagem**: número de caracteres autorizados (200 por defeito). Um contador acompanha o cliente durante a escrita.
- **Grupo de regras de imposto**: grupo de IVA aplicado aos custos de embrulho e de cartão.

### Gerir as opções de embrulho

A partir da página de configuração, clique em **« Gerir as opções »** para abrir o ecrã dedicado (controlador `AdminDfGiftWrapOptions`). Cria aí tantas opções quantas quiser, cada uma com:

- **Nome**: designação multilingue da opção (ex. « Papel kraft elegante », « Caixa de oferta premium »).
- **Preço**: montante sem IVA da opção de embrulho.
- **Imagem**: visual que ilustra a opção (normalizado automaticamente em JPG).
- **Posição**: ordem de apresentação, modificável por arrastar e largar.
- **Ativo**: mostra ou oculta a opção do lado da loja sem a eliminar.

O nome é um campo multilingue: selecione cada idioma no seletor do campo para traduzir o título da opção.

## Funcionamento

### No checkout

O bloco de embrulho e de cartão é injetado no topo do resumo da encomenda através do hook `displayCheckoutSummaryTop`. O cliente escolhe uma opção de embrulho, ativa eventualmente o cartão e escreve a sua mensagem. A seleção é registada em AJAX. Como a escolha altera o montante, o total é atualizado para refletir os custos; a mensagem, essa, é registada sem recarregamento supérfluo.

### Mecanismo dos custos

A cada seleção, o módulo calcula o montante total (opção de embrulho + cartão) e cria um **preço específico** (`SpecificPrice`) limitado ao carrinho atual, aplicado ao produto-custo oculto. Este produto é adicionado ao carrinho quando o montante é superior a zero, e retirado caso contrário. O PrestaShop aplica então o IVA, a moeda e o contexto multiloja, e o custo aparece como uma linha normal nos totais, na encomenda e na fatura.

### Onde aparece a mensagem

Na validação da encomenda (`actionValidateOrder`), a seleção é fixada. A mensagem escrita pelo cliente é visível em três locais:

- na **ficha de encomenda no back-office** (bloco dedicado via `displayAdminOrderMain`);
- na **página de confirmação** apresentada ao cliente depois da compra;
- no **campo de oferta nativo** da encomenda (`gift_message`, com `gift = 1`), o que a faz aparecer nos e-mails padrão do PrestaShop.

Como a mensagem é também escrita no campo de oferta nativo, os seus modelos de e-mail e as suas ferramentas de preparação que já exploram esse campo mostram a mensagem do cliente sem configuração adicional.

## FAQ e resolução de problemas

### Trata-se de um cartão-oferta ou de um vale de compra?

Não. O módulo gere um serviço de embrulho para oferta e um cartão de mensagem para oferecer, não um meio de pagamento nem um vale de compra. O cliente paga um embrulho e pode juntar-lhe uma dedicatória.

### O custo não aparece no total

Verifique que o produto-custo oculto (`DF-GIFTWRAP-FEE`) ainda existe e que pelo menos uma opção de embrulho está ativa. Limpe a cache do PrestaShop e recarregue a página de encomenda. O custo só se aplica quando o montante calculado é superior a zero.

### A página inicial ou a loja fica em branco depois da instalação

Certifique-se de que usa a última versão do módulo e limpe a cache. O produto-custo é voluntariamente não visível na loja; não o torne visível nem o elimine manualmente.

### A mensagem é cortada

A mensagem é limitada pela definição **Comprimento máximo da mensagem**. Aumente este valor na configuração se os seus clientes precisarem de textos mais longos.

### Como acrescentar o português ou outro idioma?

A interface é entregue em francês e inteiramente traduzível. Vá a **Parâmetros avançados > Traduções > Traduções dos módulos instalados**, escolha `dfgiftwrap` e o idioma, e traduza as cadeias. Os nomes das opções de embrulho traduzem-se diretamente no seu campo multilingue.

### É compatível com o PrestaShop 9?

Sim. O módulo foi concebido e testado do PrestaShop 8.0 ao 9.x, com um controlador de administração legacy, em monoloja como em multiloja.