Vinhos e destilados no PrestaShop: documentação DataFirefly Wine & Spirits

Instalação

Instale o módulo em Módulos > Gestor de módulos > Carregar um módulo com o ficheiro ZIP. O módulo cria as suas tabelas, regista os seus hooks e acrescenta o menu Catálogo > Vinhos e destilados.

Na instalação cria também oito características nativas: Colheita, Casta, Denominação de origem, Teor alcoólico, Cor, Região, País de origem e Certificação. Configura a França (idade legal de 18 anos, caixa de idade no pagamento, aviso de saúde francês obrigatório) e as taxas francesas de impostos especiais de 2026.

Para atualizar a partir de uma versão anterior, instale o novo ZIP: os scripts de atualização acrescentam as colunas, tabelas e características em falta sem tocar nos seus dados.

Painel

Primeiro separador do menu. Mostra o número de produtos geridos, as unidades vendidas, o álcool puro e os impostos especiais do mês em curso, uma lista de verificação da configuração, a integridade dos dados (teor alcoólico, cor, colheita, castas, denominação) e os últimos 30 produtos a completar com uma ligação para a sua página. A cor, a colheita e as castas só são verificadas para vinhos.

Definições

Modo de cálculo dos impostos especiais

• Incluídos no preço (predefinido): os seus preços já contêm os impostos. O montante é mostrado na página do produto («Dos quais impostos especiais») e no carrinho, e depois guardado no registo.
• Adicionados no checkout: é acrescentada ao carrinho uma linha «Impostos especiais de consumo» com os impostos do país de entrega. É suportada por um produto técnico oculto do catálogo, criado ao ativar este modo. Não elimine este produto.
• Desativado: nenhum montante é calculado, o registo guarda apenas volumes e álcool puro.

Regra de imposto da linha de impostos especiais: na UE, os impostos especiais fazem parte da base do IVA. Escolha a sua taxa normal.

Apresentação

Cada elemento ativa-se separadamente: resumo do vinho na página do produto, montante dos impostos na página, aviso legal na página, aviso e total dos impostos no carrinho, aviso no rodapé, impostos e aviso na fatura PDF, separador Ficha de prova, distintivos nas listas de produtos.

Pop-up de verificação de idade

• Verificação: botões Sim / Não, ou data de nascimento com cálculo da idade.
• Memorizar durante: número de dias em que o visitante não volta a ser questionado. 0 pergunta novamente em cada sessão do navegador.
• URL de saída: página aberta quando o visitante responde não ou não tem a idade exigida.
• Cor dos botões, título e texto por idioma. No texto, {age} é substituído pela idade legal do país do visitante.

O pop-up não é mostrado aos robôs dos motores de busca, nas páginas CMS nem aos clientes com sessão iniciada cuja data de nascimento comprova a idade. O conteúdo da página permanece no HTML.

Caixa mista

Defina o número de garrafas necessário (6 por predefinição), o desconto em percentagem e os produtos elegíveis: todos os produtos alcoólicos geridos pelo módulo, ou apenas os marcados no seu separador. Assim que o carrinho atinge o número necessário, cada garrafa elegível recebe o desconto. Um produto cujo desconto por caixa próprio já se aplica mantém o seu desconto.

Países sem regra específica

Valores usados para os países que não configurou: entrega de álcool permitida ou não, caixa de idade no pagamento, idade legal.

Valores predefinidos dos produtos

Volume (75 cl) e tamanho da caixa (6) propostos para um produto novo.

Características filtráveis

A tabela indica o estado das oito características. Recriar as características em falta recria uma característica eliminada. Para que os clientes filtrem por elas, adicione-as ao seu modelo de filtros no ps_facetedsearch (botão Abrir a navegação por facetas).

Preencher um produto

Abra a página do produto, separador Módulos, bloco Wine & Spirits. Marque Este produto é uma bebida alcoólica. O bloco é guardado com o seu próprio botão, independentemente do formulário do produto.

Dados de vinhos e destilados

• Categoria: categoria fiscal usada nos impostos (vinho tranquilo, espumante, vinho licoroso, outro produto intermédio, bebidas espirituosas, cerveja, sidra).
• Colheita ou caixa Sem colheita.
• Teor alcoólico em % vol e volume por unidade em cl.
• Castas separadas por vírgulas: cada uma torna-se um valor de filtro. Denominação de origem com sugestões dos valores existentes para evitar duplicados.

Perfil e prova

Cor, região, país de origem, temperatura de serviço (mín. e máx.), potencial de guarda, selos (biológico, biodinâmico, vinho natural, vegano, HVE), prémios e pontuações (um por linha). As notas de prova e a harmonização introduzem-se por idioma com os separadores de idioma.

Venda à caixa

• Apenas à unidade: comportamento padrão.
• À unidade ou à caixa: a página do produto propõe a escolha entre garrafa e caixa, com o preço da caixa e a poupança.
• Apenas à caixa: a quantidade mínima passa a ser o tamanho da caixa e as quantidades do carrinho são arredondadas à caixa completa seguinte (anterior se faltar stock).

O desconto por caixa, em % ou montante por caixa, é criado como desconto de quantidade nativo a partir de uma caixa completa. A caixa Elegível para a caixa mista aparece quando a caixa mista está ativada.

Volume por combinação

Para um produto com combinações (meia garrafa, garrafa, magnum), indique o volume de cada combinação. Vazia, a combinação usa o volume do produto. Os impostos, o álcool puro do registo e a ficha de prova seguem a combinação.

