OW Forms — Documentação

Um construtor de formulários moderno e RGPD-nativo para WordPress. Autor: OptionWeb — Julien Daniel Página do plugin: https://optionweb.dev/pt/addons/ow-forms/ Licença: GPL-2.0-or-later Versão coberta por este documento: 1.0.2

---

Índice

1. Visão geral
2. Instalação
3. Início rápido — o seu primeiro formulário
4. Tipos de campos
5. Stack anti-spam
6. Funcionalidades RGPD
7. Notificações por email
8. Webhooks
9. Carregamento de ficheiros
10. Renderização: shortcode, Gutenberg, REST
11. Importador Contact Form 7
12. Referência de configurações
13. API REST
14. Hooks para programadores (filters & actions)
15. Integração com OW Consent / OW Shield
16. Internacionalização
17. Resolução de problemas
18. FAQ

---

Visão geral

OW Forms é um construtor de formulários dirigido por esquema. Cada formulário é um documento JSON que descreve os seus campos, validação e comportamento de envio. O plugin renderiza esse esquema como HTML acessível, valida os envios no servidor, fá-los passar por uma stack anti-spam de quatro camadas, persiste o que lhe permitir persistir, e dispara notificações por email + webhook.

O que inclui (tudo gratuito, GPL-2):

• Motor de esquema JSON com 17 tipos de campos
• Anti-spam de 4 camadas: honeypot, time-trap, CAPTCHA multi-fornecedor, reputação IP
• Consentimento RGPD nativo + retenção + DSAR
• API REST (namespace owf/v1) — submit público + CRUD admin
• Bloco Gutenberg + shortcode + API de renderização PHP
• Webhooks de saída assinados com HMAC
• Importador Contact Form 7 de um clique
• Deteta automaticamente os tokens do tema OW Canvas para consistência visual

O que deliberadamente NÃO faz:

• Processamento de pagamentos (use WooCommerce + um checkout dedicado)
• Wizards multipágina além do simples seguinte/anterior (use um plugin de wizard dedicado)
• Construtor visual drag-and-drop em v1 (apenas editor JSON; construtor visual na roadmap)

---

Instalação

Do WordPress.org (recomendado)

1. Admin WordPress → Plugins → Adicionar novo
2. Pesquise por OW Forms
3. Clique em Instalar agora, depois em Ativar

Por upload .zip

1. Descarregue ow-forms-1.0.2.zip de https://optionweb.dev/pt/addons/ow-forms/
2. Plugins → Adicionar novo → Carregar plugin
3. Escolha o ficheiro, clique em Instalar agora, depois em Ativar

Requisitos

• WordPress 6.0 ou posterior
• PHP 7.4 ou posterior (8.1+ recomendado)
• MySQL/MariaDB com suporte de coluna JSON (5.7+ / 10.2+)

O que é instalado

Na ativação, OW Forms cria três tabelas personalizadas:

• {prefix}_owf_submissions — payloads de envios + metadados de spam
• {prefix}_owf_files — registo de ficheiros carregados
• {prefix}_owf_log — trilho de auditoria de envios

Mais um Custom Post Type owf_form (não consultável publicamente) usado para armazenar os esquemas dos formulários.

---

Início rápido

Após a ativação, é criado automaticamente um formulário "Contacto" por defeito.

1. Vá a OW Forms → Formulários no admin
2. Anote o ID do formulário por defeito (ex.: 1)
3. Em qualquer página ou artigo, coloque o shortcode:

[owf_form id="1"]

…ou insira o bloco Gutenberg OW Forms e escolha o formulário no menu suspenso.

É isso. O formulário é renderizado, aceita envios, envia um email admin para admin_email, e armazena o envio na base de dados.

Para o personalizar, abra o formulário em OW Forms → Formulários → [Editar] e ajuste diretamente o esquema JSON. Um construtor visual está na roadmap v1.1.

---

Tipos de campos

OW Forms suporta 17 tipos de campos. Cada campo no esquema é um objeto com no mínimo type e name; a maioria também aceita label, help, required, placeholder e opções específicas do tipo.

