# Smart Loyalty Tiers: documentação completa

> Introdução O Smart Loyalty Tiers é um programa de fidelidade completo para WooCommerce. Ao contrário da maioria dos plugins de fidelidade, que se limitam a um simples contador de pontos…

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

## Introdução

O Smart Loyalty Tiers é um programa de fidelidade completo para WooCommerce. Ao contrário da maioria dos plugins de fidelidade, que se limitam a um simples contador de pontos nas compras, o Smart Loyalty Tiers propõe **5 fontes de ganho distintas**, **4 níveis VIP progressivos** com recompensas concretas (portes grátis vitalícios, acesso antecipado às novidades, apoio prioritário), um sistema de **distintivos de gamificação**, e a conversão dos pontos num **cupão WooCommerce de utilização única**.

**Compatibilidade:** pronto para HPOS, blocos Cart e Checkout, Polylang Pro e WPML, WordPress Multisite. Testado até ao WooCommerce 9.5.

## Instalação e ativação

1. Descarregue o ficheiro ZIP `smart-loyalty-tiers.zip` a partir da sua área de cliente DataFirefly.
2. No WordPress, vá a **Plugins → Adicionar plugin → Carregar plugin**.
3. Selecione o ZIP e clique em **Instalar agora**.
4. Clique em **Ativar**.

Na ativação, o plugin cria automaticamente 9 tabelas na base de dados (prefixo `wp_slt_`), inicializa os 4 níveis Bronze / Silver / Gold / Platinum, insere 10 distintivos de conquista predefinidos, acrescenta o endpoint `loyalty` a A minha conta do WooCommerce, e agenda 2 tarefas cron (expiração diária, recálculo horário dos níveis).

**Requisitos:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (recomendado 8.1+). O plugin recusa ativar-se se o WooCommerce não estiver instalado e ativo.

## Configuração em 3 minutos

Depois da ativação, aparece um novo menu **Loyalty** na barra lateral da administração com 5 subpáginas: Dashboard, VIP Tiers, Membros, Distintivos, Definições.

### Etapa 1: taxa de ganho (Loyalty → Definições)

Ajuste os valores predefinidos conforme a sua estratégia:

- **Pontos por euro gasto**: por predefinição 1 (ou seja, 1 pt por 1 €)
- **Pontos por avaliação de produto**: por predefinição 50
- **Pontos por apadrinhamento**: por predefinição 500
- **Pontos por inscrição na newsletter**: por predefinição 100
- **Pontos por partilha social**: por predefinição 25

### Etapa 2: conversão em cupão

- **Taxa de conversão**: por predefinição 100 pontos = 1 € de desconto
- **Limiar mínimo de conversão**: por predefinição 500 pontos
- **Limite do cupão**: por predefinição 30% do subtotal do carrinho

### Etapa 3: apresentação e gamificação

- **Designação dos pontos**: por predefinição «pontos» (por exemplo: «milhas», «estrelas», «fireflies»)
- **Gamificação ativa**: ativa a sobreposição de celebração na subida de nível
- **Notificações por e-mail**: ativa os e-mails de subida de nível e de distintivo conquistado

## Os 4 níveis VIP

Cada cliente é colocado automaticamente num nível em função do seu **total de pontos acumulados ao longo da vida** (pontos lifetime, independentemente do que gastou em cupões). Os níveis criados na ativação:

- **Bronze**: 0 pontos, sem benefícios especiais, nível de entrada
- **Silver**: 500 pontos acumulados, multiplicador ×1,25 nos pontos de compra, acesso antecipado de 12h
- **Gold**: 2000 pontos acumulados, multiplicador ×1,5, portes grátis, apoio prioritário, acesso antecipado de 24h
- **Platinum**: 5000 pontos acumulados, multiplicador ×2, portes grátis vitalícios, acesso antecipado de 48h, produtos exclusivos, 500 pontos de bónus de aniversário

A partir de **Loyalty → VIP Tiers**, cada nível é editável em direto com um seletor de cor. Os benefícios configuráveis:

