# DfPreorder SW: guia completo

> O Shopware não oferece nativamente qualquer função «Avise-me quando voltar a haver stock». O DfPreorder SW preenche essa lacuna: em cada página de produto esgotado aparece automaticamente um formulário de…

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

O Shopware não oferece nativamente qualquer função «Avise-me quando voltar a haver stock». O DfPreorder SW preenche essa lacuna: em cada página de produto esgotado aparece automaticamente um formulário de inscrição, e o cliente recebe um alerta por email, no seu próprio idioma, assim que o produto regressa. A extensão acrescenta também um modo de pré-encomenda leve (selo e data de expedição prevista) e um módulo de administração para acompanhar as inscrições. Um único ZIP instala-se no Shopware 6.5, 6.6 e 6.7. Este guia cobre a instalação, a compilação dos recursos, o worker e a tarefa agendada, a configuração, a utilização no storefront, o modo de pré-encomenda, os emails, a Store API, a conformidade com o RGPD e a resolução de problemas.

Compatível com Shopware 6.5.x, 6.6.x e 6.7.x numa única base de código. Não é acrescentada qualquer dependência Composer. Ao contrário de algumas extensões entregues com um dist pré-compilado, o DfPreorder inclui o código-fonte JavaScript: é necessária uma compilação do storefront e da administração depois da instalação (ver abaixo).

## Como funciona a deteção do regresso ao stock

O DfPreorder deteta os reabastecimentos de duas formas complementares, que convergem para um mesmo processamento idempotente, pelo que os seus clientes são sempre avisados, e nunca duas vezes:

- **Em tempo real**: um subscritor escuta a escrita dos produtos e reage assim que o stock ou o stock disponível muda.
- **Varredura agendada**: uma tarefa agendada corre a cada 15 minutos e apanha as atualizações de stock feitas em SQL direto, tipicamente a decrementação do stock disponível na colocação de uma encomenda, ou uma importação ERP, que não acionam qualquer evento aplicacional.

O formulário de lista de espera aparece numa página de produto quando se reúnem duas condições: o produto está em modo «esgotado oculta a disponibilidade» (closeout) _e_ o seu stock disponível chegou a zero.

## Instalação

1. Transfira o arquivo `DfPreorder-v1.0.0.zip` a partir da sua conta DataFirefly.
2. Copie a pasta descomprimida `DfPreorder` para `custom/plugins/`, ou instale o ZIP em **Administração → Extensões → As minhas extensões → Carregar extensão**.
3. Instale e ative a extensão: ``` bin/console plugin:refresh bin/console plugin:install --activate DfPreorder ```
4. Compile os recursos do storefront e da administração (passo indispensável, não é fornecido qualquer dist): ``` ./bin/build-storefront.sh ./bin/build-administration.sh ```
5. Limpe a cache: ``` bin/console cache:clear ```

Na instalação, a extensão cria a tabela `df_stock_notification`, o conjunto de campos personalizados `df_preorder` na entidade produto, dois modelos de email e a tarefa agendada. Na desinstalação sem conservação dos dados, tudo é eliminado.

## Worker e tarefa agendada

Para que os emails sejam realmente enviados, dois mecanismos têm de estar a correr, o que em produção costuma já acontecer através do admin-worker, do systemd ou do cron:

- O **worker Messenger**, que consome a mensagem assíncrona de reabastecimento e envia os emails;
- O **agendador de tarefas**, que aciona a varredura de segurança a cada 15 minutos.

```
bin/console messenger:consume async --time-limit=60
bin/console scheduled-task:run
```

Se nem o worker nem o agendador estiverem a correr, as inscrições são registadas mas nenhum email é enviado. É a causa número um de «a extensão não notifica ninguém». Verifique o estado do admin-worker em **Definições → Sistema → Fila de mensagens** e o das tarefas agendadas em **Definições → Sistema → Tarefas agendadas**.

## Configuração

Abra **Extensões → As minhas extensões → DataFirefly Pré-encomenda e Lista de Espera → ⋯ → Configurar**. Todas as opções são reguláveis **por canal de venda** graças ao seletor nativo no topo da página.

- **Ativar a lista de espera**: interruptor principal. Apresenta o formulário nas páginas esgotadas.
- **Duplo opt-in**: exige uma confirmação por email antes de ativar a inscrição (recomendado para o RGPD). Desativado por predefinição.
- **Autorizar visitantes**: se desativado, só os clientes com sessão iniciada se podem inscrever.
- **Eliminar a inscrição após a notificação**: minimização dos dados; o endereço de email é apagado assim que o alerta é enviado. Se desativado, a inscrição é conservada com o estado «notificado».
- **Notificações por lote**: número máximo de emails enviados por execução (worker ou varredura). 100 por predefinição.
- **Mostrar o selo de pré-encomenda**: ativa a apresentação do selo e da data de expedição nos produtos configurados em pré-encomenda.

## A lista de espera no storefront

Quando um produto está esgotado (closeout e stock disponível a zero), o formulário «Ser avisado do regresso ao stock» aparece automaticamente sob o botão de compra. O cliente introduz o seu email (pré-preenchido se tiver sessão iniciada) e valida.

