# Agrupar Produtos como Variantes no PrestaShop: Documentação do Módulo (dfproductlinker)

> O módulo DF ProductLinker (dfproductlinker) liga fichas de produto distintas para as apresentar como um único artigo com seletor de cor, tamanho ou qualquer outro atributo. Cada variante continua a…

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

O módulo **DF ProductLinker** (dfproductlinker) liga fichas de produto distintas para as apresentar como um único artigo com seletor de cor, tamanho ou qualquer outro atributo. Cada variante continua a ser um produto completo com o seu próprio URL. É o movimento inverso do [DF ProductSplitter](https://www.datafirefly.com/pt/produto/separar-variantes-em-produtos-prestashop/), que divide um produto com combinações em produtos separados.

## Instalação

1. Descarregue o ZIP a partir da sua conta de cliente DataFirefly.
2. No back-office, vá a _Módulos > Gestor de módulos > Carregar um módulo_ e envie o ZIP.
3. Na instalação, o módulo cria as suas tabelas e o separador _Catálogo > Variantes ligadas_.
4. Abra a configuração do módulo para verificar a posição do seletor.

O módulo funciona no PrestaShop 8.0 a 9.x com o mesmo ZIP, em multiloja e multilíngue. Os textos são fornecidos em francês, inglês, espanhol, alemão, italiano, neerlandês, polaco e português.

Numa atualização, o módulo limpa a cache do Smarty. Se a loja estiver definida para _Nunca recompilar os templates_ e a apresentação não mudar, limpe a cache em _Parâmetros avançados > Desempenho_.

## Princípio: grupos e eixos

Um **grupo** reúne vários produtos. Um **eixo** é um grupo de atributos nativo do PrestaShop, por exemplo Cor ou Tamanho: os valores, as cores hexadecimais, as texturas e as traduções introduzidas em _Catálogo > Atributos e características_ são reutilizados tal como estão. Cada produto do grupo recebe um valor em cada eixo.

Um produto só pode pertencer a um grupo. Os produtos não são alterados: o grupo fica guardado nas tabelas do módulo.

## Criar um grupo

Vá a _Catálogo > Variantes ligadas_ e depois _Adicionar um grupo_.

1. Introduza o **nome do grupo**. Serve internamente e como nome de recurso nos dados estruturados.
2. Em **Eixos**, clique em _Adicionar um eixo_. O módulo propõe primeiro um grupo de atributos do tipo cor. Para cada eixo, escolha a **apresentação** (automática, amostra de cor, miniatura da foto do produto, botão de texto, lista pendente) e a **propriedade dos dados estruturados** (cor, tamanho, material, padrão ou não declarada).
3. Em **Produtos do grupo**, pesquise os produtos por nome, referência ou ID. As setas do teclado e a tecla Enter selecionam um resultado. Os produtos que já estão noutro grupo aparecem a cinzento.
4. Para cada produto, verifique o valor de cada eixo. É pré-preenchido quando aparece no nome do produto. Um valor em falta fica realçado a laranja e a linha de estado sob a tabela indica quantos produtos estão afetados, ou se dois produtos têm os mesmos valores.
5. Guarde. O módulo avisa se sair da página com alterações por guardar.

A ordem das linhas do grupo é a ordem das amostras na loja. O botão _Ordenar pela ordem dos atributos_ coloca as linhas na ordem definida no catálogo, útil para os tamanhos S, M, L, XL.

## O que o cliente vê

Em cada ficha do grupo, o seletor mostra o nome do eixo e o valor atual, por exemplo _Cor: Vermelho_, e depois os valores disponíveis. Ao passar o rato, o rótulo mostra o valor apontado. O valor atual aparece destacado; os outros são ligações para a ficha correspondente.

- Com vários eixos, um clique numa cor abre o produto que mantém o tamanho atual. Se essa combinação não existir, o módulo abre a variante mais próxima, dando prioridade a um produto em stock, e a amostra é desenhada com contorno tracejado.
- Uma variante sem stock aparece esbatida e riscada, ou oculta conforme a definição.
- Um valor de cor sem código hexadecimal nem textura é apresentado como texto numa amostra alongada.
- O seletor aparece também na vista rápida das páginas de categoria, por cima do botão de adicionar ao carrinho.

## Definições do módulo

- **Posição do seletor**: antes do bloco nativo de combinações (recomendado), depois desse bloco, no hook `displayProductAdditionalInfo` ou apenas no hook de tema `displayDfProductLinker`.
- **Seletor CSS do bloco nativo de combinações**: por predefinição `.product-variants, .product__variants`. Se nada corresponder no seu tema, o seletor fica no hook.
- **Rótulo do eixo**, **preço de cada variante** (modos imagem e botão), **formato de imagem** das miniaturas.
- **Variantes sem stock**: esbatidas ou ocultas.
- **Cor de destaque**, **forma** (redonda ou quadrada com cantos arredondados) e **tamanho** das amostras. O tamanho médio oferece uma zona tátil de 44 px, recomendada em dispositivos móveis.
- **Amostras nas listagens de produtos**, número máximo de amostras e **mudança de imagem ao passar o rato**.
- **Um só produto por grupo**, visibilidade dos restantes produtos e produto apresentado: ver a secção seguinte.
- **URL canónico das variantes** e **dados estruturados ProductGroup**: ver a secção SEO.

Para uma posição à medida, escolha a posição _hook de tema_ e acrescente esta linha ao template de produto do seu tema: `{hook h='displayDfProductLinker' product=$product}`.

## Um só produto por grupo nas categorias

Esta opção mostra uma só miniatura por grupo nas listagens de categoria. Os restantes produtos do grupo passam para a visibilidade _Apenas pesquisa_ (ou _Em lado nenhum_, conforme a definição): as suas fichas continuam online com o seu URL e as amostras da miniatura levam até elas.

- **Produto apresentado**: o primeiro do grupo ou o primeiro em stock. No segundo caso, é recalculado a cada movimento de stock.
- A visibilidade original de cada produto é guardada. É reposta quando desativa a opção, desativa o grupo, retira um produto do seu grupo ou desinstala o módulo.
- Se alterar à mão a visibilidade de um produto oculto, o seu valor passa a ser o novo valor original.
- O botão _Ressincronizar a visibilidade_ da configuração volta a aplicar a regra a todos os grupos. Use-o se um funcionário sem permissões sobre o módulo tiver alterado produtos, porque nesse caso o PrestaShop não executa os hooks do módulo.

Antes de ativar a opção, confirme que o seu gerador de sitemap inclui os produtos com visibilidade _Apenas pesquisa_; caso contrário, as variantes ocultas sairiam do sitemap.

## SEO: dados estruturados e URL canónico

O módulo acrescenta em cada ficha do grupo um bloco JSON-LD `ProductGroup` com `hasVariant` e `variesBy`. Cada variante surge com o nome, o URL, a referência, o EAN13 se for válido, a imagem, o valor em cada eixo, o preço apresentado ao cliente e a disponibilidade. O nome do grupo vem do nome do produto sem os seus valores, no idioma do visitante. Desative a opção se outro módulo já gerar este bloco.

Por predefinição, cada variante mantém um URL canónico para si própria: cada cor é indexada separadamente. Se as fichas de cor forem quase idênticas, a opção _Canónico para o produto principal do grupo_ aponta o canónico de todas as variantes para o produto principal, ou seja, o produto apresentado nas listagens se a opção de um só produto por grupo estiver ativa e, caso contrário, o primeiro produto ativo do grupo.

## Assistente de agrupamento automático

Na lista de grupos, clique em _Assistente de agrupamento automático_. Identifica os produtos que são o mesmo artigo em várias cores ou tamanhos.

1. Escolha uma categoria ou todo o catálogo.
2. Assinale os grupos de atributos a detetar, por exemplo Cor e Tamanho. Os valores devem existir como valores de atributo e aparecer no nome do produto.
3. Escolha a regra: nomes idênticos depois de retirados os valores, ou referências com a mesma raiz (TSH01-RED e TSH01-BLUE).
4. Clique em _Pré-visualizar_, desmarque os grupos a ignorar e depois _Criar os grupos selecionados_.

Os produtos que já estão num grupo são ignorados e a análise abrange 5.000 produtos por execução.

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

O botão _Importar / exportar CSV_ abre a página dedicada. A exportação gera uma linha por produto, no mesmo formato da importação. Colunas:

```
group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Cor|Tamanho;;TSH01-NAVY-M;;Cor:Azul-marinho|Tamanho:M
```

- Um grupo é identificado pelo `group_id` ou, caso contrário, pelo nome exato. Cada grupo presente no ficheiro é substituído pelas suas linhas; os grupos ausentes não são alterados.
- Um produto é encontrado pelo `product_id` ou, caso contrário, pela `product_reference`, que deve ser única no catálogo. `product_name` é informativo.
- `values` contém pares Eixo:Valor separados por `|`, com os nomes dos grupos de atributos e dos valores em qualquer idioma da loja.
- O separador `;` ou `,` é detetado automaticamente. Ficheiro UTF-8, máximo 5 MB.

A importação faz-se em dois passos: _Analisar o ficheiro_ mostra os grupos criados ou substituídos, os valores de atributo que serão criados e cada linha rejeitada com o motivo; _Executar a importação_ realiza-a. Duas opções: _Mover os produtos que já pertencem a outro grupo_ e _Criar os valores de atributo em falta_ (a cor fica vazia, a completar no catálogo).

## Ficha de produto do back-office

No separador Módulos da ficha de produto, o painel DF ProductLinker indica o grupo do produto e o valor de cada produto do grupo, com uma ligação para editar o grupo. Se o produto não estiver em nenhum grupo, uma ligação cria um grupo a partir deste produto.

## Perguntas frequentes

### O seletor não aparece numa ficha

Confirme que o grupo está ativo, que a ficha faz parte do grupo, que pelo menos dois produtos do grupo estão ativos e que pelo menos um eixo tem dois valores diferentes. Se escolheu a posição hook de tema, o hook `displayDfProductLinker` tem de estar no template de produto.

### O seletor aparece por baixo do botão do carrinho

O seletor CSS do bloco nativo de combinações não corresponde a nenhum elemento do seu tema. Indique na configuração a classe do bloco de combinações do seu tema.

### As amostras não aparecem nas listagens

A opção tem de estar ativa e o primeiro eixo do grupo tem de ser apresentado como amostra de cor ou miniatura de foto. O tema tem de chamar o hook nativo `displayProductListReviews` na miniatura do produto, como faz o tema Classic.

### Posso combinar o módulo com combinações nativas?

Sim. Um caso comum: um produto por cor, cada um com combinações de tamanho. O seletor do módulo trata das cores e o bloco nativo trata dos tamanhos.
