# Documentação Pesquisa Sem Resultados: Página de Recuperação e Alertas

> Apresentação O módulo Pesquisa Sem Resultados (dfzerosearch) entra em ação quando uma pesquisa na sua loja não encontra nada. Em vez de uma página vazia, o visitante vê uma página…

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

## Apresentação

O módulo **Pesquisa Sem Resultados** (`dfzerosearch`) entra em ação quando uma pesquisa na sua loja não encontra nada. Em vez de uma página vazia, o visitante vê uma **página de recuperação**: o destino que escolheu para essa pesquisa, os produtos cuja referência se parece com a escrita, a pesquisa corrigida, uma pesquisa mais ampla, os mais vendidos da categoria deduzida e um formulário «avise-me».

No back-office, cada pesquisa perdida é contabilizada. Associa-a a um produto, uma categoria, outra pesquisa ou um URL, com uma regra exata, «contém» ou curinga. O módulo mede depois o que essas recuperações rendem: taxa de recuperação, encomendas e receita sem IVA.

**Novidades da 1.3.0:** bloco **Similar references** (uma pesquisa por `M91650-0005` mostra `M91650-0001` e `M91650-0002`) e regras **curinga** (`M91650*` cobre toda uma família de referências com uma única regra).

A interface e os emails do módulo existem em inglês, francês, espanhol, alemão e italiano. Numa loja em português, o módulo apresenta a versão inglesa, por isso os nomes das definições abaixo aparecem nessa versão.

## Instalação e atualização

### Primeira instalação

1. Abra **Módulos > Gestor de módulos** e clique em **Carregar um módulo**.
2. Selecione o arquivo `dfzerosearch.zip`.
3. O módulo cria as suas tabelas, o seu menu de administração e a configuração predefinida. Fica ativo de imediato.
4. Copie o URL da tarefa agendada apresentado na página de configuração e agende-o de hora a hora (ver abaixo).

### Atualização a partir de uma versão anterior

Carregue o novo ZIP por cima do antigo, sem desinstalar. O PrestaShop executa os scripts de atualização: novas colunas, novas definições com o valor predefinido e limpeza da cache do módulo. As pesquisas perdidas, regras, subscritores e estatísticas são mantidos.

Não desinstale o módulo para o atualizar: a desinstalação apaga as suas tabelas e, com elas, todo o histórico.

## Configuração

A página **Configurar** começa com atalhos para os três ecrãs do módulo, seguidos de três painéis de definições e do painel da tarefa agendada.

### Rescue page

- **Enable module**: ativa ou suspende a deteção e a página de recuperação.
- **Typo correction ("Did you mean...")**: corrige erros de escrita palavra a palavra com base no índice de pesquisa e mostra os produtos correspondentes.
- **Similar references**: para uma referência que não existe no catálogo, mostra os produtos cuja referência começa da mesma forma. Hífenes, espaços e maiúsculas são ignorados, as referências de combinações são incluídas.
- **Partial match**: quando uma pesquisa longa falha por causa de uma palavra («botas couro tamanho 45»), mostra os resultados da pesquisa mais curta mais próxima.
- **Best sellers of the guessed category**: compara a pesquisa com os nomes das categorias, subcategorias incluídas.
- **Global best sellers fallback**: só aparecem se nenhum outro bloco encontrou nada. Sem vendas, são usadas as novidades.
- **"Notify me" form**: o visitante deixa o email para ser avisado quando a sua pesquisa encontrar um produto.
- **Use the theme product miniatures**: os produtos aparecem como nas páginas de categoria (adicionar ao carrinho, vista rápida, etiquetas). Desativado, o módulo usa os seus cartões compactos.
- **In-stock products only**: oculta os produtos esgotados em todos os blocos.
- **Custom message** (por idioma): texto apresentado no topo da página de recuperação, por exemplo um número de telefone ou uma ligação para encomendas especiais. `%query%` é substituído pelas palavras pesquisadas.
- **Popular searches**: etiquetas clicáveis com pesquisas que funcionam. Introduza a sua própria lista por idioma ou deixe vazio para usar as pesquisas frequentes com resultados.
- **Products per block**: de 1 a 24 (8 por predefinição).

