Inicio rápido (5 min)
- Instala el plugin desde wp-admin → Plugins → Añadir nuevo → "Flowgration", o sube el zip desde flowgration.com/integrations/wordpress.
- Actívalo. Aparece un nuevo elemento llamado Flowgration en la barra lateral.
- Ábrelo y elige una opción:
- Ya tengo una cuenta en Flowgration → pega una clave API desde Ajustes → Claves API (debe empezar por sk_live_).
- Todavía no tengo cuenta → introduce tu email de administrador; el plugin envía un enlace mágico. Haz clic en él; Flowgration crea automáticamente la organización, el usuario y un CRM inicial, y te inicia sesión.
- El panel de "Estado" se pone verde y los eventos llegan en ~30 segundos.
Dos formas de conectar
Flujo A — cuenta existente
WP plugin Flowgration
│ │
│ POST /onboarding/initiate (mode=connect, api_key=sk_live_…)
├─────────────────────────►│
│ │ verify key → upsert PluginIntegration
│ ◄────────────────────────┤ 200 { review_url, suggested_mappings }
│
│ redirect admin → /app/integrations?integration_id=42- Genera una clave API en Flowgration → Ajustes → Claves API → Nueva clave.
- Pégala en el plugin.
- El plugin hace POST a /api/plugin/onboarding/initiate con mode=connect.
- Flowgration crea una fila PluginIntegration en pending_review y devuelve una URL. El plugin la abre en una nueva pestaña.
Flujo B — automático (enlace mágico)
WP plugin Flowgration Admin inbox
│ │ │
│ POST /onboarding/initiate (mode=auto, admin.email=…) │
├─────────────────────────►│ │
│ │ create PluginOnboarding row │
│ ├──── magic-link email ───────►│
│ │ │
│ │ ◄── admin clicks link ───────┤
│ │ materialize_crm (org+user+CRM)
│ │ 302 → /plugin-callback?token=…&api_key=…- El plugin analiza la instalación de WP (plugins de formularios, tipos de entrada, productos WC).
- Envía el esquema detectado más el email del administrador a /onboarding/initiate.
- El administrador recibe un enlace mágico de un solo uso (TTL 24h).
- Al hacer clic, Flowgration crea la organización, el usuario, el plan del CRM, genera una clave API y redirige a /plugin-callback con el JWT.
- El plugin consulta /onboarding/blueprint?token=… y muestra la pantalla de carga mientras se construye el CRM.
Compatibilidad
- WordPress WordPress 5.8+ (probado hasta 6.6).
- PHP PHP 7.4+ (se recomienda 8.x).
- WooCommerce WooCommerce 7.x+ — opcional. El plugin detecta WC automáticamente y muestra los ajustes específicos de WC solo si está activo.
- WP Multisite — WP Multisitio — no compatible en v1 (ver solución de problemas #9).
- Plugins de formularios compatibles:
- Gravity Forms
- WPForms (Lite and Pro)
- Contact Form 7
- Ninja Forms
- Elementor Pro Forms
- Formidable Forms
- Fluent Forms
Qué se sincroniza
| Evento | Origen | Cuándo se dispara | Qué hace Flowgration |
|---|---|---|---|
user.created | hook user_register | Se registra un nuevo usuario de WP | Crea un Contacto, mapeado según las reglas de campo |
user.updated | hook profile_update | Cambia el perfil de un usuario de WP | Actualiza el Contacto existente |
form.submitted | Plugin de formulario (ver lista arriba) | Se envía cualquier formulario compatible | Crea/actualiza el Contacto, registra la Actividad y dispara los triggers |
order.created | woocommerce_new_order | Se realiza un pedido (cualquier estado) | Crea el Pedido + líneas de pedido, vincula al Contacto |
order.status_changed | woocommerce_order_status_changed | Un pedido de WC cambia de estado | Actualiza el estado del Pedido, dispara order.paid, etc. |
product.created | woocommerce_new_product | Se publica un nuevo producto de WC | Espeja el producto en el catálogo de Flowgration |
cart.abandoned | WC + rastreador de carrito del plugin | Carrito inactivo >30 min, email del cliente conocido | Dispara el trigger cart.abandoned para los journeys |
booking.created | WC Bookings / Amelia / Bookly | Se reserva una nueva cita | Crea la fila de Reserva y la vincula al Contacto |
subscription.activated | WC Subscriptions | Se inicia una suscripción recurrente | Crea la Suscripción y la vincula al Contacto + Plan |
Cada evento lleva una clave de idempotencia, por lo que los reintentos son seguros y los duplicados se descartan en silencio.
Mapeo de campos personalizados
En la primera conexión, Flowgration analiza el esquema detectado (tipos de entrada, campos de formulario, claves meta de WC) y sugiere mapeos a los campos de Contacto existentes. Puedes revisarlos y ajustarlos en /app/integrations → Editar mapeos.
- Las columnas integradas de Contacto (email, nombre y apellido, teléfono, empresa, ciudad, país, …) se rellenan cuando el plugin puede asociar un campo de origen con alta confianza.
- Todo lo demás va a contact.custom_fields[<clave>] — Flowgration crea el campo personalizado al vuelo si no existe.
- Puedes invalidar cualquier sugerencia u omitir un campo de origen por completo.
Pantalla de mapeo —
/docs/plugins/img/wp-mapping.pngEl mapeo se puede editar en cualquier momento. Guardarlo de nuevo no reprocesa los eventos históricos — para eso usa Backfill.
Importación de datos históricos
La página de integración tiene un botón Backfill por fuente de datos (Usuarios, Pedidos, Envíos de formularios). Este botón:
- Obtiene las filas existentes de WordPress en bloques de 500.
- Envía cada bloque por el mismo pipeline /sync que los eventos en vivo, por lo que las reglas de mapeo se aplican de forma idéntica.
- Guarda el progreso por bloque. Si el trabajo se interrumpe (reinicio del worker, error de red o cierre de pestaña por el comerciante), reanuda desde el último bloque completado al volver a hacer clic.
- Omite las filas cuya clave de idempotencia ya está en PluginEventLog, por lo que volver a ejecutar el backfill es seguro.
Rendimiento típico: ~1 000 filas/minuto en un servidor WP saludable.
Actualización del esquema
El plugin guarda en caché el esquema detectado (campos de formulario, tipos de entrada personalizados, claves meta de WC) para mejorar el rendimiento. Fuerza una actualización cuando:
- Has instalado un nuevo plugin de formularios o añadido un formulario nuevo.
- Has añadido nuevos campos personalizados a los productos o usuarios de WooCommerce.
- Llega un evento form.submitted pero falta un campo en el desplegable de mapeo.
Para actualizar: abre la página de administración del plugin → Ajustes → Actualizar esquema. El plugin vuelve a analizar la instalación y envía el esquema actualizado a /onboarding/initiate en mode=connect. Los mapeos existentes se conservan; solo aparecen como "pendiente de mapear" los campos nuevos.
Solución de problemas
1. "Error de conexión" en la primera conexión
- Comprueba que la clave API empiece por sk_live_ (no debe ser una clave sk_test_ — esas rechazan /sync).
- Comprueba que api.flowgration.com sea accesible desde el servidor WP: curl -I https://api.flowgration.com/health. Los servidores con un cortafuegos de salida restrictivo deben permitir HTTPS saliente a *.flowgration.com.
- Vuelve a pegar la clave (los espacios en blanco son una causa frecuente).
2. Los envíos de formularios no aparecen
- Abre Ajustes → Filtro de formularios del plugin. Es posible que el formulario esté excluido por ID. Vacía la lista de exclusión para capturarlo todo.
- Verifica que el plugin de formularios esté en la lista compatible de arriba. Los plugins de formularios poco comunes no se capturan automáticamente — usa la API de Eventos para enviarlos.
- Revisa el mapeo del formulario en /app/integrations. Si no hay campos mapeados, el evento se descarta en el servidor.
3. Los pedidos no se sincronizan
- Confirma que WooCommerce está activo, no solo instalado.
- Abre Plugin → Eventos. El toggle Pedidos debe estar activado.
- Haz una prueba manual: realiza un pedido de prueba con la pasarela de prueba de WC. El evento debería aparecer en /app/integrations → <tienda> → Eventos en 30 s.
4. La página de administración del plugin está en blanco
- Un error de JS está interrumpiendo el renderizado. Revisa wp-content/debug.log (activa WP_DEBUG_LOG si es necesario) y la consola del navegador.
- La causa más frecuente es que el middleware de nonce de otro plugin haya eliminado nuestro nonce de sub-administración. Desactiva los plugins uno a uno para identificar el culpable.
- Como último recurso, establece define('FLOWGRATION_LEGACY_NONCE', true) en wp-config.php para volver al path de nonce del núcleo de WP.
5. "No se ha podido autenticar con Flowgration" después de semanas funcionando
- La clave API fue revocada desde /app/api-keys. Vuelve a generarla y pega el nuevo valor en el plugin.
- El plan de la organización se degradó a un nivel que desactiva los plugins (Free → sin acceso a plugins).
6. El heartbeat muestra "detenido" durante más de 24h
- El cron de WP está desactivado en esta instalación (DISABLE_WP_CRON=true en wp-config.php, o un servidor que usa cron real).
- Vacía la cola manualmente: wp cron event run flowgration_cron_queue.
- Si usas cron real, asegúrate de que llama a wp-cron.php al menos cada 5 minutos.
7. WooCommerce Subscriptions no se sincroniza
- Confirma que el plugin WooCommerce Subscriptions está activo — el WC integrado no tiene objetos de suscripción.
- Abre Plugin → Eventos y activa el toggle Suscripciones. Por defecto está desactivado porque la mayoría de las tiendas no lo usan.
8. La clave cifrada aparece como "no conectada" tras rotar las sales de wp-config
- El plugin cifra la clave API con una clave derivada de AUTH_KEY + SECURE_AUTH_KEY. Rotar las sales de WP invalida el texto cifrado.
- Vuelve a pegar la clave API en el plugin. El nuevo texto cifrado usa las nuevas sales.
9. Multisitio — «no funciona entre sitios»
- El multisitio no está soportado en v1. El plugin solo se activa en el sitio principal de la red; los subsitios no hacen nada en silencio.
- Solución alternativa: instala por subsitio activando manualmente en cada uno. Cada subsitio necesita su propia clave API.
10. El plugin ralentiza el proceso de pago
- Los eventos se ponen en cola, no se envían en línea — las peticiones de pago regresan antes de que ocurra la sincronización. Si ves lentitud, analiza con Query Monitor: casi siempre es otro plugin.
- El único trabajo del plugin en el momento del pago es un único wp_insert_post en el CPT flowgration_queue (~5ms).
Privacidad y datos
Qué sale de tu instalación de WP
- Solo los eventos indicados en Qué se sincroniza, más los campos que el comerciante haya mapeado explícitamente.
- Sin comentarios, sin contenido de entradas, sin archivos multimedia, sin emails de administrador más allá del del administrador que realizó la conexión.
Dónde van
Frankfurt, EU (AWS eu-central-1). Fráncfort, UE (AWS eu-central-1). Los datos nunca salen de la UE en operación normal.
Retención
Los eventos viven en PluginEventLog durante 90 días y después se agregan. Los datos de Contacto persisten hasta que elimines el contacto o desinstales la integración.
RGPD
Un administrador de WordPress puede solicitar la exportación o supresión de datos de cualquier usuario desde /app/contacts. La supresión se propaga de vuelta a WP en el siguiente ciclo de sincronización (el wp_user_meta del usuario se borra si se concedió el consentimiento data_write).Desinstalar
Desde el admin de WP
- Desactivar detiene el envío de eventos pero conserva la clave cifrada en wp_options. Vuelve a activar para reanudar.
- Eliminar borra los archivos del plugin, las filas del CPT flowgration_queue y la clave cifrada. Los datos ya sincronizados en Flowgration no se modifican.
Desde Flowgration
- /app/integrations → Abre /app/integrations → Desconectar.
- Marca la fila PluginIntegration como disconnected.
- Revoca la clave API.
- Los contactos, pedidos y actividades sincronizados se conservan. Para eliminarlos, borra también los contactos.
La reinstalación es idempotente: el siguiente /onboarding/initiate en mode=connect hace upsert sobre la misma fila PluginIntegration, conservando la configuración de mapeo.