OW Forms — Documentación

Un constructor de formularios moderno y nativo RGPD para WordPress. Autor: OptionWeb — Julien Daniel Página del plugin: https://optionweb.dev/es/addons/ow-forms/ Licencia: GPL-2.0-or-later Versión cubierta por este documento: 1.0.2

---

Índice

1. Visión general
2. Instalación
3. Inicio rápido — tu primer formulario
4. Tipos de campos
5. Stack anti-spam
6. Funciones RGPD
7. Notificaciones por email
8. Webhooks
9. Subida de archivos
10. Renderizado: shortcode, Gutenberg, REST
11. Importador de Contact Form 7
12. Referencia de ajustes
13. API REST
14. Hooks para desarrolladores (filters & actions)
15. Integración con OW Consent / OW Shield
16. Internacionalización
17. Solución de problemas
18. FAQ

---

Visión general

OW Forms es un constructor de formularios dirigido por esquema. Cada formulario es un documento JSON que describe sus campos, validación y comportamiento al enviar. El plugin renderiza ese esquema como HTML accesible, valida los envíos en el servidor, los hace pasar por un stack anti-spam de cuatro capas, persiste lo que le permitas persistir, y dispara notificaciones por email + webhook.

Lo que incluye (todo gratis, GPL-2):

• Motor de esquema JSON con 17 tipos de campos
• Anti-spam de 4 capas: honeypot, time-trap, CAPTCHA multi-proveedor, reputación IP
• Consentimiento RGPD nativo + retención + DSAR
• API REST (namespace owf/v1) — submit público + CRUD admin
• Bloque Gutenberg + shortcode + API de renderizado PHP
• Webhooks salientes firmados con HMAC
• Importador de Contact Form 7 de un clic
• Detecta automáticamente los tokens del tema OW Canvas para consistencia visual

Lo que deliberadamente NO hace:

• Procesamiento de pagos (usa WooCommerce + un checkout dedicado)
• Wizards multipágina más allá del simple siguiente/anterior (usa un plugin de wizard dedicado)
• Constructor visual drag-and-drop en v1 (sólo editor JSON; constructor visual en la roadmap)

---

Instalación

Desde WordPress.org (recomendado)

1. Admin WordPress → Plugins → Añadir nuevo
2. Busca OW Forms
3. Haz clic en Instalar ahora, luego en Activar

Desde subida .zip

1. Descarga ow-forms-1.0.2.zip desde https://optionweb.dev/es/addons/ow-forms/
2. Plugins → Añadir nuevo → Subir plugin
3. Elige el archivo, haz clic en Instalar ahora, luego en Activar

Requisitos

• WordPress 6.0 o posterior
• PHP 7.4 o posterior (8.1+ recomendado)
• MySQL/MariaDB con soporte de columna JSON (5.7+ / 10.2+)

Qué se instala

Al activarse, OW Forms crea tres tablas personalizadas:

• {prefix}_owf_submissions — payloads de envíos + metadatos de spam
• {prefix}_owf_files — registro de archivos subidos
• {prefix}_owf_log — pista de auditoría de envíos

Más un Custom Post Type owf_form (no consultable públicamente) usado para almacenar los esquemas de formulario.

---

Inicio rápido

Tras la activación se crea automáticamente un formulario "Contacto" por defecto.

1. Ve a OW Forms → Formularios en el admin
2. Anota el ID del formulario por defecto (p. ej. 1)
3. En cualquier página o entrada, coloca el shortcode:

[owf_form id="1"]

…o inserta el bloque Gutenberg OW Forms y elige el formulario en el desplegable.

Eso es todo. El formulario se renderiza, acepta envíos, envía un email admin a admin_email, y almacena el envío en la base de datos.

Para personalizarlo, abre el formulario en OW Forms → Formularios → [Editar] y ajusta directamente el esquema JSON. Un constructor visual está en la roadmap v1.1.

---

Tipos de campos

OW Forms soporta 17 tipos de campos. Cada campo en el esquema es un objeto con al mínimo type y name; la mayoría también aceptan label, help, required, placeholder y opciones específicas del tipo.

Ejemplo 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": ""
  }
}