### Tracking and data

- **Minimum query length**: abaixo deste valor, a pesquisa não é registada nem recuperada (2 por predefinição).
- **Treat approximate-only results as lost**: a pesquisa aproximada nativa do PrestaShop devolve muitas vezes produtos sem relação para uma palavra desconhecida. Quando uma pesquisa só encontra esse tipo de resultado, é contabilizada como perdida e o bloco de recuperação aparece por cima.
- **Ignore bots and crawlers**: as pesquisas de motores de busca, ferramentas SEO e scripts não são registadas.
- **Attribution window (days)** (7 por predefinição): uma encomenda feita neste prazo após uma recuperação é atribuída à pesquisa e ao bloco que trouxeram o visitante de volta (último contacto).
- **Cache rescue results**: guarda o trabalho de pesquisa durante 15 minutos por pesquisa. Preços e stock continuam em tempo real. A cache é limpa assim que altera uma definição ou uma regra.
- **Retention (days)** (180 por predefinição): as pesquisas perdidas não vistas durante este período e as subscrições já avisadas são apagadas pela tarefa agendada. 0 guarda tudo. Um botão permite apagar de imediato.

### Automation

- **Automatic notify-me emails**: os subscritores recebem o aviso assim que a sua pesquisa recebe uma regra ativa ou a pesquisa volta a encontrar produtos.
- **Weekly digest**: de 7 em 7 dias, pesquisas perdidas, taxa de recuperação e principais pesquisas perdidas, enviadas por email.
- **Digest recipient**: vazio, é usado o email da loja.

## Tarefa agendada

O painel **Scheduled task (cron)** apresenta um URL protegido por token. Chame-o de hora a hora a partir do cPanel, Plesk ou de qualquer serviço de cron, por exemplo:

```
0 * * * * curl -s "https://www.a-sua-loja.pt/module/dfzerosearch/cron?token=..." > /dev/null
```

A tarefa envia os avisos automáticos, aplica o período de conservação e envia o relatório semanal. O painel indica a data da última execução, o botão **Run now** lança a tarefa manualmente e **Generate a new token** substitui o URL se este tiver sido divulgado. Em multiloja, agende uma tarefa por loja com o URL apresentado no contexto de cada loja.

Se a tarefa não correr há 48 horas, aparece um aviso no painel: os emails automáticos e o relatório semanal ficam em espera até voltar a correr.

## A página de recuperação

Quando a grelha de resultados está vazia, um script carrega a página de recuperação por AJAX. As pesquisas que encontram produtos não ficam mais lentas. Os blocos aparecem por esta ordem, sem produtos repetidos entre blocos:

1. **A sua regra**: se uma regra ativa corresponder à pesquisa, o seu destino é destacado. Em modo de redirecionamento, o visitante chega diretamente ao destino. Um sinónimo mostra também os seus produtos.
2. **Referências semelhantes**: produtos da mesma família de referência.
3. **«Queria dizer...»**: a pesquisa corrigida e os seus produtos, com ligação para a pesquisa corrigida. Este bloco só aparece se os blocos anteriores não mostraram nada.
4. **Correspondência parcial**: resultados da pesquisa encurtada, só se ainda nada tiver sido encontrado.
5. **Mais vendidos da categoria deduzida**.
6. **Mais vendidos da loja**: apenas em último recurso.

A mensagem personalizada aparece acima dos blocos; as pesquisas populares e o formulário «avise-me», abaixo.

## Referências semelhantes

Muitos clientes pesquisam um produto pela referência exata. Quando essa referência não existe no catálogo, o módulo propõe os produtos da mesma família.

- O módulo identifica na pesquisa a palavra que parece uma referência: pelo menos 5 caracteres, dos quais pelo menos 2 algarismos.
- Compara-a com as referências de produtos e combinações, ignorando hífenes, espaços, pontos e maiúsculas. `M91650-0005`, `m91650 0005` e `M916500005` são tratados da mesma forma.
- Só são mantidos os produtos com um início de referência comum suficientemente longo (pelo menos 5 caracteres e 60% da referência pesquisada). Os mais próximos aparecem primeiro.
- Exemplo: uma pesquisa por `M91650-0005` mostra `M91650-0001` e `M91650-0002`, mas não `M91651-0003`.