- **Multiplicador de pontos** (points_multiplier): aplicado automaticamente a todos os pontos ganhos nas compras
- **Portes grátis** (free_shipping): as rates do WooCommerce são colocadas a zero no cálculo do carrinho
- **Acesso antecipado em horas** (early_access_hours): define quantas horas antes da data de embargo de um produto este nível o pode ver e comprar
- **Apoio prioritário** (priority_support): acrescenta um distintivo laranja nas encomendas na administração e um cabeçalho `X-Priority` nos e-mails transacionais
- **Bónus de aniversário** (birthday_bonus): pontos creditados automaticamente no dia de aniversário do cliente (se estiver indicado no perfil)
- **Produtos exclusivos** (exclusive_products): ativa a lógica de filtragem por nível nos produtos marcados como exclusivos

Pode acrescentar tantos níveis quantos quiser. O recálculo faz-se automaticamente a cada ganho de pontos, com uma salvaguarda horária por cron para garantir a coerência.

## As 5 fontes de pontos

### 1. Compras (PurchaseAction)

Os pontos são creditados quando a encomenda passa ao estado **concluída** (`woocommerce_order_status_completed`). O cálculo:

```
pontos = subtotal sem IVA × pontos_por_euro × multiplicador_do_nível
```

O sistema é **idempotente**: é impossível ganhar duas vezes na mesma encomenda, mesmo que o estado oscile. Num reembolso total ou parcial, os pontos são automaticamente **revertidos** proporcionalmente ao montante reembolsado.

### 2. Avaliações de produto (ReviewAction)

Os pontos são creditados na publicação de uma avaliação validada (`comment_post` ou `transition_comment_status → approved`). Uma opção **«Verificar que o cliente é comprador»** permite limitar os ganhos às avaliações de compradores reais (proteção anti-spam).

### 3. Apadrinhamento (ReferralAction)

Cada utilizador recebe um **código de apadrinhamento único** e uma **ligação de partilha**. O seguimento faz-se por um cookie de 30 dias (duração configurável através de `slt_referral_cookie_days`). O padrinho ganha os pontos quando o afilhado conclui a **primeira encomenda**. É possível creditar ao afilhado um bónus de boas-vindas opcional.

### 4. Newsletter (NewsletterAction)

Dois modos de disparo:

- **Caixa de seleção no checkout**: tratada automaticamente se a caixa for assinalada
- **Hook público**: `do_action('slt_newsletter_subscribed', $user_id, $email)`, que pode chamar a partir do Mailchimp, do Brevo, do MailPoet, do Klaviyo ou de qualquer outro sistema

Para um formulário nativo, use o shortcode `[slt_newsletter_form]`.

### 5. Partilhas sociais (SocialShareAction)

7 plataformas suportadas através do shortcode `[slt_share_buttons]`: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram e e-mail. Cada partilha é registada com um limite anti-abuso:

- Máximo de **5 partilhas por dia** por utilizador (configurável)
- Uma mesma partilha _(utilizador, plataforma, URL)_ só conta uma vez

## As recompensas concretas

### Portes grátis vitalícios

Nos níveis com `free_shipping: true`, todas as _package rates_ do WooCommerce são colocadas a zero no cálculo do carrinho. Sem cupão para introduzir e sem manipulação. Aparece automaticamente um aviso verde no carrinho: «✨ Portes grátis, estatuto VIP».

### Acesso antecipado às novidades

Em cada produto, uma metabox **«Acesso antecipado Loyalty»** permite definir uma data de embargo (`_slt_embargo_until`). Enquanto a data não for atingida, o produto fica:

- **Não comprável** para os níveis abaixo do limiar configurado (filtro `woocommerce_is_purchasable`)
- **Invisível nas listagens** (filtro `woocommerce_product_query`)

Os níveis com `early_access_hours > 0` podem ver e comprar o produto na janela definida antes do levantamento público do embargo. Uma faixa âmbar na ficha de produto informa os clientes elegíveis.

### Apoio prioritário

Nos níveis com `priority_support: true`, cada encomenda feita pelo cliente:

- Recebe um **distintivo «Priority»** laranja visível na lista de encomendas da administração (HPOS e legacy)
- Leva um cabeçalho `X-Priority: high` injetado nos e-mails transacionais, útil para filtrar no seu helpdesk (Zendesk, Freshdesk, Help Scout, etc.)