Los valores name de los campos se convierten en claves del payload almacenado y en tokens que puedes usar en plantillas de email ({{name}}, {{email}}, etc.).

---

Stack anti-spam

OW Forms ejecuta cuatro capas independientes en paralelo. Cada capa aporta una contribución al score; un envío con score ≥ 80 se descarta silenciosamente — no se devuelve mensaje de error, para que los bots no puedan iterar contra la protección.

1. Honeypot

Un campo de texto oculto visualmente que los bots rellenan y los humanos no. Ajuste:

• spam_honeypot_enabled (por defecto: true)

2. Time-trap

Rechaza envíos completados más rápido que un umbral configurable (los bots típicos hacen POST instantáneamente).

• spam_timetrap_enabled (por defecto: true)
• spam_timetrap_min_seconds (por defecto: 2)

3. CAPTCHA (multi-proveedor)

Validación servidor-a-servidor del token contra la API del proveedor. Elige uno de:

• turnstile — Cloudflare Turnstile (recomendado, prioriza la privacidad, sin UX de challenge)
• recaptcha_v3 — Google reCAPTCHA v3 (invisible)
• hcaptcha — hCaptcha (widget visible)
• friendly_captcha — Friendly Captcha (widget self-hosted, con licencia MIT, EU-friendly)

Configura spam_captcha_provider, spam_captcha_site_key y spam_captcha_secret_key en la pestaña de ajustes Anti-spam. Por defecto es none.

Nota: el JS de los widgets Turnstile / reCAPTCHA / hCaptcha se carga desde el origen del propio proveedor (su JS hace una comprobación de firma de origen en servidor). Friendly Captcha es self-hosted bajo assets/js/vendor/.

4. Reputación IP (opcional)

Cuando OW Shield está instalado y activo, OW Forms usa su feed de reputación IP para puntuar los envíos:

• spam_owshield_iprep (por defecto: true)
• spam_block_disposable_emails (por defecto: true) — rechaza @mailinator, @tempmail y ~120 otros dominios desechables

Heurísticas adicionales

• spam_min_words_per_text_area — exige al menos N palabras en textareas
• spam_max_links_per_submission — rechaza si hay más de N URLs en el payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — tus propias listas

Registro

Toda decisión de spam se registra con su motivo. Revisa OW Forms → Envíos → filtro "spam" para ajustar umbrales sin volar a ciegas.

---

Funciones RGPD

El cumplimiento RGPD es nativo. Los valores por defecto son conservadores; relájalos sólo si tienes asesoramiento legal para ello.

Casilla de consentimiento

Una casilla de consentimiento se auto-inyecta al final de cada formulario cuando gdpr_consent_required es true (por defecto). El texto es configurable:

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

Si gdpr_auto_link_privacy está activo (por defecto), las palabras "privacy policy" / "política de privacidad" se enlazan automáticamente a la URL de política de privacidad de OW Consent cuando ese plugin está activo, o a tu Página de Privacidad configurada en WP.

Modos de almacenamiento de IP

Ajuste store_ip:

Almacenamiento del user agent

Ajuste store_user_agent:

Retención y purga

Un cron diario purga los envíos más antiguos que gdpr_retention_days (por defecto: 1095 días — el estándar CNIL para datos de prospectos). Pon 0 para deshabilitar la purga automática.

Si gdpr_auto_delete_after_response es true, marcar un envío como "gestionado" lo elimina inmediatamente junto con cualquier archivo subido.

DSAR — Acceso / borrado por interesado

Los emails del formulario se hashean con wp_salt() al almacenarlos. Cuando OW Consent está activo y se procesa un borrado DSAR para una dirección de email, OW Forms elimina automáticamente los envíos correspondientes por email_hash y dispara:

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

Sin OW Consent, puedes invocar el borrado manualmente:

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

---

Notificaciones por email

Plantillas

Tanto la notificación admin como la auto-respuesta de usuario soportan sustitución {{token}}:

Ajustes

Sobrescritura por formulario

El esquema del formulario puede sobrescribir los globales:

{
  "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

Cuando webhook_url está definido, cada envío con éxito dispara un 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"
}

