# Arredondamento Solidário e Donativo no Checkout: guia completo

> Apresentação O módulo Arredondamento Solidário e Donativo no Checkout (dfsolidarityround) permite aos seus clientes apoiar uma associação em poucos segundos, diretamente no carrinho: arredondando a encomenda para o euro seguinte,…

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

## Apresentação

O módulo **Arredondamento Solidário e Donativo no Checkout** (`dfsolidarityround`) permite aos seus clientes apoiar uma associação em poucos segundos, diretamente no carrinho: **arredondando a encomenda para o euro seguinte**, escolhendo um **montante de donativo predefinido** ou indicando um **montante livre**. O donativo integra-se de forma limpa no total, ficando o IVA, a moeda e a multiloja a cargo do núcleo do PrestaShop, até à fatura.

O donativo não é uma simples apresentação visual: é suportado por um produto virtual dedicado e por um preço específico limitado ao carrinho do cliente. O montante aparece por isso naturalmente nos totais, na encomenda e na fatura.

## Compatibilidade

- PrestaShop 8.0 a 9.x
- Loja única e multiloja
- PHP 7.4 a 8.3
- Tema Classic e temas personalizados
- Interface fornecida em francês, inglês, espanhol, alemão e italiano
- Sem dependências (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 `dfsolidarityround.zip`.
3. Depois de instalado, clique em **Configurar**.

Na instalação, o módulo cria a sua tabela de histórico, regista os seus hooks (recursos do front-office, bloco no carrinho e no checkout, validação da encomenda), acrescenta o separador de back-office **Donativos solidários** e gera um **produto virtual oculto «Donativo solidário»**: não visível na loja, sem IVA e sem portes. É ele que suporta o montante do donativo no carrinho. Não o elimine manualmente.

## Configuração

### Modos de donativo

Estão disponíveis três modos, que se ativam de forma independente. Pode propor apenas um, ou os três em simultâneo.

- **Arredondamento para o euro seguinte**: propõe ao cliente que leve a sua encomenda até ao montante redondo seguinte. O **passo de arredondamento** é configurável (`1,00` para o euro seguinte, `0,50` para o meio euro, etc.).
- **Montantes fixos**: apresenta botões prontos a clicar. A lista de montantes é configurável (por exemplo, `1;2;5`).
- **Montante livre**: deixa o cliente indicar a quantia que quiser, limitada por um **donativo mínimo** e um **donativo máximo**.

No modo de arredondamento, se o total do carrinho já for um montante redondo, o módulo propõe um donativo de um passo completo, para que a adesão do cliente faça sempre sentido.

### Personalização da associação

- **Título do bloco**: texto apresentado no topo do bloco (campo multilingue).
- **Nome da associação**: nome da causa apoiada (campo multilingue).
- **Descrição**: texto curto de acompanhamento (campo multilingue).
- **Logótipo da associação**: imagem apresentada no bloco (PNG, JPG, GIF, WEBP ou SVG).

### Locais de apresentação

- **Apresentar na página do Carrinho**: apresenta o bloco no fundo da página do carrinho (local principal e fiável).
- **Apresentar no processo de encomenda**: apresenta o bloco no resumo da encomenda, se o seu tema expuser o local correspondente.

## Funcionamento do lado do cliente

### Arredondamento para o euro seguinte

O cliente vê um botão do tipo «Arredondar e doar 0,73 €». O montante proposto corresponde à diferença entre o seu total e o montante redondo seguinte, segundo o passo configurado.

### Montantes fixos

O cliente clica num dos montantes propostos (1 €, 2 €, 5 €...). O donativo correspondente é acrescentado de imediato.

### Montante livre

O cliente indica o montante que quiser e valida. O valor é verificado face ao mínimo e ao máximo definidos.

Depois de acrescentado o donativo, o bloco apresenta um agradecimento e uma ligação «Retirar o donativo». O cliente mantém o controlo: pode mudar de montante ou retirar o donativo a qualquer momento antes do pagamento.

## Como o donativo é acrescentado ao carrinho

Em cada escolha, o módulo cria um **preço específico** (`SpecificPrice`) limitado ao carrinho atual (`id_cart`) e aplica-o ao produto virtual «Donativo solidário». Este produto é acrescentado ao carrinho quando o montante é superior a zero e retirado caso contrário. O PrestaShop aplica então a moeda e o contexto multiloja, e o donativo aparece como uma linha clara nos totais, na encomenda e na fatura.

### Recálculo automático do arredondamento

No modo de arredondamento, o montante do donativo é **recalculado em cada apresentação do bloco**. Assim, se o cliente alterar o carrinho depois de ter escolhido o arredondamento, o donativo mantém-se coerente com o novo total até ao pagamento.

### Donativo sem IVA

O produto «Donativo solidário» é criado **sem regra de imposto**: o montante apresentado e cobrado corresponde exatamente ao gesto do cliente, sem surpresas de IVA.

## Acompanhamento dos donativos no back-office

É acrescentado um separador **Donativos solidários** em **Encomendas** (controlador `AdminDfDonations`). Lista cada donativo com:

- o **montante** do donativo;
- o **modo** utilizado (arredondamento, montante fixo ou montante livre);
- o **cliente** e a **encomenda** associada;
- a **data** do donativo.

Uma faixa de síntese apresenta o **total recolhido** e o número de donativos. O donativo é fixado no histórico na **validação da encomenda** (`actionValidateOrder`).

## Entrega dos donativos à associação

O módulo **não entrega automaticamente** os donativos à associação: é uma opção deliberada. Recolhe os donativos dentro das suas encomendas e fornece-lhe o total e o histórico. Mantém o controlo sobre o momento e o canal de entrega à sua associação parceira, segundo o seu próprio processo.

## Compatibilidade com o PrestaShop 9

O módulo foi concebido e testado do PrestaShop 8.0 ao 9.x:

- o controlador do back-office utiliza `ModuleAdminController`, compatível com o 8 e o 9;
- o código evita os métodos removidos no PrestaShop 9 (token AJAX e formatação de preços portáveis);
- o controlador AJAX devolve diretamente JSON, sem override de assinatura incompatível.

## FAQ e resolução de problemas

### O bloco não aparece no processo de encomenda

O bloco aparece de forma fiável no fundo da página do carrinho. No resumo da encomenda, a apresentação depende do tema, que tem de expor o local correspondente. O donativo escolhido na página do carrinho é, de qualquer forma, conservado até ao pagamento.

### O total não é atualizado depois do clique

O bloco despoleta uma atualização do carrinho depois de acrescentar ou retirar o donativo. Limpe a cache do PrestaShop e recarregue a página. Verifique também se o produto «Donativo solidário» não foi eliminado manualmente.

### A loja fica em branco depois da instalação

Certifique-se de que está a utilizar a versão mais recente do módulo e limpe a cache. O produto de donativo é propositadamente não visível na loja; não o torne visível nem o elimine manualmente.

### O donativo de arredondamento parece-me incorreto

Verifique o **passo de arredondamento** configurado. No modo de arredondamento, o donativo é recalculado em cada apresentação do bloco a partir do total sem donativo; se o carrinho mudar, o montante é ajustado automaticamente.

### Como traduzir o bloco para outro idioma?

O título, o nome da associação e a descrição são campos multilingues: selecione cada idioma na configuração para os traduzir. As legendas de interface traduzem-se em **Parâmetros avançados > Traduções > Traduções dos módulos instalados**, escolhendo `dfsolidarityround`.

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

Sim. O módulo foi concebido e testado do PrestaShop 8.0 ao 9.x, tanto em loja única como em multiloja.

## Desinstalação

A desinstalação elimina o produto «Donativo solidário», o separador do back-office e a tabela de histórico dos donativos. Se quiser conservar o histórico, desative o módulo sem o desinstalar.