## Sistema de distintivos (gamificação)

São criados 10 distintivos de conquista na ativação:

- **First Purchase**: primeira encomenda
- **Regular Customer**: 5 encomendas acumuladas
- **Power Buyer**: 10 encomendas acumuladas
- **Reviewer**: primeira avaliação publicada
- **Critic**: 10 avaliações publicadas
- **Brand Ambassador**: primeiro apadrinhamento bem-sucedido
- **Influencer**: 5 apadrinhamentos bem-sucedidos
- **Social Butterfly**: 10 partilhas sociais
- **Insider**: inscrição na newsletter
- **Big Spender**: 1000 € gastos ao longo da vida

A partir de **Loyalty → Distintivos**, edite os distintivos existentes ou crie novos. Cada distintivo tem um critério em JSON:

```
{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // para os triggers baseados em contagem
  "amount": 1000.00       // para lifetime_spend (montante na moeda)
}
```

Um distintivo pode também conceder um **bónus de pontos** no desbloqueio.

## Conversão dos pontos em cupão

A partir de **A minha conta → Loyalty**, o cliente introduz o número de pontos a converter e clica em «Gerar cupão». O plugin:

1. Cria um objeto `WC_Coupon` único e de utilização única
2. Limita o cupão ao endereço de e-mail do cliente
3. Fixa uma expiração a 30 dias
4. Deduz os pontos do saldo e regista a transação

Um limite **slt_max_redemption_percent** (30% por predefinição) impede o cupão de ultrapassar uma percentagem do subtotal do carrinho, como proteção contra a diluição da margem.

## Os 7 shortcodes do front-end

### [slt_balance]

Apresenta o saldo de pontos do cliente com sessão iniciada. Atributo opcional: `label="milhas"`.

```
[slt_balance label="fireflies"]
```

### [slt_tier_badge]

Apresenta o nome do nível atual num distintivo colorido (cor do nível).

```
[slt_tier_badge]
```

### [slt_progress_bar]

Barra de progresso animada para o nível seguinte, com o número de pontos em falta e um efeito shimmer.

```
[slt_progress_bar]
```

### [slt_tiers_table]

Tabela comparativa de todos os níveis com os respetivos limiares e benefícios, ideal para uma página «Programa de fidelidade».

```
[slt_tiers_table]
```

### [slt_referral_link]

Apresenta a ligação de apadrinhamento única do cliente, mais um botão de copiar e um contador de apadrinhamentos bem-sucedidos.

```
[slt_referral_link]
```

### [slt_share_buttons]

Botões de partilha social. Atributos:

- `url`: URL a partilhar (por predefinição, o URL da página atual)
- `title`: título a partilhar (por predefinição, o título da página)
- `platforms`: lista separada por vírgulas (por predefinição, todas)

```
[slt_share_buttons platforms="facebook,twitter,whatsapp"]
```

### [slt_newsletter_form]

Formulário de inscrição na newsletter com crédito automático dos pontos na subscrição.

```
[slt_newsletter_form title="Junte-se à nossa newsletter VIP"]
```

## Área de cliente (A minha conta → Loyalty)

É acrescentado automaticamente um novo separador **Loyalty** a seguir ao painel de A minha conta do WooCommerce. O cliente encontra aí:

- Um **bloco de destaque colorido** com a cor do seu nível, o saldo e o estatuto
- A sua **barra de progresso** para o nível seguinte
- A **lista dos benefícios atuais**
- O **formulário de conversão em cupão** (se o saldo ultrapassar o limiar mínimo)
- A **grelha de todos os distintivos** (conquistados a cores, bloqueados a cinzento)
- O **histórico completo de transações** (as 25 últimas entradas por predefinição)

## Painel de administração (Loyalty → Dashboard)

O painel de administração mostra estatísticas dos últimos 30 dias:

- Número total de membros e de membros ativos em 30 dias
- Pontos em circulação (soma dos saldos ativos)
- Pontos ganhos e trocados em 30 dias
- Apadrinhamentos concluídos em 30 dias
- Distribuição dos membros por nível (barras)
- Atividade recente (as 20 últimas transações de todos os membros)