A correção de erros nunca altera uma palavra com pelo menos 2 algarismos: uma referência não é «corrigida» para outra.

## Regras: associações e sinónimos

O ecrã **Mappings & synonyms** lista as suas regras. Para criar uma, clique em **Add a mapping** ou use a ação **Map** de uma pesquisa perdida, que pré-preenche o formulário.

### Tipos de correspondência

- **Exata** (exact): a pesquisa tem de ser idêntica à regra. Maiúsculas, acentos e espaços a mais são ignorados.
- **Contém** (contains): a regra tem de aparecer como palavra ou sequência de palavras na pesquisa. Hífenes, barras, pontos e outros separadores contam como espaços: a regra `m91651` aplica-se a `M91651-0003`.
- **Curinga** (wildcard): `*` substitui qualquer sequência de caracteres e `?` um único carácter. `M91650*` cobre `M91650-0001`, `M91650-0007` ou `m916500009`, mas não `M91659-0001`. Qualquer regra que contenha `*` ou `?` é guardada automaticamente como curinga.

Uma regra curinga precisa de pelo menos 3 caracteres além dos curingas, e `**` é recusado. Escreva `M91650*` em vez de `M91650-*` se os seus clientes também escreverem a referência sem hífen.

### Prioridades

Quando várias regras correspondem a uma pesquisa, ganha a mais precisa: uma regra exata passa à frente de uma curinga, que passa à frente de uma «contém». Com o mesmo tipo, uma regra de um idioma específico passa à frente de uma regra «todos os idiomas», e depois ganha a regra mais longa.

### Destinos e modos

- **Product**: pesquisa por nome, referência ou ID no formulário.
- **Category**.
- **Synonym (other search)**: outras palavras que dão resultados («sweatshirt» para «camisola»). Os produtos dessa pesquisa aparecem na página de recuperação.
- **Custom URL**: URL absoluto ou caminho que começa por uma barra.

Cada regra funciona em modo **Suggest** (destino destacado na página de recuperação) ou **Redirect** (o visitante chega diretamente ao destino). Uma regra pode aplicar-se a um idioma específico ou a todos.

## Importação e exportação CSV

O painel **Import / export (CSV)** do ecrã de regras importa até 5000 linhas e exporta todas as regras. Separador `;` ou `,`, cabeçalho opcional. Colunas:

```
query ; match ; language ; type ; target ; mode ; active
M91650* ; wildcard ; all ; category ; 12 ; redirect ; 1
camisola ; exact ; pt ; search ; sweatshirt ; suggest ; 1
M91651 ; contains ; all ; product ; M91651-0003 ; suggest ; 1
```

- **match**: `exact`, `contains` ou `wildcard` (exact por predefinição; curinga detetado automaticamente se a regra contiver `*` ou `?`).
- **language**: código ISO, ou vazio, `*` ou `all` para todos os idiomas.
- **type**: `product`, `category`, `search` ou `url`.
- **target**: ID ou referência de produto, ID de categoria, palavras a pesquisar ou URL.
- **mode**: `suggest` ou `redirect` (suggest por predefinição). **active**: 1 ou 0 (1 por predefinição).

Uma regra existente com a mesma pesquisa e o mesmo idioma é atualizada. O relatório de importação indica as linhas criadas, atualizadas e rejeitadas com o respetivo número.

## Alertas «avise-me»

O formulário da página de recuperação tem uma caixa de consentimento desmarcada por predefinição e um campo armadilha contra bots. Para um cliente com sessão iniciada, o email já vem preenchido. Os pedidos são listados no ecrã **Notify-me requests** com o respetivo estado.

Com a tarefa agendada e a opção **Automatic notify-me emails**, o subscritor recebe o email `dfzerosearch_alert` assim que a sua pesquisa recebe uma regra ativa ou a pesquisa volta a encontrar produtos. Também pode enviá-lo manualmente com a ação **Notify** de uma regra. Cada email inclui uma ligação para cancelar a subscrição.