Exemplo de esquema

{
  "title": "Contact us",
  "fields": [
    {
      "type": "text",
      "name": "name",
      "label": "Your name",
      "required": true,
      "placeholder": "Jane Doe"
    },
    {
      "type": "email",
      "name": "email",
      "label": "Email",
      "required": true
    },
    {
      "type": "select",
      "name": "subject",
      "label": "How can we help?",
      "required": true,
      "options": [
        {"value": "quote",   "label": "Request a quote"},
        {"value": "support", "label": "Technical support"},
        {"value": "other",   "label": "Other"}
      ]
    },
    {
      "type": "textarea",
      "name": "message",
      "label": "Message",
      "required": true,
      "rows": 6
    }
  ],
  "submit": {
    "label": "Send",
    "success_message": "Thanks — we will reply within 24 hours.",
    "redirect_url": ""
  }
}

Os valores name dos campos tornam-se chaves no payload armazenado e tokens que pode usar em templates de email ({{name}}, {{email}}, etc.).

---

Stack anti-spam

OW Forms corre quatro camadas independentes em paralelo. Cada camada atribui uma contribuição para o score; um envio com score ≥ 80 é descartado silenciosamente — nenhuma mensagem de erro é devolvida, para que os bots não possam iterar contra a proteção.

1. Honeypot

Um campo de texto oculto visualmente que os bots preenchem e os humanos não. Configuração:

• spam_honeypot_enabled (padrão: true)

2. Time-trap

Rejeita envios concluídos mais rápido que um limiar configurável (os bots típicos fazem POST instantaneamente).

• spam_timetrap_enabled (padrão: true)
• spam_timetrap_min_seconds (padrão: 2)

3. CAPTCHA (multi-fornecedor)

Validação servidor-a-servidor do token contra a API do fornecedor. Escolha um de:

• turnstile — Cloudflare Turnstile (recomendado, privacy-first, sem UX de desafio)
• recaptcha_v3 — Google reCAPTCHA v3 (invisível)
• hcaptcha — hCaptcha (widget visível)
• friendly_captcha — Friendly Captcha (widget self-hosted, licença MIT, EU-friendly)

Defina spam_captcha_provider, spam_captcha_site_key e spam_captcha_secret_key no separador Anti-spam das configurações. O padrão é none.

Nota: o JS dos widgets Turnstile / reCAPTCHA / hCaptcha é carregado a partir da origem do próprio fornecedor (o JS deles faz uma verificação de assinatura de origem no servidor). Friendly Captcha é self-hosted sob assets/js/vendor/.

4. Reputação IP (opcional)

Quando OW Shield está instalado e ativo, OW Forms usa o seu feed de reputação IP para pontuar os envios:

• spam_owshield_iprep (padrão: true)
• spam_block_disposable_emails (padrão: true) — rejeita @mailinator, @tempmail e ~120 outros domínios descartáveis

Heurísticas adicionais

• spam_min_words_per_text_area — exige pelo menos N palavras nos textareas
• spam_max_links_per_submission — rejeita se houver mais de N URLs no payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — as suas próprias listas

Registo

Cada decisão de spam é registada com o respetivo motivo. Verifique OW Forms → Envios → filtro "spam" para ajustar os limiares sem voar às cegas.

---

Funcionalidades RGPD

A conformidade RGPD é nativa. Os padrões são conservadores; suavize-os apenas se tiver aconselhamento jurídico nesse sentido.

Checkbox de consentimento

Uma checkbox de consentimento é auto-injetada no fim de cada formulário quando gdpr_consent_required é true (padrão). O texto é configurável:

'gdpr_consent_text' => __(
    'I agree that my data will be processed to respond to my inquiry, in accordance with the privacy policy.',
    'ow-forms'
)

Se gdpr_auto_link_privacy estiver ativo (padrão), as palavras "privacy policy" / "política de privacidade" são auto-ligadas ao URL da política de privacidade do OW Consent quando esse plugin está ativo, ou à sua Página de Privacidade configurada no WP.

