# DataFirefly Loyalty: programa de fidelização Shopware 6

> Instalação, configuração e utilização do DataFirefly Loyalty: pontos, escalões, conversão em vales de compra e resolução de problemas.

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

## Apresentação

O DataFirefly Loyalty acrescenta um programa de fidelização completo ao Shopware 6: os seus clientes ganham pontos em cada encomenda, sobem de escalão com multiplicadores e convertem os pontos em vales de compra baseados nas promoções nativas do Shopware. A extensão funciona no Shopware 6.5, 6.6 e 6.7 com um único ZIP, sem qualquer compilação.

## Instalação

### A partir da administração

1. Vá a **Extensões > As minhas extensões**.
2. Clique em **Carregar uma extensão** e selecione o ficheiro `DfLoyalty-1.0.0.zip`.
3. Clique em **Instalar** e ative a extensão.

### Por linha de comandos

```
bin/console plugin:refresh
bin/console plugin:install --activate DfLoyalty
bin/console cache:clear
```

A instalação cria duas tabelas dedicadas: `df_loyalty_account` (uma linha por cliente) e `df_loyalty_transaction` (o registo de todas as operações de pontos).

Não é necessário qualquer build JavaScript: a extensão não contém módulo de administração compilado, o que garante a compatibilidade com os três ramos 6.5, 6.6 e 6.7.

## Configuração

Abra **Extensões > As minhas extensões > DataFirefly Loyalty > Configurar**. Todas as definições estão disponíveis por canal de venda: pode ativar o programa apenas numa loja, ou aplicar taxas diferentes consoante os canais.

### Atribuição dos pontos

- **Ativar o programa**: interruptor geral. Desativado, a página da conta de cliente devolve um erro 404 e nenhum ponto é atribuído.
- **Acionador de atribuição**: _Pagamento recebido_ (estado de transação `paid`, recomendado) ou _Encomenda concluída_ (estado de encomenda `completed`).
- **Pontos por unidade monetária**: número de pontos ganhos por euro gasto. Predefinição: 1.
- **Base de cálculo**: montante da encomenda com ou sem IVA.
- **Incluir os portes**: por predefinição, os portes são excluídos do cálculo.

### Escalões

São configuráveis três escalões, cada um com um nome, um limiar e um multiplicador. Os limiares aplicam-se aos **pontos acumulados ao longo da vida** (nunca decrementados por uma conversão), e o multiplicador aplica-se a todos os ganhos futuros.

- **Escalão 1**: predefinição Bronze, a partir de 0 pontos, multiplicador x1,0
- **Escalão 2**: predefinição Silver, a partir de 500 pontos, multiplicador x1,25
- **Escalão 3**: predefinição Gold, a partir de 2 000 pontos, multiplicador x1,5

Exemplo: um cliente Silver (x1,25) que faz uma encomenda de 100 € com IVA incluído, com uma taxa de 1 ponto/€, ganha 125 pontos.

### Conversão em vales de compra

- **Taxa de conversão**: número de pontos necessários por 1 € de vale. Predefinição: 100 (100 pontos = 1,00 €).
- **Mínimo de conversão**: número mínimo de pontos para iniciar uma conversão. Predefinição: 200.
- **Passo de conversão**: os pontos convertem-se em múltiplos deste valor. Predefinição: 100.
- **Validade dos vales**: tempo de vida do vale de compra em dias. Predefinição: 90.

## Funcionamento do lado do cliente

Uma entrada **Programa de fidelização** aparece no menu da conta de cliente. A página `/account/loyalty` apresenta:

- o saldo de pontos disponível e o total de pontos ganhos ao longo da vida;
- o escalão atual com uma barra de progresso para o escalão seguinte;
- o formulário de conversão em vale de compra;
- o histórico das últimas 50 operações (ganhos, conversões, anulações).

Quando um cliente converte os pontos, a extensão cria uma **promoção nativa do Shopware**: código único do tipo `LOYAL-XXXXXXXX`, reservado à conta dele, utilizável uma só vez, com um desconto fixo sobre o carrinho. O código aplica-se no carrinho como qualquer código promocional. Encontra todas as promoções geradas em **Marketing > Promoções**.

## Anulações e reembolsos

Quando uma encomenda passa ao estado _Cancelada_ ou o seu pagamento passa ao estado _Reembolsado_, os pontos ganhos nessa encomenda são automaticamente retirados. A operação fica registada no histórico do cliente com a etiqueta «Anulados». A retirada é idempotente: só pode acontecer uma vez por encomenda.

Na versão 1.0, um reembolso parcial não é rateado: é a passagem do pagamento completo ao estado _Reembolsado_ que aciona a retirada da totalidade dos pontos da encomenda.

## Segurança e integridade dos dados

- O débito dos pontos é atómico na base de dados: duas conversões simultâneas não podem gastar duas vezes o mesmo saldo.
- Cada operação é inscrita num registo apenas por adição, com referência da encomenda, tipo, pontos com sinal e código do vale quando aplicável.
- A criação do vale e a escrita contabilística são executadas na mesma transação SQL: nunca há vale sem débito nem débito sem vale.

## Resolução de problemas

### A ligação Programa de fidelização não aparece na conta

A extensão injeta a sua ligação através do bloco Twig `page_account_sidebar_link_orders`. Se o seu tema personalizado tiver removido ou renomeado esse bloco, acrescente a ligação manualmente no template da barra lateral da conta, apontando para a rota `frontend.account.dfloyalty.page`.

### Os pontos não são atribuídos

1. Verifique que o programa está ativo para o canal de venda em causa.
2. Verifique o acionador configurado: com _Pagamento recebido_, a transação tem de atingir o estado `paid`; com _Encomenda concluída_, a encomenda tem de atingir `completed`.
3. Limpe a cache depois de uma alteração de configuração: `bin/console cache:clear`.

### Desinstalação

Na desinstalação, o Shopware propõe conservar os dados. Se desmarcar essa opção, as tabelas `df_loyalty_account` e `df_loyalty_transaction` são eliminadas definitivamente; as promoções já geradas mantêm-se porque são promoções normais do Shopware.