- A submissão é feita em **AJAX** com uma alternativa completa sem JavaScript (mensagem flash e reencaminhamento).
- Um campo **honeypot** invisível filtra os robots.
- Se o **duplo opt-in** estiver ativo, é enviado um email de confirmação; a inscrição só fica ativa depois do clique na ligação de confirmação.
- Cada email pode conter uma **ligação de cancelamento da subscrição num clique**.

O formulário é renderizado num template sobreponível: `views/storefront/component/df-waitlist/waitlist-form.html.twig`, injetado através do buy-widget. Sobreponha-o no seu tema para alterar o aspeto ou a posição.

## Modo de pré-encomenda

A extensão cria um grupo de campos personalizados **Pré-encomenda** na entidade produto. Abra um produto em **Catálogos → Produtos**, separador **Especificações → Campos personalizados**, grupo **Pré-encomenda**:

- **Ativar a pré-encomenda**: interruptor de ativação para este produto.
- **Data de expedição prevista**: a data apresentada no selo.
- **Nota de pré-encomenda**: texto livre apresentado sob o selo.

Quando a pré-encomenda está ativa e o selo está autorizado na configuração, aparece um selo âmbar acima do botão de compra com a data de expedição prevista. A renderização está isolada no template do buy-widget e mantém-se sobreponível.

## Emails e traduções

São criados dois modelos de email na instalação, traduzidos em cinco idiomas: francês, inglês, alemão, espanhol e italiano:

- **Regresso ao stock** (`df_preorder.back_in_stock`): variáveis `productName`, `productUrl` e o objeto `product` completo.
- **Confirmação de inscrição** (`df_preorder.double_opt_in`): acrescenta a variável `confirmUrl`.

Cada cliente é notificado no idioma da loja no momento da sua inscrição: a extensão reconstrói um contexto de idioma próprio do subscritor para resolver o nome traduzido do produto e o modelo certo. O URL do produto é resolvido através do URL SEO canónico do canal e do idioma em causa.

Os modelos mantêm-se inteiramente editáveis em **Definições → Emails → Modelos de email**. Pesquise «regresso ao stock» ou «back in stock» para os encontrar.

## Módulo de administração

O menu **Marketing → Lista de Espera e Pré-encomenda** lista todas as inscrições: endereço de email, produto, estado (pendente / confirmado / notificado), data de inscrição e data de notificação. A eliminação em massa está disponível, útil para limpar manualmente inscrições antigas.

## Store API (headless / móvel)

Para as lojas headless ou as aplicações móveis, um ponto de entrada Store API permite inscrever um cliente na lista de espera:

```
POST /store-api/df-waitlist/subscribe
Content-Type: application/json
sw-access-key: <a-sua-chave-de-acesso>

{
  "productId": "0189a1b2c3d4...",
  "email": "cliente@example.com"
}
```

Um pedido válido devolve uma resposta de sucesso; um identificador de produto ou um email inválido devolve um erro 400. Aplicam-se as mesmas regras de configuração (duplo opt-in, autorização de visitantes, e as restantes).

## Conformidade com o RGPD

- Os endereços de email são recolhidos apenas para a notificação pedida.
- O duplo opt-in opcional regista um consentimento explícito.
- O comportamento predefinido elimina o dado pessoal assim que o alerta é enviado.
- Pode ser inserida nos modelos de email uma ligação de cancelamento da subscrição num clique.
- A desinstalação com eliminação dos dados apaga a tabela, os modelos, os campos personalizados e a configuração.

## Compatibilidade 6.5 a 6.7 e resolução de problemas

**O formulário não aparece num produto esgotado.** Verifique que a opção «Ativar a lista de espera» está marcada para o canal de venda certo, que o produto está mesmo em modo closeout, e que o seu stock disponível está a zero. Limpe a cache depois de qualquer alteração de configuração.

**As inscrições são registadas mas nenhum email é enviado.** O worker Messenger e/ou o agendador de tarefas não estão a correr. Execute-os manualmente para testar (ver a secção Worker), e depois garanta que correm em contínuo em produção.

**Erro do serviço de email na ativação no Shopware 6.7.** A classe abstrata do serviço de email foi substituída por uma classe concreta na 6.7. A extensão trata automaticamente dessa diferença através de um compiler pass que cria o alias adequado; um simples `cache:clear` recompila o contentor se o erro persistir depois de uma atualização.

**O email sai no idioma errado.** O idioma usado é o do canal de venda no momento da inscrição. Verifique que o canal em causa tem mesmo o idioma esperado e que o modelo de email tem uma tradução para esse idioma.

**Parece haver emails enviados em duplicado.** Não deveria acontecer: o processamento é idempotente e marca (ou elimina) cada inscrição depois do envio. Se o observar, verifique que não está a executar vários workers em concorrência sem a configuração de transporte adequada.

**O que acontece na desinstalação?** Com a opção de eliminação dos dados, a tabela `df_stock_notification`, os dois modelos de email, o conjunto de campos `df_preorder`, a tarefa agendada e a configuração são eliminados. Sem essa opção, tudo é conservado para uma reinstalação posterior.