Países e avisos legais

O separador lista os países ativos, com pesquisa. Para cada país, Editar permite definir:

• O álcool pode ser entregue neste país: desmarcada, o cliente com álcool no carrinho fica parado no passo de entrega com uma mensagem, e aparece um aviso na página do produto.
• Caixa de idade legal no checkout e idade legal: a caixa «Confirmo que tenho pelo menos N anos» é acrescentada às condições a aceitar no passo de pagamento.
• Aviso legal por idioma. Um idioma vazio usa o idioma predefinido da loja.

O país de entrega é lido na morada de entrega do carrinho, senão na primeira morada do cliente com sessão iniciada, depois no país do visitante e depois no país predefinido da loja.

Taxas de impostos especiais

Uma taxa define-se por país, categoria, intervalo de teor alcoólico (limites incluídos, 0 como máximo para sem limite), base de cálculo e montante na moeda predefinida, sem impostos. Várias taxas podem aplicar-se ao mesmo produto e somam-se.

• por hectolitro de produto: vinhos, espumantes, produtos intermédios, sidras.
• por hectolitro de álcool puro: bebidas espirituosas. Exemplo: 70 cl a 40% = 0,0028 hl de álcool puro.
• por hectolitro e por grau: cervejas.
• por litro de produto e por unidade vendida para outros casos.

Taxas francesas de 2026 incluídas: vinhos tranquilos 4,19 €/hl, espumantes 10,38 €/hl, sidras 1,46 €/hl, VDN e VDL 52,39 €/hl, outros produtos intermédios 209,53 €/hl mais 52,39 €/hl de contribuição acima de 18% vol, bebidas espirituosas 1 932,42 €/hl de álcool puro mais 620,47 € de contribuição para a segurança social acima de 18% vol, cervejas 4,12 €/hl/grau até 2,8% vol e depois 8,24 €. Uma garrafa de 70 cl a 40% suporta assim 7,15 €.

Registo de impostos especiais

Cada encomenda validada regista, para cada produto alcoólico, o país de entrega, a categoria, a combinação, as unidades, o volume, o teor alcoólico, o álcool puro e o montante dos impostos à taxa do dia. O separador Registo filtra por período, país e encomendas validadas, com duas exportações CSV: o resumo por país e categoria, e as linhas de encomenda. A página de cada encomenda mostra também um painel Impostos especiais.

Importação e exportação CSV

Exportar os produtos alcoólicos ou Exportar todo o catálogo gera um ficheiro no formato da importação. Complete-o numa folha de cálculo e volte a importá-lo.

• Separador ; ou , detetado automaticamente. Produto encontrado por id_product, senão por reference.
• Uma coluna ausente ou uma célula vazia mantém o valor atual. - limpa a colheita, as castas, a denominação e os campos de texto.
• vintage: ano ou NV. product_type: still_wine, sparkling_wine, vdn_vdl, intermediate, spirits, beer, cider. sale_mode: unit, both, case_only. color: red, white, rose, orange, amber, clear. labels: organic, biodynamic, natural, vegan, hve, separados por vírgulas. origin_country: código ISO (PT, FR…). awards: um prémio por valor, separados por |.
• Colunas por idioma: tasting_notes_pt, food_pairing_pt, tasting_notes_en…

Deixe marcada a opção Apenas simulação numa primeira passagem: o relatório indica as linhas lidas, os produtos que seriam atualizados e os erros com o número da linha, sem guardar nada.

O que o cliente vê

• Página do produto: resumo do vinho, escolha garrafa ou caixa, oferta de caixa mista, montante dos impostos, idade legal e aviso legal, alerta se o país de entrega estiver bloqueado.
• Separador Ficha de prova: cartões das características, selos, notas de prova, harmonização e prémios.
• Listas de produtos: distintivos de cor, colheita, selos, prémios e caixa mista.
• Carrinho: «2 x caixa de 6» sob as linhas, progresso da caixa mista, total dos impostos e aviso legal.
• Pagamento: caixa de idade legal, linha de impostos no modo adicionado.
• Fatura PDF: montante dos impostos, álcool puro e aviso legal.

Resolução de problemas

Os filtros não aparecem

Adicione as características ao modelo de filtros do ps_facetedsearch e associe o modelo às categorias em causa. Os valores só aparecem depois de pelo menos um produto ter sido guardado com os seus dados.

O separador Ficha de prova ou os distintivos não aparecem

Verifique as opções de apresentação e se o produto está marcado como bebida alcoólica. Os distintivos usam o hook displayProductListReviews e o separador displayProductExtraContent: um tema que não os chame não os mostrará.

A linha de impostos não aparece no carrinho

Verifique o modo Adicionados no checkout, se o país de entrega tem taxas para a categoria do produto e se existe o produto técnico da linha de impostos (o seu ID aparece nas definições).

O pop-up de idade volta a aparecer em cada página

O navegador bloqueia o cookie dfws_age_ok. Verifique se nenhum gestor de cookies o elimina: é um cookie funcional.

Compatibilidade

• PrestaShop 8.0 a 9.x, o mesmo ZIP cobre as duas versões.
• Filtros através de características nativas, compatíveis com ps_facetedsearch.
• Arquitetura ModuleAdminController, sem dependências Composer, PHP 7.2 ou superior.
• Interface em francês, inglês, espanhol, alemão, italiano, neerlandês, polaco e português.