## Painel e receita recuperada

O ecrã **Lost queries** mostra os números dos últimos 30 dias: pesquisas perdidas, taxa de recuperação, encomendas após recuperação, receita recuperada sem IVA, novas subscrições e emails pendentes. Um gráfico compara dia a dia as pesquisas perdidas e recuperadas, outro mostra os cliques por bloco de recuperação (regra, referências semelhantes, correção, correspondência parcial, categoria, mais vendidos, pesquisas populares).

A lista de pesquisas perdidas está ordenada por volume. Cada linha oferece **Map**, **Ignore / restore** e, quando foi encontrada uma correção, **Create a synonym from this correction**. A tabela **Latest orders after a rescue** indica a pesquisa e o bloco creditados.

A atribuição é feita ao último contacto: a encomenda é creditada à última recuperação do mesmo visitante dentro da janela de atribuição configurada.

## Relatório semanal

De 7 em 7 dias, a tarefa agendada envia o email `dfzerosearch_digest`: pesquisas perdidas, visitantes recuperados, taxa de recuperação, encomendas e receita sem IVA após recuperação, novos pedidos «avise-me» e pesquisas perdidas mais frequentes. Se nada aconteceu durante a semana, nenhum email é enviado.

## RGPD

- **Consentimento explícito**: caixa desmarcada por predefinição e texto de consentimento claro.
- **Módulo RGPD oficial**: o módulo está registado no `psgdpr`. A exportação e a eliminação dos dados de um cliente incluem os seus pedidos «avise-me».
- **Cancelamento**: uma ligação em cada email.
- **Conservação**: eliminação automática de pesquisas antigas e subscrições já avisadas.
- **Alojamento próprio**: nenhum dado é enviado para serviços de terceiros.

## Compatibilidade e informação técnica

- PrestaShop 8.0 a 9.x, multiloja.
- Interface e emails em inglês, francês, espanhol, alemão e italiano.
- Hooks: `actionSearch`, `actionFrontControllerSetMedia`, `actionValidateOrder`, `registerGDPRConsent`, `actionDeleteGDPRCustomer`, `actionExportGDPRData`.
- Tabelas: `dfzerosearch_query`, `dfzerosearch_mapping`, `dfzerosearch_alert`, `dfzerosearch_stat`, `dfzerosearch_session`, `dfzerosearch_conversion`.
- Menu `AdminDfZeroSearch` em Módulos, com três ecrãs: pesquisas perdidas, associações e sinónimos, pedidos «avise-me».
- Controladores front: `rescue` (página de recuperação, JSON), `cron` (tarefa agendada, token) e `unsubscribe`.
- Sem dependências: sem Composer, JavaScript sem jQuery, sem serviço externo.

## Resolução de problemas

- **A página de recuperação não aparece**: verifique se o módulo está ativo e se a pesquisa devolve mesmo zero resultados, e limpe a cache do PrestaShop e do navegador. Com um tema muito personalizado, contacte-nos indicando o nome do tema.
- **Uma pesquisa mostra produtos sem relação e não é contabilizada como perdida**: ative **Treat approximate-only results as lost**.
- **Nenhuma referência semelhante**: a palavra pesquisada precisa de pelo menos 5 caracteres com 2 algarismos, e têm de existir produtos ativos, visíveis na pesquisa, com o mesmo início de referência.
- **Uma regra curinga não se aplica**: verifique se está ativa, no idioma certo, e se nenhuma regra exata tem prioridade. Teste-a sem separador (`M91650*`) se os clientes escreverem a referência de várias formas.
- **Nenhuma correção proposta**: a correção só sugere palavras presentes no índice; reconstrua o índice de pesquisa do PrestaShop se o catálogo mudou muito.
- **Os emails automáticos ou o relatório não são enviados**: verifique a data da última execução da tarefa agendada e a configuração de email do PrestaShop. O botão Notify mostra um erro explícito se o envio falhar.
- **O painel continua vazio**: verifique o comprimento mínimo da pesquisa e teste a partir de um navegador normal, já que os bots são ignorados.