Modos de armazenamento de IP

Configuração store_ip:

Armazenamento do user agent

Configuração store_user_agent:

Retenção e purga

Um cron diário purga os envios mais antigos que gdpr_retention_days (padrão: 1095 dias — o padrão CNIL para dados de prospects). Defina 0 para desativar a purga automática.

Se gdpr_auto_delete_after_response for true, marcar um envio como "tratado" elimina-o imediatamente juntamente com quaisquer ficheiros carregados.

DSAR — Acesso / apagamento pelo titular

Os emails dos formulários são hasheados com wp_salt() no momento do armazenamento. Quando OW Consent está ativo e um apagamento DSAR é processado para um endereço de email, OW Forms elimina automaticamente os envios correspondentes por email_hash e dispara:

do_action( 'owf_gdpr_erased_for_email', $hash, $count );

Sem OW Consent, pode invocar o apagamento manualmente:

OWF_GDPR::erase_by_email( 'user@example.com' );  // returns int count

---

Notificações por email

Templates

Tanto a notificação admin como a resposta automática ao utilizador suportam substituição {{token}}:

Configurações

Sobreposição por formulário

O esquema do formulário pode sobrepor os globais:

{
  "mail": {
    "recipient": "sales@example.com",
    "subject": "New lead — {{name}}",
    "body": "Lead: {{name}}\\nEmail: {{email}}\\nMessage: {{message}}",
    "autoreply": true,
    "autoreply_subject": "Thanks, {{name}}!",
    "autoreply_body": "Hi {{name}},\\n\\nWe got your message."
  }
}

---

Webhooks

Quando webhook_url está definido, cada envio bem-sucedido aciona um POST HTTP.

Payload (JSON)

{
  "form_id": 1,
  "form_title": "Contact",
  "submission_id": 42,
  "received_at": "2026-05-13T14:32:18+00:00",
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "site": "https://example.com"
}

Assinatura HMAC

Se webhook_secret estiver definido, o pedido inclui:

X-OWF-Signature: sha256=<hex digest of HMAC-SHA256(body, secret)>

Verificação no lado do recetor (exemplo Node):

const expected = crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
const provided = req.headers['x-owf-signature'].replace(/^sha256=/, '');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  return res.status(401).end('bad sig');
}

Retentativas

Se o recetor devolver 5xx ou der timeout, OW Forms tenta novamente com backoff exponencial (60 s → 5 min → 30 min). Após 3 falhas, o webhook é registado como falhado permanentemente mas não bloqueia o envio.

---

Carregamento de ficheiros

Quando allow_file_uploads está ativo (padrão true), qualquer campo do tipo file é aceite. A pipeline:

1. Validação no servidor — tamanho do ficheiro (max_file_size_mb, padrão 8 MB), allowlist de extensões (allowed_file_types) e uma verificação MIME finfo cruzada com wp_get_mime_types().
2. Armazenamento — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> com um .htaccess deny-all (Apache) e index.php vazio (Nginx/IIS).
3. Registo em BD — metadados do ficheiro + hash SHA-256 em {prefix}_owf_files, ligado ao ID do envio pai.
4. Limpeza — quando um envio é eliminado (manualmente, por retenção, ou por DSAR), todos os ficheiros ligados são removidos.

Importante: OW Forms usa um caminho de upload isolado personalizado, não a biblioteca de media do WordPress, pelo que os ficheiros carregados não são detetáveis através do endpoint padrão /wp-json/wp/v2/media e não são geradas miniaturas. Isto é deliberado — os anexos do formulário são privados ao proprietário do formulário.

Tipos de ficheiros permitidos (padrão)

pdf, jpg, jpeg, png, webp, doc, docx, xls, xlsx, csv, txt

Para estender:

add_filter( 'owf_settings', function( $s ) {
    $s['allowed_file_types'] = array_merge(
        (array) $s['allowed_file_types'],
        array( 'odt', 'ods', 'zip' )
    );
    return $s;
} );