Firma HMAC

Si webhook_secret está definido, la petición incluye:

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

Verificación en el receptor (ejemplo 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');
}

Reintentos

Si el receptor devuelve 5xx o tiempo de espera agotado, OW Forms reintenta con backoff exponencial (60 s → 5 min → 30 min). Tras 3 fallos, el webhook se registra como definitivamente fallido pero no bloquea el envío.

---

Subida de archivos

Cuando allow_file_uploads está activo (por defecto true), cualquier campo de tipo file se acepta. La pipeline:

1. Validación en el servidor — tamaño de archivo (max_file_size_mb, por defecto 8 MB), allowlist de extensiones (allowed_file_types) y comprobación MIME con finfo cotejada contra wp_get_mime_types().
2. Almacenamiento — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> con un .htaccess deny-all (Apache) e index.php vacío (Nginx/IIS).
3. Registro en BD — metadatos del archivo + hash SHA-256 en {prefix}_owf_files, enlazado al ID de envío padre.
4. Limpieza — cuando se elimina un envío (manualmente, por retención o por DSAR), se eliminan todos los archivos enlazados.

Importante: OW Forms usa una ruta de subida aislada personalizada, no la biblioteca de medios de WordPress, por lo que los archivos subidos no son descubribles a través del endpoint estándar /wp-json/wp/v2/media y no se generan miniaturas. Es deliberado — los adjuntos de formulario son privados al propietario del formulario.

Tipos de archivo permitidos (por defecto)

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

Para ampliar:

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

---

Renderizado

Shortcode

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

id (ID numérico del post) o slug (slug del post) — uno es obligatorio.

Bloque Gutenberg

En el editor de bloques, busca "OW Forms" en el insertor y elige tu formulario del desplegable.

PHP

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

REST

El formulario también puede enviarse programáticamente — ver API REST.

---

Importador CF7

Si Contact Form 7 está o estuvo instalado, OW Forms se entrega con un importador de un clic.

OW Forms → Herramientas → Importar desde Contact Form 7

El importador:

1. Escanea cada post wpcf7_contact_form de tu base de datos
2. Analiza cada formulario CF7 basado en shortcode y construye el esquema OW Forms equivalente
3. Conserva destinatario, asunto, mensajes de éxito/error y tipos de campo
4. Reescribe cada shortcode [contact-form-7 id="..."] en todo tu post_content (páginas, entradas, custom post types) a [owf_form id="..."]
5. Registra resultados: formularios encontrados, importados, omitidos (ya importados)

El plugin CF7 puede entonces desactivarse y eliminarse.

El importador es idempotente: ejecutarlo dos veces no crea duplicados. Los formularios CF7 ya importados se marcan mediante una meta key _owf_imported_from_cf7 y se omiten en ejecuciones subsiguientes.

---

Referencia de ajustes

Todos los ajustes se almacenan en una sola clave de opción, owf_settings. Puedes leerlos o sobrescribirlos programáticamente:

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

Valores por defecto 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 los endpoints viven bajo el 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": ""
}

Respuesta (200):

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

Respuesta (422) cuando falla la validación:

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

Endpoints admin (requieren manage_options)

Todos los endpoints admin requieren tanto la capability manage_options como un 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 );

Patrón recomendado — ampliar lista de dominios desechables

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

Patrón recomendado — empujar envíos a un 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 );

---

Integraciones

OW Canvas (tema)

Cuando el tema OW Canvas está activo, OW Forms hereda sus propiedades CSS personalizadas (--owc-ink, --owc-paper, --owc-accent, etc.) para coherencia visual. Desactiva con inherit_theme_tokens = false.

OW Consent

Cuando OW Consent está activo:

• El enlace de la casilla de consentimiento RGPD apunta automáticamente a tu URL de política de privacidad de OW Consent
• Los envíos se enlazan a los registros de OW Consent (cuando el visitante tiene una cookie de ID de consentimiento)
• Los flujos de borrado DSAR desde OW Consent purgan automáticamente los envíos de OW Forms para el mismo hash de email

OW Shield

