# 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…

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

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.