---

Renderização

Shortcode

[owf_form id="42"]
[owf_form slug="contact"]

id (ID numérico do post) ou slug (slug do post) — um é obrigatório.

Bloco Gutenberg

No editor de blocos, pesquise "OW Forms" no inseridor de blocos e escolha o seu formulário na lista pendente.

PHP

echo OWF_Form::render( 42 );
// or
echo do_shortcode( '[owf_form id="42"]' );

REST

O formulário também pode ser submetido programaticamente — ver API REST.

---

Importador CF7

Se Contact Form 7 está ou esteve instalado, OW Forms vem com um importador de um clique.

OW Forms → Ferramentas → Importar de Contact Form 7

O importador:

1. Faz scan a cada post wpcf7_contact_form na sua base de dados
2. Faz parse de cada formulário CF7 baseado em shortcode e constrói o esquema OW Forms equivalente
3. Preserva destinatário, assunto, mensagens de sucesso/erro e tipos de campo
4. Reescreve cada shortcode [contact-form-7 id="..."] em todo o seu post_content (páginas, artigos, custom post types) para [owf_form id="..."]
5. Regista resultados: formulários encontrados, importados, ignorados (já importados)

O plugin CF7 pode então ser desativado e removido.

O importador é idempotente: executá-lo duas vezes não cria duplicados. Os formulários CF7 já importados são marcados via uma meta key _owf_imported_from_cf7 e ignorados em execuções seguintes.

---

Referência de configurações

Todas as configurações são armazenadas numa única chave de opção, owf_settings. Pode lê-las ou sobrescrevê-las programaticamente:

$value = OWF_Core::setting( 'spam_timetrap_min_seconds' );
OWF_Core::update_settings( array( 'spam_timetrap_min_seconds' => 3 ) );

Padrões completos

array(
    // General
    'default_recipient_email'        => '',     // empty = admin_email
    'from_name'                      => '',
    'from_email'                     => '',
    'sender_uses_dpo'                => true,

    // Anti-spam
    'spam_honeypot_enabled'          => true,
    'spam_timetrap_enabled'          => true,
    'spam_timetrap_min_seconds'      => 2,
    'spam_captcha_provider'          => 'none',
    'spam_captcha_site_key'          => '',
    'spam_captcha_secret_key'        => '',
    'spam_owshield_iprep'            => true,
    'spam_block_disposable_emails'   => true,
    'spam_min_words_per_text_area'   => 0,
    'spam_max_links_per_submission'  => 3,
    'spam_blocklist_emails'          => array(),
    'spam_blocklist_words'           => array(),
    'spam_blocklist_ips'             => array(),

    // GDPR
    'gdpr_consent_required'          => true,
    'gdpr_consent_text'              => '...',
    'gdpr_auto_link_privacy'         => true,
    'gdpr_retention_days'            => 1095,
    'gdpr_auto_delete_after_response' => false,

    // Storage
    'store_submissions'              => true,
    'store_ip'                       => 'pseudonymized',
    'store_user_agent'               => 'hashed',
    'allow_file_uploads'             => true,
    'max_file_size_mb'               => 8,
    'allowed_file_types'             => array( 'pdf', 'jpg', 'jpeg', 'png',
                                                'webp', 'doc', 'docx', 'xls',
                                                'xlsx', 'csv', 'txt' ),

    // Notifications
    'mail_html'                      => true,
    'mail_admin_subject'             => '[{{site_name}}] New message via {{form_title}}',
    'mail_admin_body'                => '',
    'mail_user_autoreply_enabled'    => true,
    'mail_user_subject'              => 'We have received your message',
    'mail_user_body'                 => '',
    'mail_failed_alert_email'        => '',
    'webhook_url'                    => '',
    'webhook_secret'                 => '',

    // Rendering
    'style_preset'                   => 'auto',
    'button_label_default'           => 'Send',
    'success_message_default'        => 'Your message has been sent. We will reply within 24 hours.',
    'error_message_default'          => 'An error occurred. Please try again or contact us directly.',
    'inherit_theme_tokens'           => true,

    // Analytics (opt-in)
    'track_conversions'              => false,
    'conversion_event_name'          => 'generate_lead',
    'conversion_value'               => 0,
    'conversion_currency'            => 'EUR',
);

