# Módulo de passatempos e sorteios para PrestaShop 8 e 9: documentação > Apresentação O módulo dfcontest adiciona passatempos e sorteios à sua loja PrestaShop 8 ou 9. Os clientes participam automaticamente ao fazer uma encomenda, ou gratuitamente através de um formulário. O… - Página: - Idioma: pt - Atualizado em: 2026-09-24 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfcontest/index.md), [en](https://www.datafirefly.com/en/documentation/dfcontest/index.md), [es](https://www.datafirefly.com/es/documentation/dfcontest/index.md), [de](https://www.datafirefly.com/de/documentation/dfcontest/index.md), [it](https://www.datafirefly.com/it/documentation/dfcontest/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfcontest/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfcontest/index.md) - Índice: ## Apresentação O módulo **dfcontest** adiciona passatempos e sorteios à sua loja PrestaShop 8 ou 9. Os clientes participam automaticamente ao fazer uma encomenda, ou gratuitamente através de um formulário. O sorteio é verificável: qualquer visitante pode repetir o cálculo e obter os mesmos vencedores. O módulo gera o regulamento, envia os emails aos vencedores e recolhe a morada de entrega. ## Instalação 1. No back office, abra **Módulos > Gestor de módulos** e clique em **Carregar um módulo**. 2. Carregue o ficheiro `dfcontest-x.y.z.zip` e clique em **Instalar**. 3. Aparece o menu **Clientes > Passatempos**. As definições gerais estão na página de configuração do módulo. Para atualizar, basta carregar a nova versão: os scripts de atualização adicionam as colunas e as definições em falta sem mexer nos seus passatempos nem nas participações. ## Configuração do módulo ### Organizador Indique a denominação social, a sede, o número de registo da empresa (NIPC, SIRET, CIF, KvK…) e o email de contacto para os participantes. Estes dados são usados no regulamento gerado e nos emails. ### Apresentação - **Nome dos vencedores nas páginas públicas**: só iniciais (J. S.) ou nome próprio e inicial (João S.). - **Mostrar o passatempo nas páginas dos produtos elegíveis** e **mostrar as participações obtidas no carrinho**, com o valor que falta para a participação seguinte. - **Cor de destaque**: cor da contagem decrescente, das caixas e dos contornos. Deixe vazio para o verde predefinido; os botões mantêm as cores do seu tema. - **Comprovativo de participação por email**: código de participação e ligação de partilha, enviados assim que uma participação pelo formulário é válida. - **Destacar o passatempo a decorrer na página inicial** (hook `displayHome`). ### Proteção contra fraude A opção **Recusar endereços de email descartáveis** bloqueia os principais serviços de email temporário (Yopmail, Mailinator, 10 Minute Mail, Guerrilla Mail e outros). O campo **Outros domínios bloqueados** aceita um domínio por linha; os subdomínios também são bloqueados. ### Tarefas automáticas (cron) A página de configuração mostra um URL cron assinado. Só é necessário para o piloto automático (ver abaixo). Chame-o a cada 5 a 15 minutos, por exemplo: ``` */10 * * * * curl -s "https://a-sua-loja.pt/module/dfcontest/cron?token=O_SEU_TOKEN" > /dev/null ``` A data da última execução aparece por baixo do URL. ## Criar um passatempo Abra **Clientes > Passatempos** e depois **Novo passatempo**. O formulário está dividido em separadores. ### Geral - **Nome**, **URL amigável**, **descrição** e **prémio** (descreva cada prémio e o seu valor comercial: este texto é incluído no regulamento). - **Imagem**: JPG, PNG ou WebP, 4 MB no máximo, largura recomendada de 1600 px. - **Início**, **fim** e **data de sorteio anunciada**. - **Destacar na página inicial**: se houver vários passatempos a decorrer, é mostrado o que termina primeiro. ### Como participar Ative a participação com compra, pelo formulário ou ambas. O **máximo de participações por participante** conta em conjunto as compras, o formulário e os bónus de convite, por endereço de email. ### Participações por compra - **1 participação por encomenda** ou **1 participação por escalão de valor** (com IVA, na moeda predefinida). - **Valor mínimo da encomenda** e **máximo de participações por encomenda**. - **ID dos produtos elegíveis** e **categorias elegíveis**: se estiverem definidos, só conta o valor desses produtos, com os descontos repartidos proporcionalmente. Deixe vazio para todo o catálogo. A participação é criada quando a encomenda passa a um estado pago durante o período do passatempo. É retirada se a encomenda for cancelada, reembolsada ou tiver um erro de pagamento, enquanto as participações não estiverem seladas. Uma encomenda dividida em vários envios conta como uma só encomenda. ### Participações por formulário - **Conta de cliente obrigatória**: reserva o formulário aos clientes com sessão iniciada. - **Confirmação por email** (recomendado): os visitantes recebem uma ligação e a participação só conta depois de confirmada. - **Número de telefone**: oculto, opcional ou obrigatório. - **Pergunta**: pergunta livre cuja resposta é guardada e exportada. - **Caixa de subscrição da newsletter**: desmarcada por predefinição. - **Participações bónus por amigo convidado** e **máximo de participações bónus por participante**: ativa os convites (0 desativa-os). ### Sorteio - **Número de vencedores** e **número de suplentes** (sorteados por ordem depois dos vencedores). - **Um prémio por pessoa**: um participante sorteado uma segunda vez é ignorado. - **Piloto automático**: selagem na data de fim, sorteio na data anunciada, emails aos vencedores (requer o URL cron). - **Substituir os vencedores que não reclamam a tempo**: no fim do prazo, o vencedor é marcado como desistente e o suplente seguinte recebe o email (requer o URL cron). - **Dias para reclamar o prémio**. A impressão digital do sorteio é criada quando o passatempo é guardado pela primeira vez e não pode mudar depois. Após a selagem, as datas, as definições de participação e o número de vencedores ficam bloqueados. ### Regulamento Se ficar vazio, é gerado um regulamento em 9 artigos a partir das definições do passatempo e dos dados do organizador. Pode escrever o seu próprio texto com as variáveis `{organizer}`, `{contest_name}`, `{date_start}`, `{date_end}`, `{draw_date}`, `{nb_winners}`, `{prize}`, `{claim_days}`, `{verify_url}`, `{commitment}` e as restantes indicadas no separador. O regulamento gerado é um modelo. Mande validá-lo segundo a lei de cada país onde o passatempo está aberto. Em Portugal, por exemplo, os concursos e sorteios publicitários estão sujeitos a autorização prévia quando dependem da sorte. ## Na loja - **/contests**: lista dos passatempos a decorrer, futuros e terminados. - **Página do passatempo**: contagem decrescente, prémios, formas de participar, formulário e, depois de participar, código de participação, número de participações e ligação de partilha. Depois do sorteio: lista de vencedores e aviso «Ganhou!» para o visitante em causa. - **/rules**: regulamento para imprimir. **/draw**: página de verificação. - **Página de produto e carrinho**: aviso nos produtos elegíveis e mensagem de progresso. - **Confirmação da encomenda**: participações obtidas com o respetivo código. - **A minha conta > As minhas participações em passatempos**: histórico, estado e botão para reclamar o prémio para os vencedores. - **Widget**: na página inicial, ou em qualquer sítio com `{widget name="dfcontest"}` ou `{widget name="dfcontest" id_contest=3}`. ## Desenrolar do sorteio O painel do passatempo (botão **Ver** na lista) apresenta o sorteio em 4 passos. 1. **Impressão digital publicada**: a impressão digital SHA-256 da chave secreta é pública desde a criação do passatempo. 2. **Selar as participações**: disponível depois da data de fim. A lista de participações válidas é congelada e a sua impressão digital publicada. No mesmo momento, o módulo compromete-se com uma ronda futura do [drand](https://drand.love), a aleatoriedade pública da League of Entropy, publicada cerca de dois minutos depois, ou após a data de sorteio anunciada. 3. **Realizar o sorteio**: assim que o valor da ronda é publicado, o módulo obtém-no e sorteia os vencedores e depois os suplentes. Se o seu servidor não conseguir contactar o drand, abra a ligação drand indicada, copie o valor `randomness` e cole-o no campo previsto. 4. **Avisar os vencedores**: cada vencedor recebe um email no idioma da sua participação, com uma ligação para aceitar o prémio e indicar a morada antes do fim do prazo. ### Acompanhar a entrega dos prémios A tabela de vencedores indica para cada um: reclamado (com a morada de entrega), a aguardar resposta ou prazo ultrapassado. O botão **Reenviar** volta a enviar o email e reinicia o prazo. **Marcar como desistente** retira o prémio ao vencedor e passa-o ao primeiro suplente disponível; depois reenvie os emails para o avisar. Quando um vencedor reclama o prémio, o email de contacto do organizador recebe os seus dados. ## Página de verificação A página **/draw** publica a impressão digital da chave, a impressão digital da lista, a ronda drand e depois a chave, o valor público, a semente e os vencedores. Um participante pode pesquisar o seu código na lista selada e iniciar a verificação no navegador, que controla cada passo sem enviar nada para a loja. O ficheiro de prova JSON pode ser descarregado a partir da página e do painel. ## Piloto automático Para um passatempo com a opção **Piloto automático**, cada execução do cron: - sela as participações quando a data de fim já passou; - realiza o sorteio quando se atinge a data anunciada e o valor drand está publicado, e depois envia os emails aos vencedores; - se a opção de substituição estiver ativa, marca como desistentes os vencedores cujo prazo terminou sem reclamação e avisa o suplente seguinte. O cron não tem efeito nos passatempos sem piloto automático. Pode correr com a frequência que quiser. ## Exportações e dados pessoais - **Exportar vencedores (CSV)**: posição, código, contactos, origem, bilhete sorteado, resposta, data do aviso, estado da reclamação e morada de entrega. - **Exportar participações (CSV)**: todas as participações com o estado, a origem e o consentimento para a newsletter. - Com o módulo oficial **psgdpr**, a eliminação de um cliente anonimiza as suas participações e retira as dos passatempos não selados; a exportação RGPD inclui as suas participações e a reclamação do prémio. ## Resolução de problemas ### Uma encomenda paga não criou participação O PrestaShop ignora os hooks de um módulo quando o perfil do funcionário que muda o estado não tem permissão para ver esse módulo. No painel do passatempo, o botão **Verificar encomendas** percorre as encomendas pagas do período e cria as participações em falta. ### Um visitante não recebe o email de confirmação Na página do passatempo aparece o botão **Reenviar a ligação** para uma participação pendente (no máximo um envio a cada dois minutos). Verifique também as definições de email da loja. ### O sorteio não arranca O valor da ronda drand só é publicado à hora indicada no painel. Depois dessa hora, se o drand continuar inacessível a partir do servidor, cole o valor `randomness` copiado da ligação drand. ### O cron não faz nada Verifique se o passatempo tem a opção **Piloto automático** e se a loja não está em modo de manutenção, que também bloqueia o URL cron. Em multiloja, chame o URL cron de cada loja.