Cuando OW Shield está activo y spam_owshield_iprep está activado, la IP de cada envío se puntúa contra el feed de reputación de OW Shield antes de ser aceptada.

---

Internacionalización

El idioma fuente es inglés. Se incluye una traducción francesa bajo languages/ow-forms-fr_FR.po.

Para traductores

La plantilla .pot está en languages/ow-forms.pot. Envía traducciones vía translate.wordpress.org/projects/wp-plugins/ow-forms una vez aprobado el plugin en WP.org. Para distribución local, coloca ow-forms-<locale>.mo en la carpeta languages/.

Compilar .mo localmente

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

---

Solución de problemas

El formulario se envía pero no llega ningún email

1. Comprueba que tu sitio puede enviar mails siquiera — prueba un envío desde el formulario de contacto de otro plugin o con Mail Tester
2. Comprueba OW Forms → Envíos para confirmar que el envío llegó (si sí, el problema es la entrega, no OW Forms)
3. Configura mail_failed_alert_email con tu propia dirección — OW Forms te enviará un email cuando wp_mail() devuelva false
4. Instala un plugin SMTP (Fluent SMTP, WP Mail SMTP, etc.) — el mail() PHP por defecto es rechazado por el 95 % de los servidores receptores

El CAPTCHA no aparece

• Verifica que spam_captcha_site_key y spam_captcha_secret_key están ambos configurados
• Abre la página en las DevTools — la URL del script del proveedor debería cargar con 200
• Para reCAPTCHA, el dominio de tu sitio debe estar registrado en el admin de Google
• Para Turnstile, el modo widget en el admin Cloudflare debe ser "Managed" o "Non-interactive"

Los archivos se suben pero el admin no puede descargarlos

Es por diseño — los archivos subidos los sirve un handler PHP autenticado, no directamente. Comprueba que estás logueado como un usuario con manage_options.

El importador CF7 dice "0 formularios encontrados"

El importador escanea el post type wpcf7_contact_form. Si CF7 ya está desactivado y los posts fueron eliminados, ya no queda nada para importar. Reactiva CF7 sólo para la importación, y desactívalo de nuevo después.

La tabla de envíos es enorme

• Reduce gdpr_retention_days (por defecto 1095 / 3 años)
• Desactiva store_submissions si sólo necesitas la entrega de email, no un registro de auditoría en BD
• Pon gdpr_auto_delete_after_response = true para borrar al marcar como "gestionado"

---

FAQ

¿Es OW Forms gratis? Sí. GPL-2.0-or-later. No hay versión Pro, ni clave de licencia, ni función bloqueada tras pago.

¿Funciona en WordPress Multisite? Sí — cada sitio tiene sus propias tablas y biblioteca de formularios, aislados como se espera.

¿Soporta formularios multi-paso? La navegación básica siguiente/anterior funciona mediante agrupación de campos en el esquema. Una UX de wizard de primera clase está en la roadmap v1.1.

¿Cómo exporto los envíos? OW Forms → Envíos → Exportar CSV. La exportación respeta los filtros actuales (formulario, rango de fechas, estado).

¿Puedo alojar mis formularios tras un paywall o login? Sí — envuelve el shortcode en la lógica de gating de cualquier plugin de membresía, o renderiza vía PHP dentro de una comprobación is_user_logged_in().

¿Se integra con herramientas de email marketing / CRM? De serie: webhooks (POST firmado HMAC a cualquier endpoint) y destinatarios de email por formulario. Para Brevo / Mailchimp / HubSpot / Pipedrive, conecta a owf_submission_received y llama a la API REST del proveedor — ver la sección Hooks.

¿Está el plugin certificado RGPD? Los valores por defecto del plugin están alineados con las mejores prácticas CNIL / RGPD, pero la certificación es un proceso legal específico de tu configuración como responsable del tratamiento. Nosotros proporcionamos las herramientas técnicas; tu DPD valida la política.

¿Dónde está el soporte?

• Portal de soporte: https://optionweb.dev/es/addons/support/
• Email: support@optionweb.dev
• Documentación: https://optionweb.dev/es/addons/ow-forms/

---

Construido por OptionWeb — Julien Daniel, Châtelet, Bélgica.