---

API REST

Todos os endpoints vivem sob o namespace owf/v1.

Endpoint público

Body:

{
  "form_id": 1,
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "_owf_nonce": "<from wp_create_nonce('owf_submit_form')>",
  "_owf_time": 1736780000,
  "_owf_hp": ""
}

Resposta (200):

{ "ok": true, "id": 42, "message": "Your message has been sent." }

Resposta (422) quando a validação falha:

{
  "ok": false,
  "errors": { "email": "Please enter a valid email" },
  "message": "Please review the fields in error."
}

Endpoints admin (requerem manage_options)

Todos os endpoints admin requerem tanto a capability manage_options como um nonce REST WP válido.

---

Hooks (filters & actions)

Actions

/**
 * Fires after a submission has been processed and stored.
 *
 * @param int   $submission_id  Database ID (0 if not stored)
 * @param int   $form_id        Form ID
 * @param array $cleaned        Sanitized field payload
 * @param array $schema         Full form schema
 */
do_action( 'owf_submission_received', $submission_id, $form_id, $cleaned, $schema );

/**
 * Fires after a DSAR erasure has deleted matching submissions by email hash.
 *
 * @param string $email_hash   SHA-256(email + wp_salt())
 * @param int    $deleted_count
 */
do_action( 'owf_gdpr_erased_for_email', $email_hash, $deleted_count );

Filters

/**
 * Filter the resolved settings array (merged defaults + saved + per-request).
 */
apply_filters( 'owf_settings', array $settings );

/**
 * Whitelist of trusted reverse proxy IPs that may set X-Forwarded-For.
 * Without this OW Forms ignores proxy headers (to prevent IP spoofing).
 */
apply_filters( 'owf_trusted_proxies', array $proxies );

/**
 * List of disposable email domains rejected when `spam_block_disposable_emails`
 * is on.
 */
apply_filters( 'owf_disposable_domains', array $domains );

Padrão recomendado — estender a lista de domínios descartáveis

add_filter( 'owf_disposable_domains', function( $list ) {
    return array_merge( $list, array(
        'example-throwaway.com',
        'company-blocked-domain.net',
    ) );
} );

Padrão recomendado — empurrar envios para um CRM

