Criador de formulários para PrestaShop 8 e 9: documentação

O DataFirefly Form Builder acrescenta ao PrestaShop 8 e 9 um criador de formulários de arrastar e soltar. Cada formulário aparece nas posições do tema, numa página CMS, numa janela pop-up ou numa página própria. As respostas são guardadas no back-office, enviadas por email e exportáveis em CSV.

Instalação

1. Em Módulos > Gestor de módulos, clique em Enviar um módulo e largue o ficheiro dfformbuilder.zip.
2. Aparecem dois menus em Apoio ao cliente: Formulários e Respostas dos formulários.
3. O botão Configurar do módulo abre as definições gerais (ver abaixo) e mostra o número de formulários e de respostas por ler.

Requisitos: PrestaShop 8.0.0 a 9.x, PHP 7.2 ou superior. Os ficheiros enviados pelos visitantes ficam em /upload/dfformbuilder/, que tem de ter permissão de escrita. O módulo não usa nenhum override.

Atualização: instale o novo ZIP por cima do anterior. Os formulários e as respostas são mantidos e os scripts de atualização acrescentam as novas tabelas.

Criar um formulário

Em Apoio ao cliente > Formulários, clique em Novo formulário e escolha um ponto de partida:

• Formulário de contacto: nome, email, assunto e mensagem. O campo Referência da encomenda só aparece se o assunto for uma encomenda.
• Pedido de orçamento: particular ou empresa (os campos Empresa e NIF só aparecem para uma empresa), quantidade, orçamento, prazo, anexos. Numa ficha de produto, o nome do produto é preenchido automaticamente.
• Candidatura: três passos (dados de contacto, função, documentos), CV obrigatório e anexado ao email.
• Formulário vazio.

A lista de formulários oferece também Duplicar, Exportar (ficheiro JSON) e, na barra de ferramentas, Importar. Um formulário importado é criado desativado e sem posições de apresentação.

O criador

A barra superior contém o nome interno do formulário, a caixa Ativado, o idioma de edição, os botões Anular e Refazer, Pré-visualizar e Guardar. Por baixo há quatro separadores: Campos, Definições, Emails, Apresentação e integração.

Separador Campos

• Coluna da esquerda: os tipos de campo. Um clique acrescenta o campo por baixo do selecionado, arrastar coloca-o onde quiser.
• Centro: o formulário tal como vai aparecer, com as larguras reais. Os campos movem-se arrastando ou com as setas de cada cartão, e podem ser duplicados ou eliminados.
• Coluna da direita: as definições do campo selecionado.

Atalhos: Enter seleciona um campo, Alt + setas move-o, Delete elimina-o, Ctrl+Z anula, Ctrl+Y refaz, Ctrl+S guarda. O navegador avisa se sair da página com alterações por guardar.

Idiomas

Todos os textos (etiquetas, ajudas, opções, mensagens, emails, URL) são escritos no idioma escolhido no topo. Um texto vazio usa o do idioma predefinido da loja, mostrado a cinzento no campo. Reveja cada idioma antes de publicar.

Chave do campo

Cada campo de preenchimento tem uma chave técnica gerada a partir da etiqueta (por exemplo email, order_reference). É o nome da coluna na exportação CSV e uma variável nos emails: {email}. Tem de ser única no formulário.

Tipos de campo

• Texto, Email, Telefone, Site: texto de exemplo, comprimento máximo, preenchimento. Um endereço web escrito sem https:// é completado automaticamente.
• Número: mínimo, máximo e incremento.
• Texto longo: altura em linhas, comprimento máximo com contador de caracteres para o visitante.
• Data: data mais cedo e mais tarde, no formato AAAA-MM-DD ou com a palavra today.
• Lista pendente, Botões de opção, Caixas de seleção: opções com etiqueta por idioma e valor. O valor é guardado e usado pela lógica; vazio, usa a etiqueta. A ligação Acrescentar várias opções de uma vez aceita uma opção por linha, no formato etiqueta|valor se necessário.
• Consentimento: uma caixa com um texto que aceita ligações (política de privacidade).
• Classificação por estrelas: de 3 a 10 estrelas, guardada como 4/5.
• Envio de ficheiros: extensões permitidas, tamanho máximo por ficheiro (limitado pela definição global), vários ficheiros até 10.
• Campo oculto: valor fixo ou preenchido, invisível para o visitante.
• Título, Bloco de texto, Separador: apenas paginação, nada é guardado.
• Novo passo: divide o formulário em passos (ver abaixo).

Cada campo tem uma largura: inteira, dois terços, metade ou um terço. Os campos mais estreitos ficam lado a lado em ecrãs grandes e empilhados no telemóvel.