A partir da página **Membros**, pode pesquisar um cliente, ver o seu saldo e o seu nível, e **ajustar-lhe manualmente os pontos** (atribuir ou deduzir) através de uma modal AJAX com justificação.

## E-mails transacionais

São enviados automaticamente dois e-mails HTML responsivos:

### Subida de nível

Enviado na passagem para um novo nível. Contém:

- Uma faixa com a cor do novo nível e um troféu
- A lista dos novos benefícios desbloqueados
- Um CTA para a área Loyalty

O template pode ser substituído copiando-o para `o-seu-tema/smart-loyalty-tiers/emails/tier-upgrade.php`.

### Distintivo conquistado

Enviado no desbloqueio de um novo distintivo, com o nome, a descrição e o eventual bónus de pontos creditado.

## Hooks para programadores

Cada ação do plugin dispara hooks que permitem estender sem tocar no código:

```
// Após o crédito de pontos
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// Após a dedução de pontos
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Mudança de nível
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Distintivo desbloqueado
do_action('slt_badge_awarded', $user_id, $badge);

// Apadrinhamento bem-sucedido
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Inscrição na newsletter (a disparar a partir da sua integração)
do_action('slt_newsletter_subscribed', $user_id, $email);
```

## Compatibilidade com HPOS e com os blocos Cart / Checkout

O plugin declara automaticamente a compatibilidade HPOS através do `FeaturesUtil::declare_compatibility()`. Todas as leituras de encomenda passam pela API CRUD do WooCommerce (`wc_get_order()`), sem qualquer consulta direta a `wp_posts`.

A compatibilidade com os blocos **Cart** e **Checkout** também é declarada. Os portes grátis aplicam-se nos dois modos (clássico e blocos).

## Multilingue (Polylang e WPML)

O plugin é totalmente traduzível através do `load_plugin_textdomain` com o textdomain `smart-loyalty-tiers`. O francês e o inglês são fornecidos, e está incluído um ficheiro POT completo para qualquer outro idioma.

Nos sites multilingues:

- **Polylang Pro**: os nomes dos níveis e dos distintivos podem ser traduzidos através da interface de String Translations do Polylang
- **WPML**: as mesmas cadeias são registadas com o WPML através do `icl_register_string`

## FAQ e resolução de problemas

### Um cliente não vê os pontos creditados depois de uma encomenda

Verifique que a encomenda está mesmo no estado **concluída** (o plugin não atribui pontos em «em processamento» ou «pendente»). Se o estado estiver correto, vá a **Loyalty → Membros**, procure o cliente e verifique o histórico.

### Os portes não são oferecidos a um cliente Gold

Verifique em **Loyalty → VIP Tiers** que o benefício _«Portes grátis»_ está mesmo assinalado no nível Gold. Limpe também as caches de sessão do WooCommerce (`wc_clear_cart_cache()`).

### O endpoint A minha conta → Loyalty devolve um 404

Vá a **Definições → Permalinks** e clique em «Guardar alterações» para fazer flush às rewrite rules. É necessário apenas uma vez, depois da ativação.

### O cron não dispara

Nos sites de baixo tráfego, o cron do WordPress pode ser irregular. Configure um verdadeiro cron de sistema para chamar o `wp-cron.php` a cada 5 a 15 minutos, e desative o pseudo-cron no `wp-config.php`:

```
define('DISABLE_WP_CRON', true);
```

### Um cliente reclama pontos na sequência de um reembolso total

É o comportamento normal: num reembolso total ou parcial, os pontos correspondentes são deduzidos automaticamente. Se o cliente insistir, pode recreditar-lhe manualmente os pontos em **Loyalty → Membros → Ajustar**.

### Como desativar a expiração dos pontos?

Em **Loyalty → Definições**, coloque a _«Duração até à expiração»_ a **0 dias**. Os pontos nunca serão eliminados.

**Suporte:** para qualquer questão não coberta aqui, contacte o nosso suporte prioritário em [support@datafirefly.com](mailto:support@datafirefly.com). Resposta em 24 horas úteis durante o seu ano de suporte incluído.