add_action( 'owf_submission_received', function( $sid, $form_id, $cleaned ) {
    if ( $form_id !== 7 ) return;  // only the "Sales" form
    wp_remote_post( 'https://crm.example.com/leads', array(
        'headers' => array( 'Authorization' => 'Bearer ' . CRM_TOKEN ),
        'body'    => wp_json_encode( array(
            'email'   => $cleaned['email'],
            'name'    => $cleaned['name'],
            'message' => $cleaned['message'],
            'source'  => 'website-form',
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 3 );

---

Integrações

OW Canvas (tema)

Quando o tema OW Canvas está ativo, OW Forms herda as suas propriedades CSS personalizadas (--owc-ink, --owc-paper, --owc-accent, etc.) para consistência visual. Desative com inherit_theme_tokens = false.

OW Consent

Quando OW Consent está ativo:

• O link da checkbox de consentimento RGPD aponta automaticamente para o URL da política de privacidade do OW Consent
• Os envios são ligados aos registos OW Consent (quando o visitante tem um cookie de ID de consentimento)
• Os fluxos de apagamento DSAR do OW Consent purgam automaticamente os envios OW Forms para o mesmo hash de email

OW Shield

Quando OW Shield está ativo e spam_owshield_iprep está ligado, o IP de cada envio é pontuado contra o feed de reputação do OW Shield antes de ser aceite.

---

Internacionalização

A língua de origem é o inglês. Uma tradução francesa é entregue em languages/ow-forms-fr_FR.po.

Para tradutores

O template .pot está em languages/ow-forms.pot. Submeta traduções via translate.wordpress.org/projects/wp-plugins/ow-forms assim que o plugin for aprovado no WP.org. Para distribuição local, coloque ow-forms-<locale>.mo na pasta languages/.

Compilar o .mo localmente

msgfmt languages/ow-forms-fr_FR.po -o languages/ow-forms-fr_FR.mo

---

Resolução de problemas

O formulário é submetido mas não chega nenhum email

1. Verifique se o seu site consegue enviar email de todo — experimente um teste a partir do formulário de contacto de outro plugin ou com Mail Tester
2. Verifique OW Forms → Envios para confirmar que o envio chegou (se sim, o problema é a entrega, não o OW Forms)
3. Defina mail_failed_alert_email para o seu próprio endereço — OW Forms enviar-lhe-á um email quando wp_mail() devolver false
4. Instale um plugin SMTP (Fluent SMTP, WP Mail SMTP, etc.) — a função mail() PHP padrão é rejeitada por 95 % dos servidores recetores

O CAPTCHA não aparece

• Verifique se spam_captcha_site_key e spam_captcha_secret_key estão ambos definidos
• Abra a página nos DevTools — o URL do script do fornecedor deve carregar com um 200
• Para reCAPTCHA, o domínio do seu site deve estar registado no admin Google
• Para Turnstile, o modo widget no admin Cloudflare deve ser "Managed" ou "Non-interactive"

Os ficheiros são carregados mas o admin não os consegue descarregar

É por design — os ficheiros carregados são servidos por um handler PHP autenticado, não diretamente. Verifique se está autenticado como utilizador com manage_options.

O importador CF7 diz "0 formulários encontrados"

O importador faz scan ao post type wpcf7_contact_form. Se o CF7 já está desativado e os posts foram eliminados, já não há nada para importar. Reative o CF7 só para a importação, e depois desative novamente.

A tabela de envios está enorme

• Reduza gdpr_retention_days (padrão 1095 / 3 anos)
• Desative store_submissions se só precisa da entrega de email, não de um trilho de auditoria em base de dados
• Defina gdpr_auto_delete_after_response = true para eliminar ao marcar como "tratado"

---

FAQ

O OW Forms é grátis? Sim. GPL-2.0-or-later. Não há versão Pro, nem chave de licença, nem funcionalidade bloqueada atrás de pagamento.

Funciona em WordPress Multisite? Sim — cada site tem as suas próprias tabelas e biblioteca de formulários, isolados como esperado.

Suporta formulários multi-passo? A navegação básica seguinte/anterior funciona via agrupamento de campos no esquema. Uma UX de wizard de primeira classe está na roadmap v1.1.

Como exporto os envios? OW Forms → Envios → Exportar CSV. A exportação respeita os filtros atuais (formulário, intervalo de datas, estado).

Posso alojar os meus formulários atrás de uma paywall ou login? Sim — encapsule o shortcode na lógica de gating de qualquer plugin de membership, ou renderize via PHP dentro de uma verificação is_user_logged_in().

Integra com ferramentas de email marketing / CRM? À partida: webhooks (POST assinado HMAC para qualquer endpoint) e destinatários de email por formulário. Para Brevo / Mailchimp / HubSpot / Pipedrive, ligue-se a owf_submission_received e chame a API REST do fornecedor — ver a secção Hooks.

O plugin é certificado RGPD? Os padrões do plugin estão alinhados com as boas práticas CNIL / RGPD, mas a certificação é um processo legal específico à configuração do seu responsável pelo tratamento. Nós fornecemos as ferramentas técnicas; o seu DPO valida a política.

Onde está o suporte?

• Portal de suporte: https://optionweb.dev/pt/addons/support/
• Email: support@optionweb.dev
• Documentação: https://optionweb.dev/pt/addons/ow-forms/

---

Construído por OptionWeb — Julien Daniel, Châtelet, Bélgica.