Preenchimento

Os campos Texto, Email, Telefone e Oculto podem ser preenchidos com o email, o nome, o apelido, o nome completo ou a empresa do cliente com sessão iniciada, o nome ou a referência do produto (numa ficha de produto), o URL da página ou um parâmetro de URL. Exemplo: um campo oculto preenchido com o parâmetro utm_source e uma ligação para /contacto?utm_source=newsletter guardam newsletter com a resposta.

Endereço de resposta

Marque Usar como endereço de resposta num campo Email: responder ao email de notificação escreve diretamente ao visitante.

Lógica condicional

No painel de um campo, marque Mostrar ou ocultar este campo conforme outras respostas e escolha:

• Mostrar ou Ocultar este campo;
• se todas ou pelo menos uma das condições forem cumpridas;
• cada condição: um campo, um operador (é, não é, contém, não contém, está vazio, está preenchido, é maior que, é menor que) e um valor.

Para uma lista, botões de opção ou caixas, o valor escolhe-se entre as opções. Um campo oculto não é validado, guardado nem enviado. A mesma lógica é recalculada no servidor no momento do envio.

Formulários em vários passos

Acrescente um elemento Novo passo (grupo Paginação) onde um passo deve começar e dê-lhe um título. Os campos antes do primeiro marcador formam o primeiro passo. Para o visitante:

• aparecem uma barra de progresso e os títulos dos passos (desativável em Definições > Formulário em vários passos);
• os botões Seguinte e Anterior têm um texto definido por idioma;
• cada passo é verificado antes de avançar;
• um passo cujos campos estão todos ocultos pela lógica é saltado.

Separador Definições

• Título e introdução: título mostrado aos visitantes e texto de introdução.
• Envio: texto do botão, mensagem de confirmação ou redirecionamento para um URL após o envio.
• Acesso: formulário reservado a clientes com sessão iniciada (os outros veem uma ligação para iniciar sessão), classe CSS.
• Disponibilidade e limites: data de abertura e de fecho (fuso horário da loja), número máximo de respostas, uma só resposta por pessoa (verificada pela conta de cliente e pelo email escrito), mensagem de fecho.
• Rascunho: guarda as respostas 30 dias no navegador do visitante até ao envio. Nada é transmitido à loja antes do envio e os ficheiros não são conservados.

Separador Emails

Notificação à loja

Enviada no idioma predefinido da loja. Destinatários separados por vírgulas; se o campo estiver vazio, usam-se os destinatários predefinidos da configuração do módulo e depois o email da loja. O assunto aceita as variáveis {form_name} e {chave_do_campo}, que se copiam com um clique. A opção Anexar os ficheiros enviados acrescenta os ficheiros até 15 MB no total.

Destinatários condicionais

Cada regra associa uma condição a endereços: por exemplo, se Assunto for Orçamento, enviar para vendas@a-sua-loja.pt. A definição Quando uma condição é cumprida acrescenta estes endereços aos destinatários ou substitui-os.

Confirmação ao visitante

Requer um campo Email no formulário. O email sai no idioma que o visitante usou, com o assunto e a mensagem que escolher (variáveis aceites) e, opcionalmente, um resumo das respostas.

Webhook

Indique um URL (Zapier, Make, n8n, CRM) para receber cada resposta em JSON através de um pedido POST. Exemplo de conteúdo:

{
  "event": "submission.created",
  "form": { "id": 3, "name": "Contacto" },
  "submission": { "id": 128, "date": "2026-09-30T10:12:00+02:00", "language": "pt",
    "shop_id": 1, "customer_id": 0, "product_id": 0, "page_url": "https://..." },
  "fields": {
    "email": { "label": "Email", "type": "email", "value": "joao@exemplo.pt", "display": "joao@exemplo.pt" }
  }
}

Com um segredo de assinatura, o cabeçalho X-DFFB-Signature contém sha256= seguido do HMAC-SHA256 do corpo. Verificação em PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, 'O_SEU_SEGREDO');
$valid = hash_equals($expected, $_SERVER['HTTP_X_DFFB_SIGNATURE'] ?? '');

A chamada espera no máximo 5 segundos. O resultado (entregue, recusado com o código HTTP, sem resposta) aparece na ficha de cada resposta.

Separador Apresentação e integração

Modo de apresentação

Diretamente na página ou atrás de um botão, numa janela pop-up, com o texto do botão por idioma. Este modo aplica-se às posições, ao shortcode e ao widget.

Posições automáticas

Marque as posições do tema: página inicial (displayHome), página de contacto (displayContactContent, displayContactRightColumn), ficha de produto (displayProductAdditionalInfo, displayFooterProduct), garantias (displayReassurance), carrinho (displayShoppingCartFooter), páginas CMS (displayCMSDisputeInformation), colunas (displayLeftColumn, displayRightColumn), acima do rodapé (displayFooterBefore), fim do conteúdo (displayWrapperBottom). Uma posição não mostra nada se o tema não a chamar.

Página própria

Cada formulário pode ter a sua página, por exemplo /forms/3-pedido-de-orcamento, com um URL amigável por idioma. A ligação Pré-visualizar funciona mesmo com o formulário desativado; os envios são recusados até ser ativado.

Códigos de integração

• Shortcode para página CMS: [dfform id=3]
• Widget Smarty num template: {widget name='dfformbuilder' id_form=3}
• Hook personalizado: {hook h='displayDfForm' id_form=3}

Estatísticas

Em 30 dias: visualizações (formulário mostrado ou janela aberta), preenchimentos iniciados (clique num campo), respostas, taxas de conversão e de abandono. Visitantes sem JavaScript e a maioria dos robots não são contados. As visualizações e a taxa de conversão aparecem também na lista de formulários.

Gerir as respostas

Apoio ao cliente > Respostas dos formulários lista as respostas com o formulário, um resumo, o estado e a data, com filtros. Ações em massa: marcar como lido, tratado, arquivar, exportar em CSV, eliminar (os ficheiros também são eliminados).

Abrir uma resposta passa-a para Lido e mostra:

• todas as respostas e os ficheiros para descarregar;
• o estado e uma nota interna;
• o cliente (se tinha sessão iniciada), o produto, a página de envio, o idioma, o endereço IP, o resultado do email e do webhook;
• os botões Imprimir, Responder por email, resposta anterior e seguinte.

Responder ao visitante

O painel Responder ao visitante envia a sua mensagem para o endereço do campo Email (primeiro o marcado como endereço de resposta), no idioma que o visitante usou, com a paginação de email da loja. A resposta fica no histórico e a resposta pode passar a Tratado ao mesmo tempo.

Exportação CSV

O painel por baixo da lista exporta por formulário, estado e período. Escolher um formulário dá uma coluna por campo. O ficheiro está em UTF-8 com ponto e vírgula como separador e abre diretamente no Excel, no LibreOffice e no Google Sheets.

Definições gerais do módulo

• Destinatários predefinidos: usados quando um formulário não tem destinatários próprios.
• Tamanho máximo dos ficheiros (10 MB por predefinição): limite global por ficheiro. Não pode ultrapassar upload_max_filesize e post_max_size do PHP.
• Conservar as respostas durante (dias): depois disso, as respostas e os ficheiros são eliminados automaticamente. 0 conserva-as sem limite.
• Guardar o endereço IP: se desativado, apenas é guardado um hash para o limite de envios.
• Tempo mínimo de preenchimento (3 segundos) e envios por hora e por visitante (10): proteções contra robots.
• reCAPTCHA v3: chave do site, chave secreta e pontuação mínima (0,5 recomendado). O script da Google só carrega quando o visitante começa a preencher o formulário.

Segurança e RGPD

• Cada formulário inclui um campo armadilha invisível e uma assinatura com data; um envio demasiado rápido ou acima do limite é recusado.
• Scripts, páginas HTML e executáveis são sempre recusados e o conteúdo dos ficheiros é verificado. Os ficheiros recebem um nome aleatório numa pasta protegida e só se descarregam no back-office.
• Com o módulo oficial psgdpr, as respostas de um cliente (conta ou email escrito) entram na exportação dos seus dados e são eliminadas com a conta.

Traduções

A interface do módulo está disponível em francês e inglês; os outros idiomas do back-office mostram-na em inglês. Os modelos de email do módulo existem em inglês, francês, alemão, espanhol, italiano, neerlandês, polaco e português. Os textos dos próprios formulários são escritos em todos os idiomas da loja.

Resolução de problemas

O formulário não aparece

Verifique se o formulário está ativado, se o tema chama a posição escolhida e se as datas de abertura não o fecham. Em caso de dúvida, teste o shortcode numa página CMS ou a página própria.

Os emails não chegam

A ficha da resposta indica se a notificação foi enviada. Verifique Parâmetros avançados > Email e envie um email de teste a partir do PrestaShop.

Um ficheiro é recusado

Verifique a extensão permitida no campo, o tamanho máximo do campo e do módulo e os limites PHP upload_max_filesize e post_max_size.

A proteção antispam bloqueia o formulário

Uma página aberta há várias semanas tem uma assinatura expirada: o visitante tem de recarregar a página. Se usar o reCAPTCHA, verifique se o domínio está declarado na consola da Google e baixe a pontuação mínima se clientes reais forem bloqueados.